Atoll 3.2.1 Task Automation Guide PDF

Version 3.2.
Task Automation Guide
AT321_TAG_E4
AT321_TAG_E4
Atoll 3.2.1 Task Automation Guide
Release: AT321_TAG_E4 (October 2014)
© Copyright 1997‐2014 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.
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.
Atoll 3.2.1 Task Automation Guide © 2014 Forsk
4
AT321_TAG_E4 Table of Contents
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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
3.3 get_Parent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
3.4 get_Active . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
3.5 put_Active . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
3.6 get_Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
3.7 get_Name. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
3.8 get_FullName. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
3.9 get_Path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
3.10 get_ActiveDocument. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
3.11 get_WindowStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
3.12 put_WindowStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
3.13 put_StatusBar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
3.14 get_Visible . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
3.15 put_Visible . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
3.16 get_Version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
3.17 Quit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
3.18 LogMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
3.19 CreatePropertyContainer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
5
Table of Contents © Forsk 2014
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 Application Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .42
3.29.1 WillQuitApp. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .42
3.29.2 DocumentOpenComplete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43
3.29.3 WillCloseDocument . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43
3.29.4 WillSaveDocument . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43
3.29.5 DocumentSaveComplete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43
3.29.6 DocumentNewComplete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43
3.29.7 WillRefreshDocument . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .44
3.29.8 RefreshDocumentComplete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .44
3.29.9 WillArchiveDocument. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .44
3.29.10 ArchiveDocumentComplete. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .44
3.29.11 WillRun . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .44
3.29.12 RunComplete. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45
3.29.13 LicenceAcquireComplete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45
3.29.14 LicenceReleaseComplete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .46
3.29.15 WillNewDocumentFromDatabase. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .55
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.6 get_Path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .62
5.7 get_ReadOnly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .62
5.8 get_Saved . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .62
6
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
5.46 get_DatabaseSchemaString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
5.47 get_DisplayApplicationDialogues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
5.48 put_DisplayApplicationDialogues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
7
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
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
7 Zones and Predictions Tabular Data Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .97
7.1 Zones Tabular Data Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .97
7.2 Predictions Tabular Data Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .98
8 CoordSystem Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

8.1 How to Access a CoordSystem Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
8
8.2 Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
8.3 ConvertCoordsTo. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
8.4 Datum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
8.5 DatumName. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
8.6 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
8.7 Ellipsoid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
8.8 EllipsoidName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
8.9 Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
8.10 Pick . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
8.11 ProjMethod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
8.12 ProjParameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
8.13 SetDatum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
8.14 SetProjection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
8.15 Unit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
9 ChildFolder Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
9.1 How to Access a ChildFolder Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
9.2 get_Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
9.3 get_Parent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
9.4 get_Name. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
9.5 put_Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
9.6 get_Count. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
9.7 get_Item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
9.8 get__NewEnum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
9.9 get_Visible . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
9.10 put_Visible . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
9.11 get_Selected . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
9.12 put_Selected . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
9.13 Export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
9.14 CentreOnMap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
9.15 Redraw . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
9.16 AddChild . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
9.17 Remove. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
9.18 get_position . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
9.19 put_position. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
9.20 get_Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
9.21 get_dispatch. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
9.22 get_ObjectKind . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
9.23 GetProperty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
9.24 SetProperty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
9
9.25 GetPropertiesInfo. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
9.26 PropertyIsPropertyContainer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
9.27 PropertyIsTabularData. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
9.28 LoadProperties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
9.29 SaveProperties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
9.30 RemoveItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
9.31 SetCustomIcon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
9.32 OpenPropertySheet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
10 PropertyContainer Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

10.1 Get. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
10.2 Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
10.3 GetInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
10.4 IsPropertyContainer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
10.5 IsTabularData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
10.6 Load. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
10.7 Save . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
10.8 RemoveAll. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
10.9 Remove . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
11 ChildFolder Object Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

11.1 How to Access ChildFolder Object Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
11.2 Common ChildFolder Object Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
11.3 Predictions Folder Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
11.4 Coverage Prediction Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

11.4.1 General Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
11.4.2 Group, Filter, and Sort Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
11.4.3 Non‐Simulation‐based Coverage Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
11.4.4 Simulation‐based Coverage Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
11.4.5 Shadowing and Indoor Coverage Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
11.4.6 Display Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
11.5 GSM Simulation Group Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
11.6 UMTS Simulation Group Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
11.7 WiMAX and LTE Simulation Group Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
11.8 3GPP Multi‐RAT Simulation Group Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
11.9 Propagation Model Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
11.10 CW Measurement Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
11.11 Drive Test Data Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
11.12 Custom ChildFolder Object Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
11.13 Master Link Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
11.14 Link Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
11.15 Vector Layer Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150

11.15.1 Display Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
11.16 User Density Traffic Map Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
10
12 ChildFolder Feature Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157

12.1 Clutter Feature Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
12.1.1 How to Access the Clutter Feature Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
12.1.2 get_Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
12.1.3 get_ClassAttributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
12.1.4 get_DefaultAttributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
12.1.5 Accessing Clutter Class Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
12.2 Traffic Feature Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160

12.2.1 How to Access the Traffic Feature Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
12.2.2 get_Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
12.2.3 get_ScenarioProvider. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
12.2.4 ExportCumulatedTraffic. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
12.2.5 HasTrafficForService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
12.3 UMTS Traffic Scenario Provider Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163

12.3.1 GetMeanSize. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
12.3.2 Create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
12.4 Environment Based Traffic Map Feature Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165

12.4.1 How to Access Environment Based Traffic Map Feature Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
12.4.2 get_Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
12.4.3 get_ClassAttributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
12.4.4 get_DefaultAttributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
12.4.5 Accessing Environment Based Traffic Maps Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
12.5 Simulation Feature Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167

12.5.1 How to Access Simulation Feature Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
12.5.2 get_Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
12.5.3 get_Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
12.5.4 get_Cells . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
12.5.5 get_Sites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
12.5.6 get_Mobiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
12.5.7 get_Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
12.6 Simulation Group Feature Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170

12.6.1 How to Access Simulation Group Feature Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
12.6.2 get_Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
12.6.3 get_Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
12.6.4 get_MeanSimulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
12.6.5 get_StdDevSimulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
12.6.6 Accessing Mobiles, Cells, Sites, for Simulations and Simulation Groups. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
12.7 3GPP Multi‐RAT Simulation Group Feature Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177

12.7.1 get_Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
12.7.2 get_Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
12.7.3 get_MeanSimulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
12.7.4 get_StdDevSimulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
12.8 GSM Interference Matrix Feature Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179

12.8.1 How to Access GSM Interference Matrix Feature Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
12.8.2 get_Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
12.8.3 Load . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
12.8.4 CompleteScopeInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
12.8.5 get_Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
12.8.6 put_Active. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
12.8.7 get_Active . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
12.8.8 get_Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
12.8.9 put_Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
12.8.10 get_BasedOnTraffic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
12.8.11 put_BasedOnTraffic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
12.8.12 get_Resolution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
12.8.13 put_Resolution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
12.8.14 get_StdDev . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
12.8.15 put_StdDev . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
12.8.16 get_InfoQuantityIndicator. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
12.8.17 put_InfoQuantityIndicator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
12.8.18 get_CdfTab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
11
13 Document Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189

13.1 How to Invoke a Document Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
13.2 IMPORTXML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190
13.3 EXPORTXML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
13.4 APPENDTABLECOLUMN. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
13.5 CALCULATEPOINTS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
13.6 IMPORTTESTMOBILEDATA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
13.7 RUNNEIGHBOURALLOCATION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
13.8 RUNINTERTECHNOLOGYNEIGHBOURALLOCATION. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
13.9 RUNINTRACARRIERNEIGHBOURALLOCATION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
13.10 RUNINTERCARRIERNEIGHBOURALLOCATION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
13.11 CLONESTUDY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
13.12 DUPLICATESTUDY. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
13.13 COMPARESTUDY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
13.14 CALCULATEEQUIPMENTLOSSES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
13.15 CALCULATEREPEATERS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
13.16 CALCULATEREMOTEANTENNAS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
13.17 EXPORTACTIVESETANALYSIS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
13.18 CALCULATEPOINTSECI0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
13.19 RUNALLCARRIERSALLOCATION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
13.20 RUNMASTERCARRIERALLOCATION. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
13.21 MWRun . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
13.22 EXPORTMAPWINDOW. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
13.23 IMPORTPLANETDATAFILE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
13.24 EXPORTMWLINKANALYSISPROFILEPICTURE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
13.25 GETPOWERMODE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
13.26 SETPOWERMODE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
13.27 APPENDVECTORDATACOLUMN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
13.28 LOADSAVEPRINTSETUP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
13.29 CALCULATEPATHLOSS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
13.30 MWLinksCustomExport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
13.31 ARCHIVETODATABASE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
14 Enumerations, Structures, and Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225

14.1 Enumerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
14.1.1 Atoll Type Library Enumerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
14.1.1.1 AtoSaveStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
14.1.1.2 AtoSaveChanges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
14.1.1.3 AtoRefreshPriority. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
14.1.1.4 AtoArchiveStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
14.1.1.5 AtoWindowStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
14.1.1.6 AtoLogType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
14.1.1.7 AtoCompareOp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
14.1.1.8 AtoTransmissionUnit. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
12
14.1.1.9 AtoReceptionUnit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226

14.1.1.10 AtoDistanceUnit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
14.1.1.11 AtoRadiatedPowerUnit. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
14.1.1.12 AtoAntennaGainUnit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
14.1.1.13 AtoHeightOffsetUnit. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
14.1.1.14 AtoRootType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
14.1.1.15 AtoRowFilter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
14.1.1.16 AtoRowStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
14.1.1.17 AtoTemperatureUnit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
14.1.2 FSKGISLib Type Library Enumerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
14.1.2.1 GeographicUnit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
14.1.2.2 ProjectionMethod. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
14.1.2.3 ProjParameterIndices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
13
14
Chapter 1
Getting Started
Atoll 3.2.1 Task Automation Guide © Forsk 2014
16
AT321_TAG_E4 Chapter 1: Getting Started
1 Getting Started
Atoll provides a set of programmable extensions enabling users to enhance the already rich functionalities available in 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 interaction 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
Set myapp = CreateObject("Atoll.Application")
WScript.ConnectObject myapp, "Atoll_"
17
Chapter 1: Getting Started © Forsk 2014
myapp.Visible = False
Set doc = myapp.Documents.OpenFromDatabase(

"Provider=SQLOLEDB.1;UserID=myNameName;Password=myPwd;InitialCatalog=myA-
tollDbName;Data Source=myServer;", "")
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
You must replace all the parameters beginning with "my" with your own values in the above connection string. This script:
1. Starts an invisible Atoll 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.
To open the Windows Task Scheduler:
1. Select Start > Settings > Control Panel. The Control Panel opens.
2. Double‐click the Scheduled Tasks icon.
18
3. Double‐click the Add Scheduled Task icon. The Scheduled Taks Wizard opens.
4. Click Next.
Figure 1.1: Scheduled Tasks Wizard
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.
19
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.
Figure 1.4: Atoll Tutorial
14. Set account information if needed.
15. Click OK. Your task will be displayed in the Scheduled Tasks window:
Figure 1.5: Scheduled Tasks
To modify the task properties:
1. Right‐click the Atoll Tutorial task. The context menu opens.
2. Select Properties from the context menu.
20
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:
wscript tutorial.vbs //X
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:
Myapp.Visible = True
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:
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
21
End If
If IsObject(myapp) Then
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;UserID=myName;Password=myPwd;InitialCatalog=myAtollDb-
Name;DataSource=myServer;", "")
If Err Then Call CatchError End If
doc.Run True
var = 0
Do While var = 0
WScript.Sleep 1000
Loop
doc.Save("C:\mydoc.atl")
WScript.DisconnectObject myapp
doc = Null
22
myapp.Quit atoSaveNo
myapp = Null
WScript.Quit 0
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 an Atoll Application object is automatically added as a script‐level vari‐
able 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:
mydoc = Atoll.ActiveDocument
The script‐level variable name for the Atoll Application object is "Atoll" and it is optional. So, the above line is equivalent to:
mydoc = ActiveDocument
Macros can also be invoked in response to application events.
Example
Sub Atoll_DocumentSaveComplete(doc)
LogMessage "Archive on save running ..."
Dim status
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
LogMessage "Archive on save completed successfully."
23
End If
End If
End Sub
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:
Public Sub Main
End Sub
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.
Figure 1.6: Adding Macros in Atoll
To associate an icon file to a macro:
1. Under Macros, select the macro in the list of macros.
2. Click the Icon button.
24
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:
Function Atoll_WillRun(doc, success)
doc.Save
Atoll_WillRun = False ‘ Intercepts the run order and cancels
‘ it by returning False
End 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:
Both 32-bit and 64-bit

Only 32-bit Atoll installed Only 64-bit Atoll installed
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

the script 32-bit Atoll is launched 64-bit Atoll is launched 64-bit Atoll is launched
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.
25
26
Chapter 2
Object Model
28
AT321_TAG_E4 Chapter 2: Object Model
2 Object Model
This chapter describes the Atoll object model. Figure 2.1 on page 29 provides an overview of the Atoll object model.
Application
Documents
Document 1 Document 2 PropertyContainer 1

TabularData 1 TabularData 1
PropertyContainer 2
TabularData 2 TabularData 2
ChildFolder 1 ChildFolder 1
ChildFolder 2 ChildFolder 2
CoordSystem CoordSystem
Figure 2.1: 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:
Name Description
The Application object provides an entry point for clients to retrieve and
Application Object
navigate through the Atoll object model.
The Documents object is used to create a new document or to iterate
Documents Object
through open documents in an Atoll session.
The Doc ument object provides access to ATL documents and database
Document Object
connections.
The TabularData object provides access to Atoll tables whether an Atoll
TabularData Object 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.
The PropertyContainer object is a generic container containing a set of
PropertyContainer Object
named properties of arbitrary types
The Transmitter object provides read‐only access to antenna patterns,
Transmitter Object
antenna losses, and some transmitter properties.
2.1 Interfaces Implemented by Objects
Atoll objects provide access to Atoll components through properties and methods.
29
Chapter 2: Object Model © Forsk 2014
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:
value = object.property ’for reading a property
object.property = value ’for writing a property
For calling a method, you write:
object.method
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
Dim strDescription
If Err Then
strDescription = Err.Description
End If
Please refer to the VBScript Language Reference for more information about VBScript, error handling, and the Err script‐level
variable.
30
Chapter 3
Application Object
32
AT321_TAG_E4 Chapter 3: Application Object
3 Application Object
The Application object provides an entry point for clients to retrieve and navigate through the Atoll object model.
The Application object provides the following properties and methods:
Name Description Attributes
Type: Application object
get_Application Returns the Atoll Application object.
Access: Read
get_Parent Returns the Atoll Application object.
Access: Read
Returns whether the Atoll window is active Type: Boolean
get_Active
or not. Access: Read/Write
Type: Boolean
put_Active Sets the Atoll window active.
Access: Read/Write
Type: Documents object
get_Documents Returns the Documents object.
Access: Read
Returns the application name. The Type: String
get_Name
application name is always "Atoll". Access: Read
Type: String
get_FullName Returns the full path of the executable.
Access: Read
Type: String
get_Path Returns the path of the executable.
Access: Read
Type: Document object
get_ActiveDocument Returns the active document.
Access: Read
Returns the window status of the Atoll Type: Integer
get_WindowStatus
application. Access: Read/Write
Sets the window status of the Atoll Type: Integer
put_WindowStatus
application. Access: Read/Write
Sets the status bar text of the Atoll Type: String
put_StatusBar
application. Access: Write
Type: Boolean
get_Visible Returns the application visible state.
Access: Read/Write
Type: Boolean
put_Visible Sets the application visible state.
Access: Read/Write
Type: String
get_Version Returns the application version.
Access: Read
Quit Quits the application.
Displays a message in the Atoll event
LogMessage
observer window.
CreatePropertyContainer Returns an empty PropertyContainer object.
Returns the full path to the Atoll initialisation Type: String
get_IniFileFullPath
file. Access: Read/Write
Sets the full path to the Atoll initialisation Type: String
put_IniFileFullPath
file. Access: Read/Write
Returns an option read from the Atoll
GetOption
initialisation file.
SetOption Sets an option in the Atoll initialisation file.
33
Chapter 3: Application Object © Forsk 2014
Suspends the application apartment
Sleep
execution.
The Application object fires the following events:
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.
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:
Set app = CreateObject("Atoll.Application")
Because Atoll registers itself in the Running Objects Table when an Atoll session is running, you can use:
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.
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".
3.2 get_Application
Returns the Atoll Application object.
34
HRESULT get_Application(IApplication **ppVal);
Parameters
[out] ppVal: Address of the IApplication interface pointer used to return the Atoll Application object.
3.3 get_Parent
HRESULT get_Parent(IApplication **ppVal);
Parameters
3.4 get_Active
Returns whether the Atoll window is active or not.
HRESULT get_Active(VARIANT_BOOL *pVal);
Parameters
[out] pVal: Address of the VARIANT_BOOL used to return whether the Atoll windows application is active or not.
Example
Dim app
Dim act
act = app.Active
app.Active = True
3.5 put_Active
Sets the main application window active.
HRESULT put_Active(VARIANT_BOOL aNewVal);
Parameters
[in] aNewVal:
• VARIANT_TRUE: Activates the main window application.
Example
See "get_Active" on page 35.
3.6 get_Documents
Returns the Documents object.
35
HRESULT get_Documents(IDocuments **ppDocVal);
Parameters
[out] ppDocVal: Address of the IDocuments interface pointer used to return the Documents object.
Example
Dim app
Dim docs
Set docs = app.Documents
3.7 get_Name
Returns the application name. The application name is always "Atoll".
HRESULT get_Name(BSTR *pVal);
Parameters
[out] pVal: Address of the BSTR used to return the application name.
3.8 get_FullName
Returns the full path of the executable.
HRESULT get_FullName(BSTR *pVal);
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.
HRESULT get_Path(BSTR *pVal);
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".
3.10 get_ActiveDocument
Returns the active document.
36
HRESULT get_ActiveDocument(IDocument **ppDocVal);
Parameters
[out] ppDocVal: Address of the IDocument interface pointer used to return the Document object.
Example
Dim app
Dim doc
Set doc = app.ActiveDocument
3.11 get_WindowStatus
Returns the window status of the Atoll application.
HRESULT get_WindowStatus(enum AtoWindowStatus *pVal);
Parameters
[out] pVal: Address of the AtoWindowStatus enumeration used to return the window status.
Example
Dim app
Dim status
status = app.WindowStatus
Const atoMinimized = 2
app.WindowStatus = atoMinimized
3.12 put_WindowStatus
Sets the window status of the Atoll application.
HRESULT put_WindowStatus(enum AtoWindowStatus aNewVal);
Parameters
[in] newVal: The window status.
Example
See "get_WindowStatus" on page 37.
3.13 put_StatusBar
Sets the status bar text of the Atoll application.
37
HRESULT put_StatusBar(const BSTR bstrNewVal);
Parameters
[in] bstrNewVal: The text to display in the status bar.
Example
Dim app
app.StatusBar = “This is my message”
3.14 get_Visible
Returns the application visible state.
HRESULT get_Visible(VARIANT_BOOL *pVal);
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.
HRESULT put_Visible(VARIANT_BOOL aNewVal);
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 get_Version(BSTR *pVal);
Parameters
[out] pVal: Address of the BSTR used to return the version.
38
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.
HRESULT Quit(enum AtoSaveChanges aSaveChanges, enum AtoSaveStatus *pStatus);
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.
3.18 LogMessage
Displays a message in the Atoll event observer window.
HRESULT LogMessage(const BSTR bstrMsg, enum AtoLogType aLogtype = atoInfo);
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.
:
4.
5.
:
3.19 CreatePropertyContainer
Returns an empty PropertyContainer object.
HRESULT CreatePropertyContainer(VARIANT *pProperties)
Parameters
[out] pProperties: Address of the VARIANT used to return the empty PropertyContainer object.
39
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.
HRESULT get_IniFileFullPath(BSTR *pVal);
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.
HRESULT put_IniFileFullPath(BSTR bstrFile);
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.
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.
HRESULT GetOption(BSTR bstrSection, BSTR bstrOption, VARIANT *pVal);
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.
40
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.
HRESULT SetOption(BSTR bstrSection, BSTR bstrOption, VARIANT varValue);
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.
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.
HRESULT Sleep(long lMilliseconds);
Parameters
[in] lMilliseconds : A long integer used to specify the time, in milliseconds, to sleep.
Example
’Sleep 5 seconds
Atoll.Sleep 5000
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 SetAddinInfoEx(
LONGLONG hInstance,
LPDISPATCH dispatch,
long idr,
long cookie
);
41
Parameters
3.26 put_OLENotRespondingDialog
Enables or disables OLE not responding dialog.
HRESULT put_OLENotRespondingDialog(VARIANT_BOOL newVal);
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.
HRESULT put_OLEBusyDialog(VARIANT_BOOL newVal);
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.
HRESULT put_OLEMessagePendingDelay(LONG newVal);
Parameters
[in] newVal: A LONG integer used to specify the OLE message pending delay.
3.29 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,
• When a document has been archived in database,
• When a 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.29.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.
42
HRESULT WillQuitApp(VARIANT_BOOL* evtStatus);
Parameters
[out] evtStatus: A VARIANT_BOOL pointer used to return whether Atoll is allowed to quit (VARIANT_TRUE) or not
(VARIANT_FALSE).
3.29.2 DocumentOpenComplete
Event fired when a document has been opened.
HRESULT DocumentOpenComplete(IDocument* document);
Parameters
[in] document: The IDocument interface pointer of the document object which has been opened.
3.29.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...).
HRESULT WillCloseDocument(IDocument* document, VARIANT_BOOL* evtStatus);
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.29.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.
HRESULT WillSaveDocument(IDocument* document, VARIANT_BOOL* evtStatus);
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.29.5 DocumentSaveComplete
Event fired just after a document has been saved.
HRESULT DocumentSaveComplete (IDocument* document);
Parameters
[in] document: The IDocument interface pointer of the document which has been successfully saved.
3.29.6 DocumentNewComplete
Event fired when a new document has been created.
43
HRESULT DocumentNewComplete(IDocument* document);
Parameters
[in] document: The IDocument interface pointer of the document which has been created.
3.29.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.
HRESULT WillRefreshDocument(IDocument* document, VARIANT_BOOL* evtStatus);
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.29.8 RefreshDocumentComplete
Event fired when a document has been refreshed from database.
HRESULT RefreshDocumentComplete(IDocument* document);
Parameters
[in] document: The IDocument interface pointer of the document which has been refreshed.
3.29.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.
HRESULT WillArchiveDocument(IDocument* document, VARIANT_BOOL* evtStatus);
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.29.10 ArchiveDocumentComplete
Event fired when the document has been archived in database. It occurs just before the connection with the database is
broken.
HRESULT ArchiveDocumentComplete(IDocument* document);
Parameters
[in] document: The IDocument interface pointer of the document which has been archived.
3.29.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.
44
HRESULT WillRun(
IDocument* document,
VARIANT_BOOL all,
VARIANT_BOOL* evtStatus
);
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.29.12 RunComplete
Event fired when the calculation has finished. It occurs after all tasks have completed.
HRESULT RunComplete(IDocument* document, VARIANT_BOOL succeeded);
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 calculation might result in 3 RunComplete events, one for LTE, one for UMTS,
and one for GSM matrices.
3.29.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 LicenceAcquireComplete(
IDocument *pDocument,
long lModuleID
);
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.
45
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:
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;
3.29.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.
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
46
• LICENCE_MW
• LICENCE_PACK3G
• LICENCE_UMTS
• LICENCE_CDMA
• LICENCE_TDSCDMA
• LICENCE_WIMAX
• LICENCE_LTE
3.29.15 WillNewDocumentFromDatabase
 3.2.0
Fired just before a new document is created from an existing database.
HRESULT WillNewDocumentFromDatabase(
BSTR connexion,
BSTR schema,
VARIANT_BOOL *pEvtStatus
);
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).
47
48
Chapter 4
Documents Object
50
AT321_TAG_E4 Chapter 4: Documents Object
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:
Returns the number of currently open documents in an Type: Integer
get_Count
Atoll session. Access: Read
Type: Documents
get_Item Returns one document currently open in an Atoll session. object
Access: Read
Type: Application
get_Application Returns the Atoll application object. object
Access: Read
Type: Application
get_Parent Returns the Atoll application object. object
Access: Read
Opens an existing document and adds it to the collection of
Open
open documents.
Creates a new document and adds it to the collection of
Add
open documents.
Creates a new document from a database and adds it to
OpenFromDatabase
the collection of open documents.
CloseAll Closes all open documents.
SaveAll Saves all open documents.
4.1 How to Access a Documents Object
To access a Documents object:
Dim allDocs
Set allDocs = Atoll.Documents
The "For Each" VBScript statement can be used with the Documents collection object:
Dim allDocs
Dim doc
Set allDocs = Atoll.Documents
For Each doc In allDocs
‘ do some work with doc
‘...
Next
51
Chapter 4: Documents Object © Forsk 2014
4.2 get_Count
Returns the number of currently open documents in an Atoll session.
HRESULT get_Count(LONG *pVal);
Parameters
[out] pVal: A LONG pointer used to return the number of open documents.
Example
Dim nDocs
nDocs = Atoll.Documents.Count
4.3 get_Item
Returns one document currently open in an Atoll session.
HRESULT get_Item(const VARIANT vIdx, IDocument **ppDoc);
Parameters
[in] vIdx: A VARIANT of type VT_I4 or VT_BSTR identifying the returned document. A variant of type VT_I4 is interpreted as a
zero‐based index in the documents collection. A variant of type VT_BSTR is interpreted as the name of a document.
[out] ppDoc: Address of the IDocument interface pointer used to return the Atoll document object.
Remarks
The name of a document is the document file name, as returned by get_Name().
4.4 get_Application
Returns the Atoll application object.
Parameters
[out] ppVal: Address of the IApplication interface pointer used to return the Atoll application object.
4.5 get_Parent
Returns the Atoll application object.
HRESULT get_Parent(IApplication **ppVal);
Parameters
[out] ppVal: Address of the IApplication interface pointer used to return the Atoll application object.
4.6 Open
Opens an existing document and adds it to the collection of open documents.
52
HRESULT Open(const BSTR bstrPathName, VARIANT_BOOL aReadOnly, IDocument

**pDoc);
Parameters
[in] bstrPathName: The absolute path of the document to open.
[in] readOnly: VARIANT_TRUE means the document will be opened in read‐only mode. VARIANT_FALSE means the document
will be opened in read‐write mode.
[out] pDoc: Address of the IDocument interface pointer used to return the open Document object.
Example
Dim doc
Set doc = app.Documents.Open(“C:\Temp\myProject.atl”)
4.7 Add
Creates a new document and adds it to the collection of open documents.
HRESULT Add(BSTR templateName, IDocument **pDoc);
Parameters
[in] templateName: The name of an Atoll template.
[out] pDoc: Address of the IDocument interface pointer used to return the new Document object.
Example
Dim doc
Set doc = app.Documents.Add(“UMTS”)
4.8 OpenFromDatabase
Creates a new document from a database and adds it to the collection of open documents.
HRESULT OpenFromDatabase(VARIANT connection, BSTR schema, IDocument **pDoc);
Parameters
[in] connection: A VARIANT of type VT_BSTR or VT_UNKNOWN. If the variant is of type VT_BSTR, it is interpreted as the
connection string of the database you want to connect to. If the variant if of type VT_UNKNOWN, it is interpreted as an ADODB
connection interface pointer. Please read the Microsoft documentation about ADOX interfaces.
[in] schema: The name of the database schema, in case of databases supporting muti‐schema based definition. The syntax of
the schema string is:
PropertyName = Value[;PropertyName = Value]
Available properties are:
Property Name Value Version Description
Project string  2.6.0 Database schema
53
Keep Connection 0|1  2.6.0 Whether to keep connection with the database or not
group name
Field Groups  2.6.0 Comma separated values of field groups
[,group name]
Site Lists site list[,site list]  2.6.0 Comma separated values of site lists
IntraTechnology
0|1  2.6.1 Whether to load the table "NEIGHBOURS" or not
Neighbours
InterTechnology
0|1  2.6.1 Whether to load the table "NEIGHBOURSEXT" or not
Neighbours
Comma separated values of systems.
When creating a new document from a 3GPP Multi‐RAT
database, it is used to specify the radio access technologies
to load.
Available values for systems are:
Systems system,[system]  3.1.2
GSM
UMTS
LTE
When no property named "Systems" is specified in the
schema string, all radio technologies are loaded.
[out] pDoc: Address of the IDocument interface pointer used to return the new Document object.
Remarks
A dialogue box is displayed to enter the schema properties in the these cases:
a. When schema is NULL, or schema is equal to the string constant "0".
b. When a project is specified, and when no site lists are specified in the schema parameter.
No dialogue box is displayed when a project is specified, and when the site lists property of the schema parameter is set to
"<ALL>". In this case, all sites are loaded from the database.
Example
Creating a new document from a MS Access database:
Public Sub OpenMSAccessDatabase

conn = "Provider=Microsoft.Jet.OLEDB.4.0;Data Source=C:\myproject.mdb"
Atoll.Documents.OpenFromDatabase conn, ""
End Sub
Creating a new document from a database, specifying a site list to load:
Public Sub OpenSiteList

conn = "Provider=Microsoft.Jet.OLEDB.4.0;Data Source=C:\myproject.mdb"
Atoll.Documents.OpenFromDatabase conn, "Site Lists=MySiteList"
End Sub
Creating a new document from an Oracle database, with no dialogue box:
54
Public Sub OpenOracleDatabase

provider = "Provider=OraOLEDB.Oracle.1;"
username = "User ID=MyUserName;"
password = "Password=MyPassword;"
server = "Data Source=MyServer"
project = "Project=MyProject;"
conn = provider & username & password & server
sitelists = ";Site Lists=<ALL>"
schema = project & sitelists
Atoll.Documents.OpenFromDatabase conn, schema
End Sub
Creating a new document from a 3GPP Multi‐RAT Oracle database, loading LTE and UMTS information only:
Public Sub OpenLTEAndUMTSFromOracleDatabase

provider = "Provider=OraOLEDB.Oracle.1;"
username = "User ID=MyUserName;"
password = "Password=MyPassword;"
server = "Data Source=MyServer"
project = "Project=MyProject;"
conn = provider & username & password & server
sitelists = ";Site Lists=<ALL>"
technologies = ";Systems=LTE,UMTS"
schema = project & sitelists & technologies
Atoll.Documents.OpenFromDatabase conn, schema
End Sub
4.9 CloseAll
Closes all open documents.
HRESULT CloseAll(AtoSaveChanges saveChanges, AtoSaveStatus *status);
Parameters
[in] saveChanges:
• atoSaveNo: Discards document changes, then closes all open documents.
• atoSaveYes: Saves document changes, then closes all open documents.
• atoSavePrompt: The user is prompted to save document changes, then all open documents are closed.
[out] status: 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.
4.10 SaveAll
Saves all open documents.
HRESULT SaveAll();
55
56
Chapter 5
Document Object
58
AT321_TAG_E4 Chapter 5: Document Object
5 Document Object
The Doc ument object provides access to ATL documents and database connections. A document can be managed (open, save,
close, etc.) using its properties and methods. A document is also the main entry to manage all the data it contains.
The Document object provides the following properties and methods:
Type: Application
get_Application Returns the Atoll Application Object. object
Access: Read
Type: Documents
get_Parent Returns the Atoll Documents collection. object
Access: Read
Type: String
get_FullName Returns the document full path.
Access: Read
Type: String
get_Name Returns the document file name without the extension.
Access: Read
Type: String
get_Path Returns the document path.
Access: Read
Type: Boolean
get_ReadOnly Returns true if the document is read‐only, false otherwise.
Access: Read
Returns false if the document contains unsaved changes, Type: Boolean
get_Saved
true otherwise. Access: Read
Type: CoordSystem
get_CoordSystemProjection Returns the projection coordinate system of a document. object
Access: Read/Write
Type: CoordSystem
putref_CoordSystemProjection Sets the projection coordinate system of a document. object
Access: Read/Write
Type: CoordSystem
get_CoordSystemDisplay Returns the display coordinate system of a document. object
Access: Read/Write
Type: CoordSystem
putref_CoordSystemDisplay Sets the display coordinate system of a document. object
Access: Read/Write
Type: CoordSystem
get_CoordSystemInternal Returns the internal coordinate system of a document. object
Access: Read
Type: Integer
get_TransmissionUnit Returns the transmission power unit.
Access: Read/Write
Type: Integer
put_TransmissionUnit Sets the transmission power unit.
Access: Read/Write
Type: Integer
get_ReceptionUnit Returns the signal level reception unit.
Access: Read/Write
Type: Integer
put_ReceptionUnit Sets the signal level reception unit.
Access: Read/Write
Type: Integer
get_DistanceUnit Returns the display distance unit.
Access: Read/Write
Type: Integer
put_DistanceUnit Sets the display distance unit.
Access: Read/Write
59
Chapter 5: Document Object © Forsk 2014
Close Closes a document.
FilePrint Sends a document to a printer.
Save Saves a document.
Refresh Refreshes the document from a database.
Archive Archives the document in a database.
Run Starts calculations.
SetConfig Loads a configuration file.
Import Loads a file containing geographic data.
Returns a TabularData object for a requested category of
GetRecords
records.
Redraw Refreshes all items in the document.
CenterMapOn Centres map on a parameter point.
Returns the root ChildFolder object used to enumerate all
GetRootFolder ChildFolder objects belonging to one tab of the Atoll
explorer window.
Calculates the path loss matrices with no need for any
RunPathloss
predefined studies.
GetService Returns a Document Service Object.
Exports a subset of the current document configuration to a
ExportConfig
file.
GetCommandDefaults Returns current default parameters specific to a command.
InvokeCommand Invokes a command.
Type: Integer
get_RadiatedPowerUnit Returns the current radiated power unit.
Access: Read/Write
Type: Integer
put_RadiatedPowerUnit Sets the current radiated power unit.
Access: Read/Write
Type: Integer
get_AntennaGainUnit Returns the current antenna gain unit.
Access: Read/Write
Type: Integer
put_AntennaGainUnit Sets the current antenna gain unit.
Access: Read/Write
Type: Integer
get_HeightOffsetUnit Returns the current height offset unit.
Access: Read/Write
Type: Integer
put_HeightOffsetUnit Sets the current height offset unit.
Access: Read/Write
Type: String
get_DatabaseConnectionString Returns the database connection string.
Access: Read/Write
Type: Boolean
HasRunningTask Returns true when there is some calculation in progress.
Access: Read
RunEx Starts calculations.
Type: String
get_DatabaseSchemaString Returns the database schema string.
Access: Read/Write
Returns true when some methods on some Atoll interfaces Type: Boolean
get_DisplayApplicationDialogues
may display some dialogue boxes. Access: Read/Write
60
Returns true when some methods on some Atoll interfaces Type: Boolean
put_DisplayApplicationDialogues
may display some dialogue boxes. Access: Read/Write
Type: String
PutDatabaseSchemaString Sets the database schema string.
Access: Read/Write
Type: String
PutDatabaseConnectionString Sets the database connection string.
Access: Read/Write
Type: String
ChangeDatabaseConnection Changes the database connection string.
Access: Read/Write
5.1 How to Access a Document Object
To access a document, you can either:
1. Request the active document from the application:
Set myDoc = Atoll.ActiveDocument
2. Or, use the Documents object:
Set myDoc = Atoll.Documents.Open(“C:\temp\myproject.atl”)
5.2 get_Application
Returns the Atoll Application Object.
Parameters
[out] ppVal: Address of the IApplication interface pointer used to return the Atoll Application Object.
5.3 get_Parent
Returns the Atoll Documents collection.
HRESULT get_Parent(IDocuments **ppDocVal);
Parameters
[out] ppDocVal: Address of the IDocuments interface pointer used to return the Atoll Documents collection.
5.4 get_FullName
Returns the document full path.
HRESULT get_FullName(BSTR *pVal);
Parameters
[out] pVal: Address of the BSTR used to return the document full path.
61
Remarks
With a new document that has never been saved, or a document opened from a database, an empty string is returned.
5.5 get_Name
Returns the document file name without the extension.
Parameters
[out] pVal: Address of the BSTR used to return the document file name without the extension.
Remarks
5.6 get_Path
Returns the document path.
HRESULT get_Path(BSTR *pVal);
Parameters
[out] pVal: Address of the BSTR used to return the document path.
Remarks
5.7 get_ReadOnly
Returns true if the document is read‐only, false otherwise.
HRESULT get_readOnly(VARIANT_BOOL *pVal);
Parameters
[out] pVal: Address of the VARIANT_BOOL used to return the read‐only status of the document.
5.8 get_Saved
Returns false if the document contains unsaved changes, true otherwise.
HRESULT get_Saved(VARIANT_BOOL *pVal);
Parameters
[out] pVal: Address of the VARIANT_BOOL used to return whether the document contains unsaved changes or not.
5.9 get_CoordSystemProjection
Returns the projection coordinate system of a document.
62
HRESULT get_CoordSystemProjection(IDispCoordSystem **ppVal);
Parameters
[out] ppVal: Address of the IDispCoordSystem interface pointer used to return the projection coordinate system of the docu‐
ment.
5.10 putref_CoordSystemProjection
Sets the projection coordinate system of a document.
HRESULT putref_CoordSystemProjection(IDispCoordSystem *pVal);
Parameters
[in] pVal: Address of the IDispCoordSystem interface pointer used to set the projection coordinate system of the document.
5.11 get_CoordSystemDisplay
Returns the display coordinate system of a document.
HRESULT get_CoordSystemDisplay(IDispCoordSystem **ppVal);
Parameters
[out] ppVal: Address of the IDispCoordSystem interface pointer used to return the display coordinate system of the document.
5.12 putref_CoordSystemDisplay
Sets the display coordinate system of a document.
HRESULT putref_CoordSystemDisplay(IDispCoordSystem *pVal);
Parameters
[in] pVal: Address of the IDispCoordSystem interface pointer used to set the display coordinate system of the document.
5.13 get_CoordSystemInternal
Returns the internal coordinate system of a document.
HRESULT get_CoordSystemInternal(IDispCoordSystem **ppVal);
Parameters
[out] ppVal: Address of the IDispCoordSystem interface pointer used to return the internal coordinate system of the docu‐
ment.
Remarks
When the document is not connected to a database, the internal coordinate system is the same as the display coordinate
system. When the document is connected to a database, the internal coordinate system won’t change when the display coor‐
dinate system is changed. When the document is connected to a database, the internal coordinate system is the display coor‐
dinate system that was in use when the document was archived in the database for the first time.
The coordinates of sites are defined with the internal coordinate system.
63
5.14 get_TransmissionUnit
Returns the transmission power unit.
HRESULT get_TransmissionUnit(enum AtoTransmissionUnit *pVal);
Parameters
[out] pVal: Address of the AtoTransmissionUnit enumeration value used to return the transmission power unit.
5.15 put_TransmissionUnit
Sets the transmission power unit.
HRESULT put_TransmissionUnit(enum AtoTransmissionUnit aNewVal);
Parameters
[in] aNewVal: The AtoTransmissionUnit enumeration value used to specify the transmission power unit.
5.16 get_ReceptionUnit
Returns the signal level reception unit.
HRESULT get_ReceptionUnit(enum AtoReceptionUnit *pVal);
Parameters
[out] pVal: Address of the AtoReceptionUnit enumeration value used to return the signal level reception unit.
5.17 put_ReceptionUnit
Sets the signal level reception unit.
HRESULT put_ReceptionUnit(enum AtoReceptionUnit aNewVal);
Parameters
[in] aNewVal: The AtoReceptionUnit enumeration value used to specify the signal level reception unit.
5.18 get_DistanceUnit
Returns the display distance unit.
HRESULT get_DistanceUnit(enum AtoDistanceUnit *pVal);
Parameters
[out] pVal: Address of the AtoDistanceUnit enumeration value used to return the display distance unit.
5.19 put_DistanceUnit
Sets the display distance unit.
64
HRESULT put_DistanceUnit(enum AtoDistanceUnit aNewVal);
Parameters
[in] aNewVal: The AtoDistanceUnit enumeration value used to specify the display distance unit.
5.20 Close
Closes a document.
HRESULT Close(enum AtoSaveChanges saveChanges, enum AtoSaveStatus *pStatus);
Parameters
[in] saveChanges: An AtoSaveChanges enumeration value. The values are:
Constant Value Description

atoSaveNo 0 Document is closed without being saved.
atoSaveYes 1 Document is saved before being closed.
The user is prompted whether the document must be saved before
atoSavePrompt 2
closed.
status: atoSucceeded if save was forced to atoSaveYes or atoSaveNo or if the user was prompted and he has answered [out]
pStatus: Address of the AtoSaveStatus enumeration value. Returned values are:

atoSaveSucceeded 0 Document has been successfully saved.
atoSaveCanceled 1 Changes in the document has been cancelled by the user.
5.21 FilePrint
Sends a document to a printer. The current print settings are used.
HRESULT FilePrint();
5.22 Save
Saves a document.
HRESULT Save(const BSTR pVal);
Parameters
[in] pVal: A BSTR used to specify where the document will be saved. When pVal is an empty string, the document is saved in
place, the action performed is the same as the Atoll "File | Save" menu command. When pVal is the full path to an ATL file,
then the action performed is the same as the Atoll "File | Save as..." menu command. When pVal is the full path to a Microsoft
Access database file or when pVal is an Oracle database connection string, then the action performed is the same as the Atoll
"File | Database | Export..." menu command.
5.23 Refresh
Refreshes the document from a database. The document must be connected to a database.
65
HRESULT Refresh(enum AtoRefreshPriority aPriority);
Parameters
[in] aPriority: The AtoRefreshPriority enumeration value used to refresh the document from the database.
5.24 Archive
Archives the document in a database. The document must be connected to a database.
HRESULT Archive(enum AtoArchiveStatus *pStatus);
Parameters
[out] pStatus: Address of the AtoArchiveStatus used to return the result of the operation.
Remarks
Atoll >= 2.7.0:
When the DisplayApplicationDialogues property of the document is set to true, the standard Atoll archive dialogue will be
displayed, otherwise no dialogue is displayed and all changes are archived.
5.25 Run
Starts calculations.
HRESULT Run(VARIANT_BOOL aAll);
Parameters
[in] aAll: The VARIANT_BOOL value used to specify whether all previous results must be deleted before the calculations starts
(VARIANT_TRUE), or if only invalid pathloss matrices must be calculated (VARIANT_FALSE).
Remarks
1) When aAll is set to VARIANT_TRUE, the result is the same as the Atoll "Tools | Force calculation" menu command. When
aAll is set to VARIANT_FALSE, the result is the same as the Atoll "Tools | Calculate" menu command.
2) The method returns immediately and calculations occur in the background.
3) An error is returned when it is called on a Microwave Radio Links Atoll document.
The WillRun application event is thrown by this method.
5.26 SetConfig
Loads a configuration file.
HRESULT SetConfig(const BSTR bstrFileName);
Parameters
[in] bstrFileName: The BSTR used to specify the full path of the configuration file to load.
Remarks
The configuration file is a .CFG file obtained using the Atoll "User Configuration | Export..." menu command. It may contain
geographic configuration and folder configurations. Please see the Atoll Administrator Manual. The configurations in the
document are replaced with the configurations contained in the .CFG file. If you simply want to add some geographic data to
a document, you should rather use the Import method instead.
66
5.27 Import
Loads a file containing geographic data.
HRESULT Import(const BSTR fileName);
Parameters
[in] fileName: A BSTR used to specify the full path of the file to load.
Remarks
The geographic file can be:
• An .CFG file. All data from its geographic section are loaded. Please see the Atoll Administrator Manual.
• Any file format supported by Atoll (.BIL, .TIF, etc).
The geographic content of the imported file (.CFG, .GEO, .BIL, .TIF, etc.) is added to the current configuration of the geographic
data in the document. The existing geographic configuration is not removed.
If you want to replace the geographic configuration of a document, you should use the SetConfig function instead.
You must ensure that no inputs are requested from the user when importing the file (for
instance the file type, georeferencement parameters, etc.) when the application is not
visible.
5.28 GetRecords
Returns an Atoll Tabular Data Object for a requested category of records.
n
HRESULT GetRecords(
const BSTR bstrTableName,
VARIANT_BOOL aAll,
ITabularData *ppRecords
);
Parameters
[in] bstrTableName: A BSTR used to specify the name of the table from which the records are requested.
[in] aAll: A VARIANT_BOOL. When it is set to VARIANT_TRUE, all the records of the table are returned. When it is set to
VARIANT_FALSE and when there is an Atoll document folder associated with bstrTableName, the filter set on the document
folder is used to filter the returned records. If no associated folder exists, this parameter is ignored.
[out] ppRecords: Address of the ITabularData interface pointer used to return the Atoll Tabular Data Object.
Remarks
The list of available table names defined by Atoll can be found in the template (.MDB) file. Please see the Administrator
Manual for the available table names. Some other table names are available:
• PREDICTIONS: to get pathloss matrices and signal level matrices.
• ZONES: to get either the calculation zone or the focus zone.
Changes introduced in Atoll version 2.7.1 and above
1) Table "REPEATERS_VIEW"
When bstrTableName is equal to “REPEATERS_VIEW”, the TabularData object returned is a join on the "TRANSMITTERS" and
the "REPEATERS" table. The fields returned will be the "TRANSMITTERS" table fields and the "REPEATERS" table fields, where
TRANSMITTERS.TX_ID = REPEATERS.TX_ID. The name of the fields of the "REPEATERS" table in the "REPEATERS_VIEW" are
67
prefixed with "TX_ID." whereas the names of the fields coming from the "TRANSMITTERS" table are left unchanged. When
aAll is VARIANT_FALSE, then the filter set on the “Transmitters” folder of the Atoll document is used to filter the
“REPEATERS_VIEW” table records, otherwise all repeaters or remote antennas are returned. A remote antenna is a repeater
whith the field “EQUIPMENT_NAME” set to VT_NULL.
2) Table "REPEATERS"
When bstrTableName is equal to “REPEATERS”, and aAll is VARIANT_FALSE, then the filter set on the “Transmitters” folder of
the Atoll document is used to filter the “REPEATERS” table records, otherwise all repeaters or remote antennas are returned.
A remote antenna is a repeater whith the field “EQUIPMENT_NAME” set to VT_NULL.
Changes introduced in Atoll version 3.1.1 and above
1) Table "MWLinks"
When bstrTableName is equal to “MWLinks”, the TabularData object returned has an additional column named
"_LINK_LENGTH", used to access the length of Microwave links as single precision floating point values.
Example
Dim records
’ Returns the content of the SITES table
Set records = app.ActiveDocument.GetRecords("Sites", True)
’ Returns the content of the Sites folder, taking the folder filter into ac-
count
Set records = app.ActiveDocument.GetRecords("Sites", False)
5.29 Redraw
Refreshes all items in the document.
HRESULT Redraw();
Remarks
It has the same effect as the icon Refresh (F5) in Atoll.
5.30 CenterMapOn
Centres map on a parameter point.
HRESULT CenterMapOn(double* ptx, double* pty);
Parameters
[in] ptx, [in] pty: The double pointers used to specify the coordinates of the point to centres the map view on. The coordinate
system used must be the the document coordinate system.
5.31 GetRootFolder
Returns the root Atoll Child Folder Object used to enumerate all Child Folder objects belonging to one tab of the Atoll explorer
window.
HRESULT GetRootFolder(enum AtoRootType aType, IChildFolder **ppItem);
68
Parameters
[in] aType: The AtoRootType enumeration value used to specify the Atoll explorer window tab. There is one root ChildFolder
object for each tab of the Atoll explorer window.
[out] ppItem: Address of the IChildFolder interface pointer used to return the root ChildFolder object.
Example
Dim geo
const atoGeo = 1
’ Returns the root ChildFolder object of the Atoll explorer "Geo" tab
Set geo = app.ActiveDocument.GetRootFolder(atoGeo)
5.32 RunPathloss
Calculates the path loss matrices with no need for any predefined studies.
HRESULT RunPathloss(VARIANT_BOOL allTx, VARIANT_BOOL forced);
Parameters
[in] allTx: When VARIANT_TRUE, the calculation is made for all active transmitters in the table. When VARIANT_FALSE, only
filtered transmitters are calculated.
[in] forced: When VARIANT_TRUE, the calculation is forced even for transmitters having available valid results. When
VARIANT_FALSE, the calculation is made only for transmitters having unavailable or invalid results.
Remarks
1) This method corresponds to the menu commands "Calculations | Calculate Path Loss Matrices" and "Calculations | Force
Path Loss Matrix Calculation" available in the Calculations sub‐menu of the Transmitters folder.
2) The method returns immediately and the calculations occur in the background.
How to detect the end of path loss matrices calculation?
To wait for the end of background path loss matrices calculation, please use the HasRunningTask document object method.
While background calculations are running, HasRunningTask returns True. As soon as HasRunningTask returns False, you can
assume that background calculations are finished:
'"Wait" Loop
Do While AtollDoc.HasRunningTask
WScript.Sleep 1000
Loop
5.33 GetService
Returns a scriptable Document Service Object.
HRESULT GetService(BSTR bstrName, IDispatch** ppProvider)
Parameters
[in] bstrName: A BSTR used to specify the name of the service.
69
The available values are:
"SIGNAL" : A Result File Provider object, implementing the IResultFileProvider interface.
On documents based on the GSM GPRS EDGE template:
"AFP" : A GSM Frequency Plan Allocation object, implementing the IAfpLauncher interface.
"AFP_IM" : A GSM Interference Matrices object, implementing the IAfpImLauncher interface.
[out] ppProvider: Address of the IDispatch interface pointer used to return the scriptable Document Service Object.
5.34 ExportConfig
Exports a subset of the current document configuration to a file.
HRESULT ExportConfig(const BSTR bstrContent, const BSTR bstrFile);
Parameters
[in] bstrContent: A BSTR used to specify the configuration subset to export:
• "GEO" : The "Geographic Data Set" configuration is exported.
• "GEO+ZONES" : The "Geographic Data Set" and "Computation and Focus Zones" configurations are exported.
• "FULL" : All available configurations are exported.
bstrContent is parsed according to the format "OPTION[+OPTION]". The set of specified options are exported to bstrFile. Avail‐
able options are:
OPTION name Description
GEO Geographic Data Set
ZONES Computation and Focus Zones
STUDIES Prediction List
OPTION name Description
FOLDERS Folder Configuration
MACROS Macros
AFP AFP Configuration
ANP Automatic Neighbour Allocation Parameters
MW Microwave Link Parameters
PNO Automatic PN Offset Allocation Parameters
SCP Automatic Scrambling Code Allocation Parameters
[in] bstrFile: A BSTR used to specify the name of the export file.
5.35 GetCommandDefaults
Returns current default parameters specific to a command.
HRESULT GetCommandDefaults(
const BSTR bstrCommandName,
70
IPropertyContainer **ppParameters
);
Parameters
[in] bstrCommandName: A BSTR used to specify the command.
[out] ppParameters: Address of the IPropertyContainer interface pointer used to return the defaults parameters for the
bstrCommandName command.
5.36 InvokeCommand
Invokes a command.
HRESULT InvokeCommand(
const BSTR bstrCommandName,
IPropertyContainer *pParameters,
IPropertyContainer **ppResults
);
Parameters
[in] bstrCommandName: A BSTR used to specify the command.
[in] pParameters: The IPropertyContainer interface pointer used to specify the Property Container object holding the param‐
eters needed to carry out the command.
• If set to NULL, default parameters for the command will be used.
ppResults: Results of the command invokation.
• *ppResults will be set to NULL if the command has no results.
5.37 get_RadiatedPowerUnit
Returns the current radiated power unit.
HRESULT get_RadiatedPowerUnit(enum AtoRadiatedPowerUnit *pVal);
Parameters
[out] pVal: Address of the AtoRadiatedPowerUnit enumeration value used to return the radiated power unit.
5.38 put_RadiatedPowerUnit
Sets the current radiated power unit.
HRESULT put_RadiatedPowerUnit(enum AtoRadiatedPowerUnit aNewVal);
Parameters
[in] aNewVal: The AtoRadiatedPowerUnit enumeration value used to specify the radiated power unit.
5.39 get_AntennaGainUnit
Returns the current antenna gain unit.
71
HRESULT get_AntennaGainUnit(enum AtoAntennaGainUnit *pVal);
Parameters
[out] pVal: Address of the AtoAntennaGainUnit enumeration value used to return the antenna gain unit.
5.40 put_AntennaGainUnit
Sets the current antenna gain unit.
HRESULT put_AntennaGainUnit(enum AtoAntennaGainUnit aNewVal);
Parameters
[in] aNewVal: The AtoAntennaGainUnit enumeration value used to specify the antenna gain unit.
5.41 get_HeightOffsetUnit
Returns the current height offset unit.
HRESULT get_HeightOffsetUnit(enum AtoHeightOffsetUnit *pVal);
Parameters
[out] pVal: Address of the AtoHeightOffsetUnit enumeration value used to return the height offset unit.
5.42 put_HeightOffsetUnit
Sets the current height offset unit.
HRESULT put_HeightOffsetUnit(enum AtoHeightOffsetUnit aNewVal);
Parameters
[in] aNewVal: The AtoHeightOffsetUnit enumeration value used to specify the height offset unit.
5.43 get_DatabaseConnectionString
Returns the database connection string.
HRESULT get_DatabaseConnectionString(BSTR *pVal);
Parameters
[out] pVal: Address of the BSTR used to return the database connection string.
Remarks
An error is returned when the document is not connected to a database.
5.44 HasRunningTask
Returns true when there is some calculation in progress.
HRESULT HasRunningTask(VARIANT_BOOL *pVal);
72
Parameters
[out] pVal: Address of the VARIANT_BOOL used to return whether there is some calculation in progress or not.
Remarks
When some calculation is in progress, it is impossible to start new ones.
5.45 RunEx
Start calculations.
HRESULT RunEx(VARIANT_BOOL aAll, VARIANT_BOOL vbBlocking);
Parameters
[in] aAll: The VARIANT_BOOL value used to specify whether all previous results must be deleted before the calculations starts
(VARIANT_TRUE), or if only invalid pathloss matrices must be calculated (VARIANT_FALSE).
[in] vBlocking: The VARIANT_BOOL value used to specify whether the calculations will occur in the background
(VARIANT_FALSE), or if the method should wait for the calculations to finish before returning (VARIANT_TRUE).
Remarks
1) When aAll is set to VARIANT_TRUE, the result is the same as the Atoll "Tools | Force calculation" menu command. When
aAll is set to VARIANT_FALSE, the result is the same as the Atoll "Tools | Calculate" menu command.
The WillRun application event is thrown by this method.
When vbBlocking is set to VARIANT_TRUE, the RunComplete application event is thrown by this method before it returns.
5.46 get_DatabaseSchemaString
Returns the database schema string.
HRESULT get_DatabaseSchemaString(BSTR *pVal);
Parameters
[out] pVal: Address of the BSTR used to return the database schema string.
Remarks
An error is returned when the document is not connected.
The database schema string is returned using the exact same syntax described for the OpenFromDatabase method.
5.47 get_DisplayApplicationDialogues
Returns true when some methods on some Atoll interfaces may display some dialogue boxes.
HRESULT get_DisplayApplicationDialogues(VARIANT_BOOL *pVal);
Parameters
[out] pVal: Address of the VARIANT_BOOL used to return whether some dialogue boxe may be displayed upon invokation of
some method on some Atoll interface.
Remarks
Setting the Application Object visibility state to false sets this value to false.
73
5.48 put_DisplayApplicationDialogues
Returns true when some methods on some Atoll interfaces may display some dialogue boxes.
HRESULT put_DisplayApplicationDialogues(VARIANT_BOOL aNewVal);
Parameters
[in] aNewVal: The VARIANT_BOOL used to specify whether some dialogue boxe may be displayed upon invokation of some
method on some Atoll interface.
Remarks
Setting the Application Object visibility state to false sets this value to false.
5.49 PutDatabaseSchemaString
Sets the database schema string.
HRESULT PutDatabaseSchemaString(BSTR aVal);
Remarks
This method is not implemented.
Please do not use this method.
Atoll Version
 2.8.1
5.50 PutDatabaseConnectionString
Sets the database connection string.
HRESULT PutDatabaseConnectionString(BSTR aVal);
Parameters
[in] aVal:
The BSTR used to specify the new database connection string.
To disconnect the document from the database, specify a NULL BSTR value or an empty string.
Remarks
An error is returned when the document is not connected to a database.
Depending on the aVal parameter value, the action performed is the same as Database | Connection Properties | Modify, or
Database | Connection Properties | Disconnect.
Atoll Version
 2.8.1
5.51 ChangeDatabaseConnection
Changes the database connection string.
HRESULT ChangeDatabaseConnection(BSTR aCnn, BSTR aReserved);
74
Parameters
[in] aCnn:
The BSTR used to specify the new database connection string.
[in] aReserved:
A BSTR reserved for a future usage.
Remarks
Please do not use this method. Use PutDatabaseConnectionString instead.
Atoll Version
 2.8.1
5.52 get_TemperatureUnit
Returns the display temperature unit.
HRESULT get_TemperatureUnit(enum AtoTemperatureUnit *pVal);
Parameters
[out] pVal: Address of the AtoTemperatureUnit enumeration value used to return the display temperature unit.
5.53 put_TemperatureUnit
Sets the display temperature unit.
HRESULT put_TemperatureUnit(enum AtoTemperatureUnit aNewVal);
Parameters
[in] aNewVal: The AtoTemperatureUnit enumeration value used to specify the display temperature unit.
5.54 GetDocumentProperties
Returns the document properties.
HRESULT GetDocumentProperties(IPropertyContainer **ppProperties);
Parameters
[out] ppProperties: Address of the IPropertyContainer interface pointer used to return the document properties.
Remarks
Please see the SetDocumentProperties documentation for the list of available document properties.
5.55 SetDocumentProperties
Sets the document properties.
HRESULT SetDocumentProperties(IPropertyContainer *pProperties);
75
Parameters
[in] pProperties: The IPropertyContainer interface pointer used to specify the document properties.
Remarks
Available document properties are:
Name Type
PROJECT String
DATE String
AUTHOR String
TITLE String
COMMENT String
STATUS String
LOGO String
USER_PROPERTY0
USER_PROPERTY1
USER_PROPERTY2
USER_PROPERTY3
USER_PROPERTY4
USER_PROPERTY5
USER_PROPERTY6
USER_PROPERTY7
USER_PROPERTY8
USER_PROPERTY9
USER_PROPERTY_NAME0 String
76
77
78
Chapter 6
TabularData Object
80
AT321_TAG_E4 Chapter 6: TabularData Object
6 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, explained in "Zones and
Predictions Tabular Data Objects" on page 97.
Access to tabular data in an Atoll document connected to a database
For each database table, access is provided to differences between the content of the
database when the data table has been refreshed for the last time and the current table
content stored in an Atoll document. These are the differences listed in the Atoll Database
Archive dialogue, which can be submitted through an external process using this interface.
Access is given the original data as retrieved by the latest refresh operation from the data‐
base. Access is not given to the current content of the database. Therefore, it is not possi‐
ble to show or solve conflicts between the data in the Atoll document and the current
content of the database.
For a given database table, original data values and row statuses are not stored in the data‐
base. They are stored in the Atoll document.
The TabularData object provides the following properties and methods:
Type: Integer
get_ColumnCount Returns the number of columns of the TabularData Object.
Access: Read
Type: Integer
get_RowCount Returns the number of rows of the TabularData Object
Access: Read
Edit Puts a row into edition mode.
Adds a new empty row to the TabularData Object. The row
AddNew
added is put into edition mode.
Commits a row changes and puts the row from edition mode
Update
to normal mode.
Delete Deletes a record.
GetValue Returns a value of a column for a given row.
SetValue Sets the value of a column for the row being edited or added.
GetPrimaryKey Returns the value of the primary key for a given row number.
Searches the row whose primary key equals the input value
FindPrimaryKey
and returns the row number of the row found.
Find Searches a column for a value.
GetFormattedValue Returns a column value formatted as a string.
CancelUpdate Cancels a pending update.
Type: Integer
get_ColumnNumber Returns a column number.
Access: Read
Type: Boolean
get_CanEdit Checks if rows can be modified.
Access: Read
Type: Boolean
get_CanAddNew Checks if rows can be added.
Access: Read
Type: Boolean
get_CanFilterSort Checks if rows can be filtered or sorted.
Access: Read
Type: String
get_Filter Returns the filter currently set on the table.
Access: Read/Write
81
Chapter 6: TabularData Object © Forsk 2014
Type: String
put_Filter Filters the table data according to a filter criteria.
Access: Read/Write
Type: String
get_Sort Returns the sort order currently set on the table.
Access: Read/Write
Type: String
put_Sort Sorts the table data.
Access: Read/Write
GetOriginalValue Returns an original field value.
Type: Integer
get_RowStatus Returns a row status.
Access: Read
6.1 How to Access a TabularData Object
A TabularData object is defined by its structure (number of columns, name of columns) and its content (rows = records).
Column 0 and row 0 are special:
• Row 0 holds the field names, i.e., the table structure description.
• Column 0 holds a unique identifier for records, called RECORD_ID. This identifier is not persistent and must not be
used between two sessions of Atoll, neither when refreshing nor when archiving.
Thus, in order to get a tabular data structure, you write:
Dim i
Dim colName
Dim records
Set records = Atoll.ActiveDocument.GetRecords("Transmitters", True)
For i = 0 To records.ColumnCount
colName = records.GetValue(0, i)
Next
The first value (for i = 0) is always "RECORD_ID". The second (for i = 1) is "SITE_NAME" in case of TRANSMITTERS table, and so
on. The last one corresponds to i = ColumnCount.
To read the calculation radii of all the transmitters, you write:
Dim i
Dim radius
Dim records
Set records = Atoll.ActiveDocument.GetRecords("Transmitters", True)
For i = 1 To records.RowCount
radius = records.GetValue(i, “CALC_RADIUS”)
Next
Note that the loop does not start with i = 0 because GetValue would return the string "CALC_RADIUS" and not a value.
If we know that column "CALC_RADIUS" is number 11, we could instead write:
82
radius = records.GetValue(i, 11)
But it is better to let Atoll manage the correspondence by itself.
The table names you can use to request GetRecords in a document are Atoll tables defined in the document template initially
used to create your document, and depend on the type of network.
You can also get some additional tables: Predictions, Zones.
• Predictions tabular data gives access to path loss and signal level matrices.
• Zones tabular data gives access to calculation and focus zones.
For more information, see "Zones and Predictions Tabular Data Objects" on page 97.
6.2 get_ColumnCount
Returns the number of columns of the TabularData Object.
HRESULT get_ColumnCount(long *pVal);
Parameters
[out] pVal: Address of the long integer used to return the number of columns.
Remarks
This number does not include the RECORD_ID column. If a table TABLE1 is defined by FIELD1, FIELD2, and FIELD3,
get_ColumnCount returns 3, even though there are 4 columns : RECORD_ID, FIELD1, FIELD2, and FIELD3.
6.3 get_RowCount
Returns the number of rows of the TabularData Object
HRESULT get_RowCount(long *pVal);
Parameters
[out] pVal: Address of the long integer used to return the number of rows.
Remarks
The first row is row number 0 and it contains the TabularData Object field names. If a table TABLE1 has no record, 0 is
returned. The actual contents of the table starts at row number 1. GetValue(0, 1) returns FIELD1, which is the name of the
column number 1 (read in row number 0). GetValue(0, 0) returns RECORD_ID, which is the name of the column number 0
(read in row number 0). GetValue(1, 1) returns the value for column FIELD1 (number 1) in row number 1.
6.4 Edit
Puts a row into edition mode.
HRESULT Edit(long iRow);
Parameters
[in] iRow: The long integer used to specify the row number to put into edition mode.
Remarks
Once a row is put into edition mode, it is possible to change the row contents by using SetValue. Update is used to commit
the row changes.
83
Don’t forget to call this method before a call to SetValue and to call Update to commit the
changes in the row.
6.5 AddNew
Adds a new empty row to the TabularData Object. The row added is put into edition mode.
HRESULT AddNew();
Don’t forget to call this method before a call to SetValue and to call Update to actually add
the new row.
6.6 Update
Commits a row changes and puts the row from edition mode to normal mode.
HRESULT Update(long *piRow);
Parameters
[out] piRow: The long integer pointer used to return the number of the row that was in edition mode. If the method Edit
started the editing, the same iRow as in Edit is returned. If it was AddNew method, the number is the row number where the
new record has been added.
Remarks
At one point in time, only one record can be put into edition mode. This method must be called once after each Edit and
AddNew. Editing another record without updating the previous one will throw an error. Edit/Update cannot be mixed up for
different records, neither can be AddNew/Update.
6.7 Delete
Deletes a record.
HRESULT Delete(long iRow);
Parameters
[in] iRow: The long integer used to specify the row number of the record to delete.
Remarks
A valid iRow number is any integer, such that 0 < iRow <= RowCount. Deletion can fail if the record to delete is related to
another one. For instance an antenna from the table "ANTENNAS" cannot be deleted if it is being used by a transmitter from
the table "TRANSMITTERS".
Even if the record deletion doesn’t break integrity relations between tables, deleting a record may involve updating other
tables or records.
For instance, be careful when using this method with the "TRANSMITTERS" table and the "TRXs" table. If you delete one TRX,
you want to edit the "TRANSMITTERS" table in order to update the field "NUM_TRX".
6.8 GetValue
Returns a value of a column for a given row.
84
HRESULT GetValue(long iRow, const VARIANT iCol, VARIANT *pVal);
Parameters
[in] iRow: The long integer used to specify the row number.
[in] iCol: The VARIANT used to specify a column. When iCol is of type VT_I4, iCol is interpreted as a column number. When iCol
is of type VT_BSTR, iCol is interpreted as a column name.
[out] pVal: Address of the VARIANT used to return the column value.
Remarks
A valid iRow number is any integer, such that 0< iRow<= RowCount. A valid iCol is either an integer such that 0< iCol <= Colum‐
nCount or a string containing the name of an existing column.
The column names are not case sensitive.
You should never assume that the type of the returned VARIANT is the one you expect. For instance, a VARIANT of type
VT_NULL may be returned when the value of the column is the "Null" value. You should explicitly convert the returned VARI‐
ANT to the type you expect and handle conversion errors.
When using a TabularData Object to access database tables, please refer to the Atoll Administrator Manual for the available
column names, types, units, and to check if the column specification allows for "Null" values. For site coordinates values,
please refer to the Atoll Technical Reference Guide for coordinate systems and units. Site coordinates are expressed in the
internal coordinate system of the Atoll document.
Example
Set sites = app.ActiveDocument.GetRecords(“Sites”)
For i = 1 To sites.ColumnCount
colName = sites.GetValue(0, i)
Next
6.9 SetValue
Sets the value of a column for the row being edited or added.
HRESULT SetValue(const VARIANT iCol, const VARIANT newVal);
Parameters
[in] iCol: The VARIANT used to specify a column.
[in] newVal: The VARIANT used to specify the column value.
Remarks
A valid iCol is either an integer such that 0 < iCol <= ColumnCount or a string containing the name of an existing column. The
column names are not case sensitive.
You must have previously called Edit or AddNew to specify the row to edit before writing the column value.If this method is
used for a large number of records, it is recommended to get the column numbers beforehand and then to use the SetValue
method with this number and not with a VARIANT of type VT_BSTR. This will run faster. To get the column number, you can
search the row number 0 for the field name you want to use.
Example
This example increments all the TXLOSSES of all the transmitters in the active document by 1 dB.
Dim transmitters
Dim doc
85
Dim i
Dim txLosses
Set doc = app.ActiveDocument
Set transmitters = doc.GetRecords(“Transmitters”)
For i = 1 To transmitters.RowCount
txLosses = transmitters.GetValue(i, “LOSSES”)
transmitters.Edit(i)
transmitters.SetValue(“LOSSES”, txLosses + 1)
transmitters.Update
Next
Instead, we could have used:
For i = 1 To transmitters.RowCount
txLosses = transmitters.GetValue(i, 12)
transmitters.Edit(i)
transmitters.SetValue(12, txLosses + 1)
transmitters.Update
Next
Updating the main contour of the focus zone:
Public Sub WriteZone()
Set doc = ActiveDocument
Set zones = doc.GetRecords("Zones", true)
row = zones.Find(0, "NAME", atoEQ, "FocusZone")
Dim pts(3,1)
pts(0,0) = 555000
pts(0,1) = 2188000
pts(1,0) = 600000
pts(1,1) = 2188000
pts(2,0) = 600000
pts(2,1) = 2140000
pts(3,0) = 555000
pts(3,1) = 2140000
86
zones.Edit row
zones.SetValue "POINTS", pts
zones.Update
End Sub
6.10 GetPrimaryKey
Returns the value of the primary key for a given row number.
HRESULT GetPrimaryKey(long iRow, VARIANT* pVal);
Parameters
[in] iRow: The row number.
[out] pVal: Address of the VARIANT used to return the primary key.
Remarks
A valid iRow number is an integer whose value is greater than zero or equal to zero and lower than or equal to the row count
of the TabularData object. Most of TabularData objects have a primary key. If no primary key is defined, the value of the
column RECORD_ID for the row iRow is returned. When the TabularData object primary key is made of several columns, the
type of the variant returned is a one dimension VARIANT array, of type VT_ARRAY|VT_VARIANT, and VARIANT array values
are the values of the columns defining the primary key. Otherwise, the VARIANT returned is the value of the column used to
define the primary key.
When 0 is used for the iRow parameter, the names of the columns defining the primary key are returned. The variant returned
is of type VT_BSTR or VT_ARRAY|VT_VARIANT with variants of type VT_BSTR, whether the primary key is made of one or
several columns, respectively.
6.11 FindPrimaryKey
Searches the row whose primary key equals the input value and returns the row number of the row found. If no row is found,
returns –1.
HRESULT FindPrimaryKey(VARIANT val, long* iRow);
Parameters
[in] val: The VARIANT used to specify the key value to search for.
[out] iRow: Address of the long integer used to return the number of the row whose primary key equals val. If no row is found,
‐1 is returned.
Remarks
When the primary key is made of several columns, the input variant must be of type VT_ARRAY|VT_VARIANT.
6.12 Find
Searches a column for a value.
HRESULT Find(
long iRowStart,
const VARIANT iCol,
87
enum AtoCompareOp op,
const VARIANT value,
long* piRow
);
Parameters
[in] iRowStart: The long integer used to specify the row number from which the value will be searched for.
[in] iCol: The VARIANT used to specify the column number or the column name that will be searched.
[in] op: The atoCompareOp enumeration value used to specify the search criteria (greater than, less than, equal to, etc).
[in] value: The VARIANT used to specify the value to search.
[out] piRow: The long integer pointer used to return the row number of the first row matching the search criteria. –1 is
returned if no row is found.
Remarks
Patch iRowStart inside a loop in order to scan several rows matching the search criteria.
This method should be used only for a few searches, because on the Atoll side, this method scans the rows one after the other
and can be very time consuming.
If the column is the primary key of the TabularData Object, use FindPrimaryKey instead.
For repetitive search operations, use a collection (map) of all the rows and write your own filter.
Example
In this example, we search for all transmitters whose LOSSES are equal to 2, and replace them with 3.
Dim transmitters
Dim iRow
Const atoEQ = 0
Set transmitters = ActiveDocument.GetRecords(“Transmitters”, False)
iRow = 0
While iRow <> -1
iRow = transmitters.Find(iRow + 1, "LOSSES", atoEQ, 2)
If iRow <> -1 Then
transmitters.Edit(iRow)
transmitters.SetValue("LOSSES", 3)
transmitters.Update
End If
Wend
6.13 GetFormattedValue
Returns a column value formatted as a string.
HRESULT GetFormattedValue(long iRow, const VARIANT iCol, BSTR *pVal);
88
Parameters
[in] Row: The row number.
• A valid iRow number is an integer whose value is greater than zero or equal to zero, and lower than or equal to the
row count of the TabularData object.
[in] iCol: The VARIANT used to define the column.
• When iCol variant type if VT_I4, iCol is interpreted as a column number. A valid column number is an integer whose
value is greater than zero or equal to zero, and lower than or equal to the column count of the TabularData object.
• When iCol variant type if VT_BSTR, iCol is interpreted as a column name. Column names are not case sensitive.
[out] pVal: Address of a BSTR string used to return the formatted value.
Remarks
When 0 is used for the iRow parameter, the title of the column specified by iCol is returned. The title of a column is localized
and may be shown to a user, as opposed to the column name.
6.14 CancelUpdate
Cancels a pending update. This method may be called after Edit or AddNew to cancel the operation.
HRESULT CancelUpdate();
6.15 get_ColumnNumber
Returns a column number.
HRESULT get_ColumnNumber(const VARIANT vColName, long *pCol);
Parameters
[in] vColName: The VARIANT used to specify the name of the column.
[ou] pCol: Address of the long integer used to return column number.
Remarks
It is faster to read data from tables using the column number instead of the column name. It also works for linked fields.
For instance you can write:
Set sites = doc.GetRecords("SITES", False)
colLatitude = sites.ColumnNumber("LATITUDE")
For i = 1 To sites.RowCount
latitude = sites.GetValue i, colLatitude
Next
6.16 get_CanEdit
Checks if rows can be modified.
HRESULT get_CanEdit(VARIANT_BOOL *pVal);
89
Parameters
[out] pVal: Address of the VARIANT_BOOL used to return whether rows can be modified or not.
Remarks
If VARIANT_FALSE is returned, then the Edit operation on this table is undefined.
6.17 get_CanAddNew
Checks if rows can be added.
HRESULT get_CanAddNew(VARIANT_BOOL *pVal);
Parameters
[out] pVal: Address of the VARIANT_BOOL used to return whether rows can be added or not.
Remarks
If VARIANT_FALSE is returned, then the AddNew operation on this table is undefined.
6.18 get_CanFilterSort
Checks if rows can be filtered or sorted.
HRESULT get_CanFilterSort(VARIANT_BOOL *pVal);
Parameters
[out] pVal: Address of the VARIANT_BOOL used to return whether rows can be filtered or sorted.
Remarks
If VARIANT_FALSE is returned, then the Filter and Sort operations on this table are undefined.
6.19 get_Filter
Returns the filter currently set on the table.
HRESULT get_Filter(VARIANT *pvCriteria);
Parameters
[out] : pvCriteria: Address of the VARIANT used to return the filter previously set on the table.
Remarks
Please refer to the AtoRowFilter enumeration definition for the list of constants used to filter only modified, added, or deleted
rows.
6.20 put_Filter
Filters the table data according to a filter criteria.
HRESULT put_Filter(const VARIANT vCriteria);
90
Parameters
[in] vCriteria: The VARIANT used to specify the filter criteria. When vCriteria is of type VT_I4, it is interpreted as an AtoRow‐
Filter enumeration value. When vCriteria is of type VT_BSTR, it is interpreted as a filter string. Filter strings are what can be
seen in the Atoll "Table" tab properties for record folders, when using advanced filtering. Please refer to the Atoll User Manual
for more information about advanced filtering on data.
Remarks
Please refer to the AtoRowFilter enumeration definition for the list of constants used to filter only modified, added, or deleted
rows.
If the table is retrieved using GetRecords with aAll parameter set to False, setting this property is the same as setting the filter
interactively in an Atoll session.
To remove any previous filter, call this method either with atoRowFilterNone value or with an empty string.
When the Atoll document is not connected to a database, atoRowFilterModifiedOrNew and atoRowFilterDeleted are not
available.
6.21 get_Sort
Returns the sort order currently set on the table.
HRESULT get_Sort(VARIANT *pvCriteria);
Parameters
[in] vCriteria: The VARIANT, of type VT_BSTR, used to specify the sort order. It contains a list of comma separated database
field names. Each field is optionally followed by the DESC keyword to indicate that the sort order associated with the field is
"Descending".
Remarks
If the table is retrieved using GetRecords with aAll parameter set to False, setting this property is the same as setting the sort
order interactively in an Atoll session.
To remove any previous sort order, call this method with an empty string.
Example
Private Sub PrintTransmittersTable(transmRec, infoMsg)
For nRow = 1 To transmRec.RowCount
LogMessage infoMsg & ": " & transmRec.GetValue(nRow, "TX_ID")
Next
End Sub
Sub Main
Set t = ActiveDocument.GetRecords("transmitters", False)
‘ Sort ascending according to the "SITE_NAME" database field
t.Sort = "SITE_NAME"
PrintTransmitterTables t, "Sort = SITE_NAME"
‘ Sort descending according to the "SITE_NAME" database field
t.Sort = "SITE_NAME DESC"
PrintTransmittersTable t, "Sort = SITE_NAME DESC"
91
End Sub
6.22 put_Sort
Sorts the table data.
HRESULT put_Sort(const VARIANT vCriteria);
Parameters
[in] vCriteria: The VARIANT, of type VT_BSTR, used to specify the sort order. It contains a list of comma separated database
field names. Each field is optionally followed by the DESC keyword to indicate that the sort order associated with the field is
"Descending".
Remarks
If the table is retrieved using GetRecords with aAll parameter set to False, setting this property is the same as setting the sort
order interactively in an Atoll session.
To remove any previous sort order, call this method with an empty string.
Example
See "get_Sort" on page 91.
6.23 GetOriginalValue
Returns an original field value.
HRESULT GetOriginalValue(long iRow, const VARIANT iCol, VARIANT *pVal);
Parameters
[in] iRow: The long integer used to specify a row number.
[in] iCol: The VARIANT used to specify a column name or a column number.
[out] pVal: Address of VARIANT used to return the original column value.
Remarks
The original value, as opposed to the current value return by GetValue, is the value retrieved from the database when the
Atoll document has been refreshed for the last time.
If the row is unmodified, the original value is the same as the current value.
If the row is deleted the current value is the null value and the original value is the value just before the row was deleted.
6.24 get_RowStatus
Returns a row status.
HRESULT get_RowStatus(long iRow, enum AtoRowStatus *pVal);
Parameters
[in] iRow: The long integer used to specify a row number.
[out] pVal: Address of the AtoRowStatus enumeration value used to return the row status.
92
Remarks
When an Atoll document is open from a database, row statuses are set to atoRowStatusUnmodified and original values are
set for all row columns.
When the document is archived or refreshed from the database, row statuses are set to atoRowStatusUnmodified and all
columns original values are set for rows that have been archived or refreshed.
When a new row is created, the row status is set to atoRowStatusNew and the original value for all columns are set to the null
value.
When a row is modified, the row status is set to atoRowStatusModified. If you revert the row changes, the row status is set
to atoRowStatusUnmodified.
When a row is deleted, the row status is set to atoRowStatusDeleted, the row column values are set to the null value, and the
original column values are the column values just before the row was deleted.
6.25 get_Columns
Returns table columns definition.
HRESULT get_Columns(ITabularData** ppVal);
Parameters
[out] ppVal:
Address of the ITabularData interface pointer used to return a tabular data object holding the table columns definition:
Column Name Type Description
LEGEND String The display name of the column
NAME String The database name of the column
The data type of the column. Valid values are:
0=Text
1=Short integer
2=Long integer
TYPE Integer 3=Single
4=Double
5=True/False
6=Date/Time
7=Currency;
SIZE Integer The size, in bytes, for a column of TYPE 0 (Text).
The default value of the column. The type of the variant depends on the
DEFAULT Variant type of the column, as indicated by TYPE.
May be Null.
FORMATTED_DEFAULT String The default value of the column, formatted as a string.
GROUP String The name of the database field group the column belongs to.
ISCUSTOMFIELD Boolean Whether the column is a user column (True), or not (False).
Whether a column of TYPE 0(Text) content values are restricted to the
CHOICELIST_TYPE Integer
values specified in CHOICELIST_VALUES.
CHOICELIST_VALUES String Newline separated string of valid values for a column of TYPE text.
93
94
Chapter 7
Zones and Predictions
Tabular Data Objects
96
AT321_TAG_E4 Chapter 7: Zones and Predictions Tabular Data Objects
7 Zones and Predictions Tabular Data Objects
7.1 Zones Tabular Data Object
"ComputationZone" if this row is the computation zone.
"FocusZone" if this rowis part of the focus zone.
"FilterZone" if this row is part of the filtering zone.
NAME String "PrintZone" if this row is part of the printing zone.
"ExpBitmapZone" if this row is part of the coverage export zone.
Atoll >= 2.8.1
"HotSpotZone" if this row is part of the hot spot zone.
POINTS Array An array of points as double values.
CONTOUR_NUM Integer The contour index.
POLYGON_NUM Integer The polygon index.
Atoll >= 2.8.1
The name of the polygon.
For hot spot zones, it is the name of a specific hot spot zone.
POLYGON_NAME String
For other zones, it is the name the zone sub‐folder, in the explorer window.
This column is read‐only.
Atoll Version
 2.8.1
It is now possible to access hot spot zones.
Their content is identified by the "NAME" column ("HotSpotZone"), then a specific hot spot zone is specified by the
"POLYGON_NAME" column, which is used to indicate a specific hot spot zone in the hot spot zones folder.
However, unlike other zones, hot spot zones access is read‐only. It is not possible to edit a hot spot zone, to delete a hot spot
zone, or to create a new hot spot zone.
Example
Reading the first contour of the focus zone:
Public Sub ReadZone()
Set zones = doc.GetRecords("Zones", True)
row = zones.Find(1, "NAME", atoEQ, "FocusZone")
pts = zones.GetValue(row, "POINTS")
If (IsArray(pts)) Then
For i = LBound(pts, 1) To UBound(pts, 1)
ptx = pts(i,0)
pty = pts(i,1)
MsgBox "Pts(" + CStr(i) + ") = " + CStr(ptx) + ", " + CStr(pty)
Next
97
Chapter 7: Zones and Predictions Tabular Data Objects © Forsk 2014
Else
MsgBox "Not an array"
End If
End Sub
7.2 Predictions Tabular Data Object
The "PREDICTIONS" Tabular Data object is read‐only except for the LOCKED field, which can be used to lock or unlock pahloss
matrices of a transmitter.
Atoll Version
 2.8.0
The field PATH_NAME is read‐write. Its value can be set to Null , in which case pathloss matrices for TX_ID are deleted.

TX_ID String Transmitter name.
LOCKED Boolean True if the pathloss matrices are locked, otherwise False.
VALID Boolean True if the main and extended path loss matrices are valid, otherwise False.
Cause of invalidity, when VALID returns False.
INVALID_CAUSE String
Null value when VALID returns True.
SIZE Integer Size of the main matrix plus the size of the extended matrix, in bytes.
Null value when there is no storage for the main matrix.
PATHNAME String "(Embedded in document)" if the storage is not external.
Otherwise contains the main path loss matrix file path.
The object implements the IGridData interface. This grid data contains the
PATHLOSS Object main path loss matrix data for transmitter TX_ID.
Null value when there is no available result for the main matrix.
SIGNAL Object main signal level matrix data for transmitter TX_ID.
LOWRES_PATHLOSS Object extended path loss matrix data for transmitter TX_ID.
Null value when there is no available result for the extended matrix.
LOWRES_SIGNAL Object extended signal level matrix data for transmitter TX_ID.
Atoll version  2.7.0
Null value when there is no storage for the extended matrix.
LOWRES_PATHNAME String
"(Embedded in document)" if the storage is not external.
Otherwise contains the extended path loss matrix file path.
Atoll Version
 2.8.1
New columns are available
These values are available even when VALID returns FALSE but they are not up to date when the resolution of path loss matri‐
ces, the calculation area, or the transmitter location has changed.
98
AT321_TAG_E4 Chapter 7: Zones and Predictions Tabular Data Objects

X‐coordinate of the top‐left corner of the main path loss matrix upper‐left
GRID_X Double pixel.
Y‐coordinate of the top‐left corner of the main path loss matrix upper‐left
GRID_Y Double pixel.
Number of columns in the main path loss matrix.
GRID_NX Integer
Number of rows in the main path loss matrix.
GRID_NY Integer
Resolution of the main path loss matrix, in metre.
GRID_RESX Double
Resolution of the main path loss matrix, in metre.
GRID_RESY Double
X‐coordinate of the top‐left corner of the extended path loss matrix upper‐
LOWRES_GRID_X Double left pixel.
Y‐coordinate of the top‐left corner of the extended path loss matrix upper‐
LOWRES_GRID_Y Double left pixel.
Number of columns in the extended path loss matrix.
LOWRES_GRID_NX Integer
Number of rows in the extended path loss matrix.
LOWRES_GRID_NY Integer
Resolution of the extended path loss matrix, in metre.
LOWRES_GRID_RESX Double
Resolution of the extended path loss matrix, in metre.
LOWRES_GRID_RESY Double
Atoll Version
 3.1.0
New columns are available:

TX_PATHLOSS Object The object implements the IGridData interface.
TX_SIGNAL Object The object implements the IGridData interface.
TX_LOWRES_PATHLOSS Object The object implements the IGridData interface.
TX_LOWRES_SIGNAL Object The object implements the IGridData interface.
TX_PATHLOSS, TX_SIGNAL , TX_LOWRES_PATHLOSS, TX_LOWRES_SIGNAL for the transmitter TX_ID do not take into account
its repeaters or remote antennas.
On the contrary, using PATHLOSS, SIGNAL, LOWRES_PATHLOSS, LOWRES_SIGNAL, contributions from repeaters or remote
antennas are combined into one matrix.
Please use TX_PATHLOSS, TX_SIGNAL , TX_LOWRES_PATHLOSS, TX_LOWRES_SIGNAL columns when you need to consider
transmitter signal or path loss independently from its repeaters or remote antennas.
Atoll Version
 3.2.0
It is now possible to update path loss matrices with external results (.LOS files).
99
Chapter 7: Zones and Predictions Tabular Data Objects © Forsk 2014
You can edit the PATH_NAME or LOWRES_PATHNAME columns, specifying valid .LOS absolute full path.
In this case, when the row in the predictions table is updated, path loss matrices are updated with the content of files previ‐
ously specified.
Please note that fo this to work, you have to georeference your provided .LOS files, with a standard BIL header file (.hdr).
Please note that even if your .LOS files need to be georeferenced just like they were .BIL files, .LOS files are written bottom‐
up, not top‐down.
main path loss matrix data for transmitter TX_ID.
TX_PATHLOSS Object Null value when there is no available result for the main matrix.
Values returned do not include contributions from repeaters or remote
antennas of the transmitter TX_ID.
main signal level matrix data for transmitter TX_ID.
TX_SIGNAL Object Null value when there is no available result for the main matrix.
extended path loss matrix data for transmitter TX_ID.
TX_LOWRES_PATHLOSS Object Null value when there is no available result for the extended matrix.
extended signal level matrix data for transmitter TX_ID.
TX_LOWRES_SIGNAL Object Null value when there is no available result for the extended matrix.
100
Chapter 8
CoordSystem Object
102
AT321_TAG_E4 Chapter 8: CoordSystem Object
8 CoordSystem Object
This object contains the entire definition of a coordinate system. Several coordinate systems are used in Atoll documents; one
for display, one for projected geographic files, and one for site coordinates. The last one can be related to the system used for
display.
This object is not defined in Atoll library but in the FSKGISLib library. It can convert points from one coordinate system to
another.
The CoordSystem object provides the following properties and methods:

Code Returns or sets the numeric code of the coordinates system.
Converts the coordinates of a point expressed in the current
ConvertCoordsTo
system to another one.
Datum Returns or sets the numeric value of the datum.
DatumName Name of the datum.
Description Description of the datum.
Ellipsoid Returns or sets the numeric value of the ellipsoid.
EllipsoidName Name of the ellipsoid.
Name Returns or sets the name of the coordinates system.
Pick Opens the coordinates system dialogue.
ProjMethod Projection method used for the current coordinates system.
ProjParameter Reads a parameter of the projection.
SetDatum Changes the datum of the system.
SetProjection Sets the projection parameters of the coordinate system.
Unit Returns or sets the unit of the coordinate system.
For details on coordinate systems, see the Technical Reference Guide.
8.1 How to Access a CoordSystem Object
To get the coordinate system used for sites:
Dim doc
Dim coordSys
Set doc = Atoll.ActiveDocument
Set coordSys = doc.CoordSystemInternal
8.2 Code
Returns or sets the numeric code of the coordinates system.
HRESULT Code(long *pVal);
HRESULT Code(long val);
103
Chapter 8: CoordSystem Object © Forsk 2014
Parameters
pVal: Address of the Long read as the code of the system.
val: Long value representing the code of the system to set.
Classical system codes have values less than 32767. System codes greater or equal to
32768 correspond to user defined systems.
8.3 ConvertCoordsTo
Converts the coordinates of a point expressed in the current system to another one.
HRESULT ConvertCoordsTo(
IDispCoordSystem *targetCS,
VARIANT inPoint,
VARIANT *outPoint
);
Parameters
[in] targetCS: An IDispCoordSystem interface pointer used to specify the coordinate system to which input coordinates must
be converted.
[in] inPoint: A VARIANT used used to specify the coordinates of an input point. The coordinates are expressed in the current
coordinate system. The VARIANT must a one dimension array of 2 floating point values (VT_ARRAY | VT_R8). Element at index
0 is used to specify the x coordinate, element at index 1 is used to specify the y coordinate.
[out] outPoint: A pointer to a VARIANT used to return the coordinate of the inPoint input point expressed in the targetCS coor‐
dinate system. The type of the VARIANT returned is VT_ARRAT | VT_R8 : a one dimension array of 2 floating point values.
Element at index 0 is used to specify the x coordinate, element at index 1 is used to specify the y coordinate.
Example
Public Sub ConvertSitesCoordinates
Dim sites
Dim x
Dim y
Dim oFrom
Set oFrom = ActiveDocument.CoordSystemInternal
Dim oTo
Set oTo = ActiveDocument.CoordSystemDisplay
Dim coords
Set sites = ActiveDocument.GetRecords("Sites", True)
Dim i
For i = 1 To sites.RowCount
x = sites.GetValue(i, "LONGITUDE")
y = sites.GetValue(i, "LATITUDE")
coords = oFrom.ConvertCoordsTo(oTo, Array(x, y))
104
LogMessage sites.GetValue(i,"NAME")&":"&CStr(coords(0))&";"&CStr(coords(1))
Next
End Sub
8.4 Datum
Returns or sets the numeric value of the datum.
HRESULT Datum(long *pVal);
HRESULT Datum(long val);
Parameters
pVal: Address read as the datum code of the system.
val: Value to be set as the datum code of the system.
8.5 DatumName
Name of the datum.
HRESULT DatumName(BSTR *pVal);
Parameters
pVAl: Pointer of the datum name.
8.6 Description
Description of the datum.
HRESULT Description(BSTR *pVal);
Parameters
pVal: Pointer of datum description.
8.7 Ellipsoid
Returns or sets the numeric value of the ellipsoid.
HRESULT Ellipsoid(long* pVal);
HRESULT Ellipsoid(long Val);
Parameters
pVal: Address read as the ellipsoid code of the system.
val: Value to be set as the ellipsoid code of the system.
8.8 EllipsoidName
Name of the ellipsoid.
105
HRESULT EllipsoidName(BSTR* pVal);
Parameters
pVal: Pointer to the name of the ellipsoid.
8.9 Name
Returns or sets the name of the coordinates system.
HRESULT Name(BSTR *pVal);
HRESULT Name(BSTR pVal); [id(8)]
Parameters
pVal: Address read as the name of the coordinates system.
val: Value to be set as the name of the coordinates system.
8.10 Pick
Opens the coordinates system dialogue.
HRESULT Pick(OLE_HANDLE parentWindow, WORD types, VARIANT_BOOL *ret);
Parameters
parentWindow: OLE_HANDLE of the parent window for which the dialogue is required to be opened.
types: Bitset of CoordSysType (see CoordSysTypes) corresponding to the types of systems the dialogue must filter before
opening.
ret: Pointer to a VARIANT_BOOL, set to VARIANT_TRUE if the user quits the dialogue with OK, otherwise VARIANT_FALSE.
CoordSysTypes
enum CoordSysType
{ fgUndefinedCoordSys = 1,
fgGeographic2D = 2,
fgProjected2D = 4
} CoordSysType;
8.11 ProjMethod
Projection method used for the current coordinates system.
HRESULT ProjMethod(ProjectionMethod *pVal);
Parameters
pVal: Pointer to the read ProjectionMethod (see ProjectionMethods).
106
8.12 ProjParameter
Reads a parameter of the projection.
HRESULT ProjParameter(ProjParameterIndices index, double *pVal);
Parameters
index: Index of the parameter to read.
pVal: Address of the double containing the value of the parameter.
Remarks
Keep in mind that the real valid range of index parameters depends on the projection method.
8.13 SetDatum
Changes the datum of the system.
HRESULT SetDatum(long ellipsoidCode, VARIANT params);
Parameters
ellipsoidCode: Numeric code of the ellipsoid of the new datum.
params: Parameters of the projection provided as an array of variants.
8.14 SetProjection
Sets the projection parameters of the coordinate system.
HRESULT SetProjection(ProjectionMethod method, VARIANT projectionParameters);
Parameters
[in] method: The ProjectionMethod enumeration value used to change the projection method of the coordinate system.
[in] projectionParameters: A SAFEARRAY of VARIANTs of type VT_R8 used to specify the projection parameters of the coordi‐
nate system. The projection parameters must match with the method parameter. Each parameter is identified by its index in
the array, starting from 0. Array indexes are the same as ProjParameterIndices enumeration values. Projection parameters
values are the the same as values returned by the ProjParameter property.
8.15 Unit
Returns or sets the unit of the coordinate system.
HRESULT Unit(GeographicUnit *pVal);
HRESULT Unit(GeographicUnit newVal);
Parameters
pVAl: Address of the current geographic unit (see GeographicUnits) of the system.
newVal: New value for the geographic unit.
107
108
Chapter 9
ChildFolder Object
110
AT321_TAG_E4 Chapter 9: ChildFolder Object
9 ChildFolder Object
A ChildFolder object represents an item in the application explorer window. It can be a collection of sub‐items.
The ChildFolder object provides the following properties and methods:
get_Application Returns the Application object.
Access: Read
Type: ChildFolder object
get_Parent Returns the parent ChildFolder object.
Access: Read
Type: String
get_Name Returns the ChildFolder object display name.
Access: Read/Write
Type: String
put_Name Sets the ChildFolder object display name.
Access: Read/Write
Type: Integer
get_Count Returns the number of children of the ChildFolder object.
Access: Read
Type: ChildFolder children
get_Item Returns one of the children of the ChildFolder object. collection
Access: Read
Returns an object used to enumerate the children of the
get__NewEnum
ChildFolder object.
Type: Boolean
get_Visible Returns the visibility state of the ChildFolder object.
Access: Read/Write
Type: Boolean
put_Visible Sets the visibility state of the ChildFolder object.
Access: Read/Write
Type: Boolean
get_Selected Returns the selected state of the ChildFolder object.
Access: Read/Write
Type: Boolean
put_Selected Sets the selected state of the ChildFolder object.
Access: Read/Write
Export Exports a ChildFolder object to a file, in a given format.
Centres the application map window around the
CentreOnMap
ChildFolder object.
Redraw Redraws the ChildFolder object.
AddChild Adds a new child to the current ChildFolder object.
Removes the ChildFolder object from its parent ChildFolder
Remove
object.
Returns the ChildFolder object position relative to its Type: Integer
get_position
parent ChildFolder object. Access: Read/Write
Sets the ChildFolder object position relative to its parent Type: Integer
put_position
ChildFolder object. Access: Read/Write
get_Object Access to some specific features on the ChildFolder object.
get_dispatch Access to some specific features on the ChildFolder object.
Type: String
get_ObjectKind Returns a type identifier of the ChildFolder object.
Access: Read
GetProperty Returns a ChildFolder object property.
SetProperty Sets a ChildFolder object property.
111
Chapter 9: ChildFolder Object © Forsk 2014
Returns names and types for all properties available on the
GetPropertiesInfo
ChildFolder object.
Returns true when a ChildFolder object property is a
PropertyIsPropertyContainer
PropertyContainer object.
Returns true when a ChildFolder object property a
PropertyIsTabularData
TabularData object.
Sets properties from a property container to the
LoadProperties
ChildFolder object.
Saves all the ChildFolder object properties to another
SaveProperties
property container.
RemoveItem Removes one of the children of the ChildFolder object.
SetCustomIcon Sets the path of an icon to use for a custom child folder.
9.1 How to Access a ChildFolder Object
A ChildFolder is first obtained through a root entry point from the document and is related to a tab of the Atoll Explorer
window.
Most ChildFolder objects may have children, can be selected, set visible, and renamed. Only coverage predictions may be
exported.
Dim folder
Dim item
Dim doc
Dim dataRoot
Const atoData = 0
Set doc = Atoll.ActiveDocument
Set dataRoot = doc.GetRootFolder(atoData)
For Each folder in dataRoot
‘ do some work with this folder, for instance:
For Each item in folder
‘ do some work with this item
Next
Next
9.2 get_Application
112
Parameters
9.3 get_Parent
Returns the parent Atoll ChildFolder object.
HRESULT get_Parent(VARIANT *pVal);
Parameters
[out] pVal: Address of the VARIANT used to return the parent ChildFolder object. The type of the returned VARIANT is
VT_DISPATCH. When the ChildFolder object is a root ChildFolder object, the IDispatch interface pointer of the Atoll Document
is returned, otherwise the IDispatch interface pointer of the parent ChildFolder object is returned.
9.4 get_Name
Returns the ChildFolder object display name.
Parameters
[out] pVal: Address of the BSTR used to return the display name.
Example
Renaming the "Transmitters" folder.
Dim folder
Dim dataTab
Dim folderName
Const atoData = 0
Set dataTab = ActiveDocument.GetRootFolder(atoData)
For Each folder In dataTab
folderName = folder.Name
If folderName = “Transmitters” Then
folder.Name = “TransmittersTest”
End if
Next
9.5 put_Name
Sets the ChildFolder object display name.
HRESULT put_Name(const BSTR aNewVal);
113
Parameters
[in] aNewVal: The BSTR used to specify the display name.
Example
See "get_Name" on page 113.
9.6 get_Count
Returns the number of children of the ChildFolder object.
HRESULT get_Count(long *pVal);
Parameters
[out] pVal: Address of the long integer used to return the number of children.
9.7 get_Item
Returns one of the children of the ChildFolder object.
HRESULT get_Item(const VARIANT iIdx, IChildFolder **pVal);
Parameter
[in] iIdx: A VARIANT of type VT_I4 or VT_BSTR identifying the returned ChildFolder object. If the type of the variant is VT_I4,
it is interpreted as a zero‐based index in the list of children. If the type of the variant is VT_BSTR, it is first interpreted as the
display name of the child to search for, and if the display name is not found, it is then interpreted as a ChildFolder object kind,
as returned by get_ObjectKind.
[out] pVal: Address of the IChildFolder interface pointer used to return a ChildFolder object.
9.8 get__NewEnum
Returns an object used to enumerate the children of the ChildFolder object.
HRESULT get__NewEnum(LPUNKNOWN *ppUnk);
Parameters
[out] ppUnk: Address of the IUnknown interface pointer used to return the enumerator object. The IEnumVARIANT interface
is implemented by the enumerator object.
Example
Const atoModule = 2
Set modules = app.ActiveDocument.GetRootFolder(atoModule)
For Each module In modules
‘ do something with module
Next
9.9 get_Visible
Returns the visibility state of the ChildFolder object.
114
HRESULT get_Visible(VARIANT_BOOL *pVal);
Parameters
[out] pVal: Address of the VARIANT_BOOL used to return the visibility state.
The visibility state values are:
VARIANT_TRUE : the ChildFolder object may be displayed on Atoll Map View windows.
VARIANT_FALSE : the ChildFolder object won’t be displayed on Atoll Map View windows.
Remarks
The visibility state only makes sense for ChildFolder objects that may appear on Atoll Map View windows. get_Visible and
put_Visible calls are ignored for objects that do not support it. No error is returned.
Example
dataFolder.Item("Predictions").Visible = True
9.10 put_Visible
Sets the visibility state of the ChildFolder object.
HRESULT put_Visible(VARIANT_BOOL aNewVal);
Parameters
[in] aNewVal: The VARIANT_BOOL used to specify the visibility state.
The visibility state values are:
VARIANT_TRUE : the ChildFolder object may be displayed on Atoll Map View windows.
VARIANT_FALSE : the ChildFolder object won’t be displayed on Atoll Map View windows.
Remarks
The visibility state only makes sense for ChildFolder objects that may appear on Atoll Map View windows. get_Visible and
put_Visible calls are ignored for objects that don’t support it. No error is returned.
Example
dataFolder.Item("Predictions").Visible = True
9.11 get_Selected
Returns the selected state of the ChildFolder object.
HRESULT get_Selected(VARIANT_BOOL *pVal);
Parameters
[out] pVal: Address of the VARIANT_BOOL used to return the selected state of the ChildFolder object.
Remarks
get_Selected and put_Selected calls are ignored for objects that don’t support it. No error is returned.
115
Example
Public Sub SelectTx
Const atoData = 0
Set dataFolder = doc.GetRootFolder(atoData)
’ Select the "Site0_0" transmitter
For Each folder In dataFolder
If folder.Name = "Transmitters" Then
folder.Item("Site0_0").Selected = True
End If
Next
End Sub
9.12 put_Selected
Sets the selected state of the ChildFolder object.
HRESULT put_Selected(VARIANT_BOOL aNewVal);
Parameters
[in] newVal: The VARIANT_BOOL used to specify the selected state.
Remarks
get_Selected and put_Selected calls are ignored for objects that don’t support it. No error is returned.
Example
See "get_Selected" on page 115.
9.13 Export
Exports a ChildFolder object to a file, in a given format. This method can only be used for studies.
HRESULT Export(
const BSTR bstrFileName,
IDispCoordSystem* proj,
const BSTR bstrFormat
);
Parameters
[in] bstrFileName: A string containing an absolute file path.
[in] proj: An IDispCoordSystem interface pointer used to define the coordinate system for the export.
[in] bstrFormat: A string used to define the format of the file specified by bstrFileName.
116
The syntax for the bstrFormat parameter is:
PropertyName=Value;[PropertyName=Value;]format
format:
• Available values are:
• SHP
• AGD
• MIF
• TAB
• BMP
• TIF
• TXT
• ARCVIEWGRIDASCII
• PNG
• JP2
Please read the application documentation to learn more about these file formats.
The data exported is the geographic coverage prediction of a study when using SHP, AGD, MIF, TAB, BMP, ARCVIEW‐
GRIDASCII, PNG, JP2, or TIF formats. However, if you specify TXT format, this method will export the study report in
tabulated ASCII text format. This prediction study report is the same as the one available by right‐clicking the study in
the application and selecting Generate Report.
Available properties are:
Property Name Value Version Description

This is the export resolution, expressed in meter.
If not specified, the resolution used to perform the export is
Resolution integer  2.8.1 the study resolution.
It is only relevant when the export format is a vector format,
as opposed to a raster format.
Used to specify the zone to export. Available values are:
0 : The Entire Covered Area
1 : The Computation Zone
2 : The Geographic Export Zone
AreaType 0|1|2  2.8.1
If not specified, the entire covered area is considered to
perform the export.
It is only relevant for raster formats, as opposed to vector
formats.
Return Value
S_OK: Export has completed successfully.
S_FALSE: Export couldn’t be performed because of one of the following reasons:
• The folder specified in bstrFileName does not exist.
• The study visibility check box is cleared.
• The study has no coverage.
When S_FALSE is returned, no output file is created.
Example
Const SID_PREDICTIONS = "{DA676EF0-E300-4AFF-BBFA-EC55D3798E4F}"
Public Sub ExportStudy
Dim oStudy
Dim oCS
Set oCS = ActiveDocument.CoordSystemDisplay
117
For Each oStudy In ActiveDocument.GetRootFolder(0).Item(SID_PREDICTIONS)
oStudy.Export "c:\export.asc", oCS, "ARCVIEWGRIDASCII"
oStudy.Export "c:\export.txt", oCS, "TXT"
oStudy.Export "c:\export.bmp", oCS, "BMP"
Next
End Sub
9.14 CentreOnMap
Centres the Atoll Map View window around the ChildFolder object.
HRESULT CentreOnMap(void);
Remarks
CentreOnMap only makes sense for ChildFolder objects that may appear on Atoll Map View windows. CentreOnMap calls will
be ignored for objects that don’t support it. No error will be returned.
9.15 Redraw
Redraws the ChildFolder object.
HRESULT Redraw(void);
Remarks
Redraw only makes sense for ChildFolder objects that may appear on Atoll Map View windows. Redraw calls will be ignored
for objects that don’t support it. No error will be returned.
9.16 AddChild
Adds a new child to the current Atoll child folder object.
HRESULT AddChild(const VARIANT spec, long position, IChildFolder2** pVal)
Parameters
[in] spec: VARIANT used to define the child item to add.
[in] position: The position used to define where to add the new child.
[out] pVal: Address of a IChildFolder2 interface pointer used to return the new Atoll child folder object just added.
Remark
The type of the child added depends on the type of the spec input parameter.
When spec if of type VT_UNKNOWN or VT_DISPATCH, and when it is an Atoll ChildFolder object, spec is interpreted as a source
ChildFolder object. AddChild will add a link to the source ChildFolder object. The source Atoll ChildFolder cannot be a link
itself. Links can only be created at the root level of the Atoll Explorer geo or data tabs. Links always are created at position 0.
The source ChildFolder object and the current ChildFolder object must belong to different Atoll documents.
When spec if of type VT_UNKNOWN or VT_DISPATCH, and when it is an Atoll PropertyContainer object, then a new Child‐
Folder is added with the content of the Atoll PropertyContainer object. The properties needed to actually be able to add a
new ChildFolder object depend on the current ChildFolder object type, as returned by ObjectKind.
118
9.17 Remove
Removes the ChildFolder object from its parent ChildFolder object.
HRESULT Remove(void);
Remarks
A ChildFolder object cannot be used anymore after it is removed. ChildFolder objects may be removed by Atoll, for instance
when F5 is used interactively to refresh the screen.
Atoll version >= 2.8.2:
This method is deprecated. Please use RemoveItem instead.
9.18 get_position
Returns the ChildFolder object position relative to its parent ChildFolder object.
HRESULT get_position(long *pPos);
Parameters
[out] pPos: Address of the long integer used to return the ChildFolder object position. ChildFolder objects are ordered from
position 0 (top) to to get_Count() ‐ 1 (bottom).
9.19 put_position
Sets the ChildFolder object position relative to its parent ChildFolder object.
HRESULT put_position(long lPos);
Parameters
[in] lPos: A long integer used to specify the ChildFolder object position.
• If lPos  0, the ChildFolder object is moved to the top.
• If lPos  get_Count() ‐ 1, the ChildFolder object is moved to the bottom.
9.20 get_Object
Access to some specific features on the ChildFolder object.
HRESULT get_Object(IUnknown **ppObject);
Parameters
[out] ppObject: Address of the IUnknown interface pointer used to access some specific features.
Remarks
Due to the nature of the interface returned, get_Object cannot be used by macros and scripts. Macros or scripts must use
get_dispatch instead.
9.21 get_dispatch
Access to some specific features on the ChildFolder object.
119
HRESULT get_dispatch(IDispatch **ppDispatch);
Parameter
[out] ppDispatch: Address of the IDispatch interface pointer used to access some specific features.
9.22 get_ObjectKind
Returns a type identifier of the ChildFolder object.
HRESULT get_ObjectKind(BSTR *pRetVal);
Parameters
[out] pRetVal: Address of the BSTR used to return the type identifier.
Remarks
To be able to identify the ChildFolder object type, and therefore to safely access specific features of the ChildFolder object,
here is the list of the available type identifiers:
Version SID String Value Specific Features
Tabular data clutter
 2.4.0 SID_CLUTTER {7CB51DE8‐A961‐11D2‐8688‐0060086457D1}
properties.
 2.4.0 SID_SIMULATIONS {CDDF1E1D‐1963‐4D80‐A057‐D23A19570984} Simulations folder.
"Groups of simulations"
 2.4.0 SID_SIMULATIONSGROUP {AF5E2B98‐1D54‐48FA‐89C5‐8BFA2936ABF2}
folder.
 2.4.0 SID_SIMULATION {095C5D90‐96F1‐4BA8‐85BB‐B2F990AC2DD9} "Simulation" items.
 2.5.1 SID_SITES {90443F68‐5B3B‐4AFD‐B7BB‐B057095EBAAD} Sites folder.
 2.5.1 SID_ANTENNAS {5FBEB2AE‐3BBB‐4FBA‐94D8‐5D8EA5A32069} Antennas folder.
Transmitters folder, in a
 2.5.1 SID_TRANSMITTERS {F7E891E8‐F7F5‐4870‐BF63‐AF559AD50FD3}
single‐RAT document.
 2.5.1 SID_PREDICTIONS {DA676EF0‐E300‐4AFF‐BBFA‐EC55D3798E4F} Predictions folder.
 2.5.1 SID_UMTS_PARAMETERS {D4F57EE3‐7785‐4348‐9BA6‐28998AA6BD80} UMTS Parameters folder.
 2.5.1 SID_CW_MEASUREMENTS {41413C4A‐C9DE‐43DD‐A917‐612A0AF198FC} CW Measurements folder.
CW Measurements
 2.5.1 SID_MEASURE_TX {2C102EE5‐BFF4‐4A5A‐8130‐02BD0E2F70D7}
transmitter.
 2.5.1 SID_MEASURE_ITEM {36858A48‐7A85‐482E‐9DA0‐B9E935ADE84C} CW Measurements.
 2.5.1 SID_TESTMOBILEDATA {21C11380‐D8CF‐4902‐B622‐763522AD9FC4} Drive Test Data folder.
 2.5.1 SID_NUM_MEASURE_ITEM {916801F9‐0539‐448C‐8C0C‐491FAC6399ED} Drive Test Data items.
 2.5.1 SID_PARAMETERS_FOLDER {43B8845‐5226‐454F‐908F‐59A500DB4FD1} Parameters folder.
120
 2.5.1 SID_HEXAGON_SCHEMA {B167D45E‐A0BC‐4DC6‐B9D7‐6F7B131CADF1} Hexagonal Design folder.
 2.6.0 SID_TRAFFICFOLDER {B3B25A07‐A994‐4e8d‐BBD1‐51556D6C4245} Traffic folder.
 2.7.0 SID_PROPAGATIONMODELS {4A2D160B‐7D11‐4D07‐92DF‐A3CF6B68D402} Propagation models folder.
Master link ChildFolder
 2.8.2 {16A53FB3‐A961‐4EEA‐8C30‐2387DBF1CC24}
object.
 2.8.2 {232BDB73‐A68F‐41A6‐A954‐75112D907BBF} Link ChildFolder object.
GSM Transmitters folder, in a
 3.1.0 {CC637062‐7AFF‐4516‐BEFB‐BCC954E905B1}
multi‐RAT document.
LTE Transmitters folder, in a
 3.1.0 {FD147AA0‐B9A2‐47AC‐8CD5‐51C77A708AF8}
multi‐RAT document.
UMTS Transmitters folder, in
 3.1.0 {090A23A1‐EE08‐420D‐9739‐651D1045EF16}
a multi‐RAT document.
CDMA2000 Transmitters
 3.2.0 {65FF5F7D‐DBF0‐4B52‐ABB8‐66F3414FD4C3} folder, in a multi‐RAT
document.
A sub‐folder of the
 3.2.1 StudyFolder
predictions folder.
9.23 GetProperty
Returns a ChildFolder object property.
HRESULT GetProperty(const BSTR bstrName, VARIANT *pValue);
Parameters
[in] bstrName: A property name.
[out] pValue: Address of the VARIANT used to return the property.
Remarks
The type of the returned VARIANT can be any of the following:
C++ VBScript
VT_BOOL Boolean
VT_I4 Integer
VT_R4 Single
VT_R8 Double
VT_UNKNOWN Object
Object, TabularData object, ChildFolder object, PropertyContainer
VT_DISPATCH
object
VT_BSTR String
VT_ARRAY | (any of the previous types) Array, with array items of the previous types
The error E_INVALIDARG is returned when there is no property named bstrName for the ChildFolder object. The properties
available for the ChildFolder object depend on the type of the ChildFolder object, as returned by get_ObjectKind.
121
9.24 SetProperty
Sets a ChildFolder object property.
HRESULT SetProperty(const BSTR bstrName, const VARIANT varValue);
Parameters
[in] varValue: The VARIANT used to specify the property value.
Remarks
The error E_INVALIDARG is returned when there is no property named bstrName for the ChildFolder object. The properties
available for the ChildFolder object depend on the type of the ChildFolder object, as returned by get_ObjectKind.
9.25 GetPropertiesInfo
Returns names and types for all properties available on the ChildFolder object.
HRESULT GetPropertiesInfo(VARIANT *pValue);
Parameters
[out] pValue : Address of the VARIANT used to return the names and types for all properties in the property container.
9.26 PropertyIsPropertyContainer
Returns true when a ChildFolder object property is a PropertyContainer object.
HRESULT
PropertyIsPropertyContainer(const BSTR bstrName, VARIANT_BOOL *pValue);
Parameters
[in] bstrName : The property name.
[out] pValue: Address of the VARIANT_BOOL used to return whether the property is a PropertyContainer object or not.
9.27 PropertyIsTabularData
Returns true when a ChildFolder object property is a TabularData object.
HRESULT PropertyIsTabularData(const BSTR bstrName, VARIANT_BOOL *pValue);
Parameters
[out] pValue: Address of the VARIANT_BOOL used to return whether the ChildFolder property type is TabularData object.
9.28 LoadProperties
Sets properties from a property container to the ChildFolder object.
HRESULT LoadProperties(const VARIANT varSource);
122
Parameters
[in] varSource : VARIANT of type VT_DISPATCH, used to specify a property container for the properties to set.
9.29 SaveProperties
Saves all the ChildFolder object properties to another property container.
HRESULT SaveProperties( const VARIANT varDestination) ;
Parameters
[in] varDestination : VARIANT of type VT_DISPATCH, used to specify a property container where all properties will be set.
9.30 RemoveItem
Removes one of the children of the ChildFolder object.
HRESULT RemoveItem( const VARIANT idx) ;
Parameters
[in] idx : A VARIANT of type VT_I4 or VT_BSTR used to specify one of the children to remove.
If the type of the variant is VT_I4, it is interpreted as a zero‐based index in the list of children.
If the type of the variant is VT_BSTR, it is first interpreted as the display name of the child to remove, and if the display name
is not found, it is then interpreted as a ChildFolder object kind, as returned by get_ObjectKind.
Remarks
A ChildFolder object cannot be used anymore after it is removed. ChildFolder objects may be removed by the application, for
instance when F5 is used interactively to refresh the screen.
This method fails for ChildFolder objects that cannot be removed interactively, and an error is returned in that case.
9.31 SetCustomIcon
Sets the path of an icon to use for a custom child folder.
HRESULT SetCustomIcon(const BSTR bstrPath);
Parameters
[in] bstrPath : The full path to the icon file (*.ico) to load.
9.32 OpenPropertySheet
Displays the child folder property sheet dialogue.
HRESULT OpenPropertySheet();
Parameters:
123
124
Chapter 10
PropertyContainer
Object
126
AT321_TAG_E4 Chapter 10: PropertyContainer Object
10 PropertyContainer Object
The PropertyContainer object is a generic container containing a set of named properties of arbitrary types.
The PropertyContainer object provides the following properties and methods:
Get Returns a named property.
Set Sets a named property.
Returns names and types for all properties set to the property
GetInfo
container.
Returns true when a named property is of a Type: Boolean
IsPropertyContainer
PropertyContainer object. Access: Read
Returns true when a named property is of a TabularData Type: Boolean
IsTabularData
object. Access: Read
Adds properties from another property container to the
Load
property container.
Save Saves all the properties to another property container.
RemoveAll Removes all properties from the property container.
Remove Removes a named property from the property container.
10.1 Get
Returns a named property.
HRESULT Get(const BSTR bstrName, VARIANT *pValue);
Parameters
[out] pValue: Address of the VARIANT used to return the property.
Remarks
The type of the returned VARIANT can be any of the following:
C++ VBScript
VT_BOOL Boolean
VT_I4 Integer
VT_R4 Single
VT_R8 Double
VT_UNKNOWN Object
Object, TabularData Object, ChildFolder Object, PropertyContainer
VT_DISPATCH
Object
VT_BSTR String
VT_ARRAY | (any of the previous types) Array, with array items of the previous types
127
Chapter 10: PropertyContainer Object © Forsk 2014
The error E_INVALIDARG is returned when the property named bstrName has not been previously set to the property
container.
10.2 Set
Sets a named property.
HRESULT Set(const BSTR bstrName, const VARIANT varValue);
Parameters
[in] varValue: The VARIANT used to specify the property value.
Remarks
If the property named bstrName has been previously set, its content is replaced by varValue, otherwise a new property named
bstrName is added to the property container.
10.3 GetInfo
Returns names and types for all properties set to the property container.
HRESULT GetInfo(VARIANT *pValue);
Parameters
[out] pValue : Address of the VARIANT used to return the names and types for all properties in the property container.
10.4 IsPropertyContainer
Returns true when a named property is a PropertyContainer object.
HRESULT IsPropertyContainer(const BSTR bstrName, VARIANT_BOOL *pValue);
Parameters
[out] pValue: Address of the VARIANT_BOOL used to return whether the property is a PropertyContainer Object.
10.5 IsTabularData
Returns true when a named property is a TabularData object.
HRESULT IsTabularData(const BSTR bstrName, VARIANT_BOOL *pValue);
Parameters
[out] pValue: Address of the VARIANT_BOOL used to return whether the property is a Tabular Data Object.
10.6 Load
Adds properties from another property container to the property container.
128
AT321_TAG_E4 Chapter 10: PropertyContainer Object
HRESULT Load(const VARIANT varSource);
Parameters
[in] varSource : VARIANT of type VT_DISPATCH, used to specify a property container for the properties to add.
10.7 Save
Saves all the properties to another property container.
HRESULT Save(const VARIANT varDestination);
Parameters
[in] varDestination : VARIANT of type VT_DISPATCH, used to specify a property container where all properties will be set.
10.8 RemoveAll
Removes all properties from the property container.
HRESULT RemoveAll(void);
10.9 Remove
Removes a named property from the property container.
HRESULT Remove(const BSTR bstrName, VARIANT *pValue);
Parameters
[out] pValue: Address of the VARIANT used to return the original property value, before it is removed.
129
Chapter 10: PropertyContainer Object © Forsk 2014
130
Chapter 11
ChildFolder Object
Properties
132
AT321_TAG_E4 Chapter 11: ChildFolder Object Properties
11 ChildFolder Object Properties
ChildFolder object properties are named properties. The set of available properties for a given ChildFolder object depends on
the ChildFolder object type, returned by get_ObjectKind.
ChildFolder object property names usually resemble their GUI representations in the properties dialogues inside Atoll.
ChildFolder object properties are divided into the following groups according to their use and application in Atoll:
• "Common ChildFolder Object Properties" on page 134,
• "Predictions Folder Properties" on page 134,
• "Coverage Prediction Properties" on page 135,
• "GSM Simulation Group Properties" on page 142,
• "UMTS Simulation Group Properties" on page 143,
• "WiMAX and LTE Simulation Group Properties" on page 144,
• "3GPP Multi‐RAT Simulation Group Properties" on page 145,
• "Propagation Model Properties" on page 146,
• "CW Measurement Properties" on page 148,
• "Drive Test Data Properties" on page 149,
• "Custom ChildFolder Object Properties" on page 149,
• "Master Link Properties" on page 150,
• "Link Properties" on page 150,
• "Vector Layer Properties" on page 150.
11.1 How to Access ChildFolder Object Properties
The following sample codes show how to read and write ChildFolder Object properties.
Reading a ChildFolder Object Property
item: A ChildFolder object.
propertyname: The property name.
propertyvalue: The property value.
’ If the property type is an Object (Atoll Tabular Data Object, Atoll Property
’ Container Object, ...), then replace the next line with
’ "Set propertyvalue = item.GetProperty(propertyname)"
propertyvalue = item.GetProperty(propertyname)
If Err Then
MsgBox item.Name & "." & propertyname & "does not exist."
Else
MsgBox item.Name & "." & propertyname & " = " & CStr(propertyvalue)
End If
Writing a ChildFolder Object Property
item: A ChildFolder object.
propertyname: The property name.
propertyvalue: The property value.
133
Chapter 11: ChildFolder Object Properties © Forsk 2014
item.SetProperty propertyname, propertyvalue
If Err Then
MsgBox Err.Description
End If
11.2 Common ChildFolder Object Properties
Some ChildFolder object properties are common to all kinds of ChildFolder objects. These properties include the following.
Version  : 2.6.1
NAME ChildFolder object name as it appears in the Explorer window. Type: String
Access: Read/Write
Version  : 2.6.1
ChildFolder visibility state. This property is only relevant for
VISIBLE Type: Boolean
geographic ChildFolder objects.
Access: Read/Write
Version  : 2.6.1
SELECTED ChildFolder selected state, either selected or not selected. Type: Boolean
Access: Read/Write
Version  : 2.6.1
POSITION ChildFolder position, relative to the parent ChildFolder object. Type: Integer
Access: Read/Write
Version  : 2.7.0
ChildFolder type identifier. This is the same as the value returned
OBJECTKIND Type: String
by get_ObjectKind.
Access: Read
Returns true if the ChildFolder object can be visible in the Map
Version  : 2.7.0
window, false otherwise.
ISGEOGRAPHIC Type: Boolean
When this property is false, the properties and methods specific
Access: Read
to the Map view are neither relevant nor applicable.
Version  : 2.7.0
ChildFolder minimum visibility scale display property. This
VISIBILITYSCALEMIN Type: Integer
property is only relevant for geographic ChildFolder objects.
Access: Read/Write
Version  : 2.7.0
ChildFolder maximum visibility scale display property. This
VISIBILITYSCALEMAX Type: Integer
property is only relevant for geographic ChildFolder objects.
Access: Read/Write
Version  : 2.7.0
ChildFolder add to legend display property. This property is only
ADDTOLEGEND Type: Boolean
relevant for geographic ChildFolder objects.
Access: Read/Write
Version  : 2.8.2
A Document object.
DOCUMENT Type: Object
The ChildFolder object is part of the Document object.
Access: Read
Version  : 3.2.0
LEGEND ChildFolder object name as it appears in the Legend window. Type: String
Access: Read/Write
11.3 Predictions Folder Properties
Type returned by get_ObjectKind: {DA676EF0‐E300‐4AFF‐BBFA‐EC55D3798E4F}
The following properties are accessible through the Predictions folder.
134
Version  : 2.6.1
Path to the path loss matrices private storage folder, as it appears
PRIVATESTORAGE Type: String
in the Predictions folder properties.
Access: Read/Write
11.4 Coverage Prediction Properties
The coverage prediction types returned by get_ObjectKind for the various coverage predictions are listed below:
• "GSM GPRS EDGE Coverage Predictions" on page 135,
• "UMTS HSPA Coverage Predictions" on page 135,
• "WiMAX Coverage Predictions" on page 136,
• "LTE Coverage Predictions" on page 136.
Coverage prediction properties are of the following types:
• "General Properties" on page 137,
• "Group, Filter, and Sort Properties" on page 137,
• "Non‐Simulation‐based Coverage Conditions" on page 138: Coverage conditions for predictions that cannot be based
on simulations,
• "Simulation‐based Coverage Conditions" on page 139: Coverage conditions for predictions that can be based on sim‐
ulations,
• "Shadowing and Indoor Coverage Conditions" on page 140,
• "Display Properties" on page 140.
GSM GPRS EDGE Coverage Predictions
Name ObjectKind Attributes

Coverage by Transmitter {9E42C87F‐56D0‐43CA‐A313‐78A7CA9A811B}
Coverage by Signal Level {1FF20277‐9A4C‐486A‐B0A4‐90E7E8EC72E4}
Overlapping Zones {1F0C294B‐11A0‐45C9‐9B32‐640FED79BCA6}
Coverage by C/I Level {8A94CAE7‐B4FF‐4DC6‐854A‐BC90FE8F0073}
Interfered Zones {EB45E33D‐FB33‐44F1‐A63B‐B4661ACE78B2}
Coverage by GPRS/EDGE Coding
{6B062215‐EEC1‐40E9‐9A02‐F909AFF6B5DB}
Scheme
RLC/MAC Throughput/Timeslot {02BE397A‐1F4B‐423E‐AEC4‐B8138974ADD8}
Application Throughput/Timeslot {3F8F8CB3‐A5DC‐49F9‐8F3D‐0E7243AA0E6C}
Circuit Quality Indicator Analysis {67EC97E9‐9F06‐4B0F‐90C0‐E42A67FE560C}
Coverage by C/I Level (UL) {549A79FF‐D191‐4486‐B6D8‐A1544633BC26} Version  : 3.2.1
UMTS HSPA Coverage Predictions

Coverage by Transmitter {A6FB7132‐FB5E‐42CC‐A1C1‐0BEA4AF09921}
Coverage by Signal Level {E82C3B13‐240E‐4DD3‐A553‐583ADDF57713}
Overlapping Zones {53B30925‐B781‐499D‐90E4‐3F9B8570871B}
Coverage by Total Noise Level (DL) {1C9384EB‐57CA‐433F‐BDB3‐07E1BE317890}
Pilot Quality Analysis (Ec/Io) {66287FC5‐81FA‐40B6‐84E3‐2C2C4E13D121}
Service Area Analysis (Eb/Nt) (DL) {5C6427F7‐D63A‐4046‐B8BD‐1A5E9D165890}
Service Area Analysis (Eb/Nt) (UL) {D75ADE37‐FB8A‐4693‐A788‐47109A913C29}
135

Effective Service Area Analysis (Eb/
{5F74AEFA‐2958‐42CC‐8244‐C12DC19B26C3}
Nt) (DL+UL)
Handoff Zones {39A63BBA‐02EC‐43E7‐8523‐07E29B519181}
Pilot Pollution Analysis {2199E577‐F3F5‐4FFD‐BCAB‐0D748CA7CCD3}
HSDPA Quality and Throughput
{BFDDFC83‐D8EE‐4225‐840F‐EF842DE19B74}
Analysis
HSUPA Quality and Throughput
{E9ED15F1‐EC14‐4451‐ADFA‐1953A6FB2526}
Analysis
Scrambling Code Collision Zones {AC612067‐A173‐439E‐BF7A‐76B17933A30E}
WiMAX Coverage Predictions
Coverage by Transmitter {BE607087‐CB08‐453C‐B2A0‐B356CD38C3F5} Version  : 2.7.1
Coverage by Signal Level {9C602E1C‐E5E7‐44CA‐8E5B‐878D74D07885} Version  : 2.7.1
Overlapping Zones {86560A81‐DE60‐41CC‐9B9E‐83BF33CEF491} Version  : 2.7.1
Effective Signal Analysis (DL) {6A657977‐CF0E‐415C‐8486‐C41664F7035E} Version  : 2.7.1
Effective Signal Analysis (UL) {3F803866‐1041‐4267‐8D28‐FCA43445A642} Version  : 2.7.1
Coverage by C/(I+N) Level (DL) {DCB4B756‐4D02‐42DB‐B838‐14A62F603922} Version  : 2.7.1
Coverage by C/(I+N) Level (UL) {4163305D‐E203‐4A78‐99F6‐E59EA537AB7E} Version  : 2.7.1
Coverage by Bearer (DL) {C5A270AA‐15A1‐443D‐BBCB‐77B1B99D447F} Version  : 2.7.1
Coverage by Bearer (UL) {A07FB550‐64C7‐4D2A‐B634‐79FC6A981828} Version  : 2.7.1
Coverage by Throughput (DL) {645C7166‐CE00‐4EFB‐B9AF‐A7F25A3BBBA6} Version  : 2.7.1
Coverage by Throughput (UL) {1A8B4ACB‐8D51‐49AA‐AA67‐3ADAB48F09B6} Version  : 2.7.1
Coverage by Aerial (DL) {4A9ED8C5‐F2DE‐432B‐8507‐C65A3DFE47E3} Version  : 3.2.0
LTE Coverage Predictions
Coverage by Transmitter {BE607087‐CB08‐453C‐B2A0‐B356CD38C3F5} Version  : 2.8.0
Coverage by Signal Level {9C602E1C‐E5E7‐44CA‐8E5B‐878D74D07885} Version  : 2.8.0
Overlapping Zones {86560A81‐DE60‐41CC‐9B9E‐83BF33CEF491} Version  : 2.8.0
Effective Signal Analysis (DL) {6A657977‐CF0E‐415C‐8486‐C41664F7035E} Version  : 2.8.0
Effective Signal Analysis (UL) {3F803866‐1041‐4267‐8D28‐FCA43445A642} Version  : 2.8.0
Coverage by C/(I+N) Level (DL) {DCB4B756‐4D02‐42DB‐B838‐14A62F603922} Version  : 2.8.0
Coverage by C/(I+N) Level (UL) {4163305D‐E203‐4A78‐99F6‐E59EA537AB7E} Version  : 2.8.0
Coverage by Bearer (DL) {C5A270AA‐15A1‐443D‐BBCB‐77B1B99D447F} Version  : 2.8.0
Coverage by Bearer (UL) {A07FB550‐64C7‐4D2A‐B634‐79FC6A981828} Version  : 2.8.0
Coverage by Throughput (DL) {645C7166‐CE00‐4EFB‐B9AF‐A7F25A3BBBA6} Version  : 2.8.0
136
Coverage by Throughput (UL) {1A8B4ACB‐8D51‐49AA‐AA67‐3ADAB48F09B6} Version  : 2.8.0
Coverage by Quality Indicator (DL) {B682A005‐CCC2‐4C7C‐A9FA‐D2FEBA633E15} Version  : 2.8.0
Coverage by Quality Indicator (UL) {E648833C‐48E1‐49C0‐A56F‐6B94DBA9C358} Version  : 2.8.0
11.4.1 General Properties
These properties are available for all kinds of coverage predictions.
Version  : 2.7.0
DESCRIPTION Comments Type: String
Access: Read/Write
Version  : 2.7.0
RESOLUTION Resolution of the prediction, in meters. Type: Integer
Access: Read/Write
Version  : 2.7.0
Returns true when the prediction is locked for calculations,
LOCKED Type: Boolean
false otherwise.
Access: Read/Write
Version  : 2.7.0
Returns true when the prediction coverage is empty, false
ISEMPTY Type: Boolean
otherwise.
Access: Read
Returns true when the prediction is per transmitter, false Version  : 2.7.0

ISPERTRANSMITTER otherwise. The return value depends on the display field of Type: Boolean
the prediction. Access: Read
An empty string when the coverage prediction does not Version  : 3.2.1

URL have external numerical results, otherwise the absolute Type: String
path to the disk folder containing numerical results. Access: Read
11.4.2 Group, Filter, and Sort Properties
These properties are called RECORDSETCONDITIONS, which are available for all kinds of coverage predictions.
Name Attributes
Version  : 2.7.0
RECORDSETCONDITIONS
PropertyContainer object
The following RECORDSETCONDITIONS are available:
Version  : 2.7.0
"Group By" part of the recordset conditions, applied to the
GROUPBY Type: String
Transmitters table.
Access: Read/Write
Version  : 2.7.0
"Filter" part of the recordset conditions, applied to the
FILTER Type: String
Transmitters table.
Access: Read/Write
Version  : 2.7.0
"Sort" part of the recordset conditions, applied to the
SORT Type: String
Transmitters table.
Access: Read/Write
137
11.4.3 Non‐Simulation‐based Coverage Conditions
These properties are called COVERAGECONDITIONS.
Name Attributes
Version  : 2.7.0
COVERAGECONDITIONS
PropertyContainer object
These properties are available for the following coverage predictions:
• GSM GPRS EDGE:
‐ Coverage by Transmitter
‐ Coverage by Signal Level
‐ Overlapping Zones
‐ Coverage by C/I Level
‐ Interfered Zones
‐ Coverage by GPRS/EDGE Coding Scheme
‐ RLC/MAC Throughput/Timeslot
‐ Application Throughput/Timeslot
• UMTS HSPA:
• WiMAX (Version  : 2.7.1):
• LTE (Version  : 2.8.0):
The following COVERAGECONDITIONS are available:

The field type to base the prediction with.
Version  : 2.7.0
The values are: 1=Path Loss (dB); 2=Total Losses (dB);
FIELDTYPE Type: Integer
3=Signal Level (dBm); 4=Signal Level (dBµV); 5=Signal Level
Access: Read/Write
(dBµV/m);
The way to choose transmitters among available (active, not
filtered) ones for the current coverage prediction.
The values are: 0=All; 1=Best Signal Level; 2=Second Best
Signal Level; Version  : 2.7.0
SERVERTYPE For GSM GPRS EDGE documents, the following values are Type: Integer
also available: 3=Best Signal Level per HCS Layer; 4=Second Access: Read/Write
Best Signal per HCS Layer; 5=Best Signal Level of the Highest
Priority HCS Layer;
6=Best Idle Mode Reselection Criterion (C2);
The margin (in dB) from the best server signal level and
signal level from other servers taking part into the current
Version  : 2.7.0
coverage (available only if the best signal level or highest
SERVERMARGIN Type: Single
priority option is selected)
Access: Read/Write
e.g.: If the two best server signal levels are within the
margin, these are both considered in the coverage area.
GSM GPRS EDGE: The TRX type to take into account for the
Version  : 2.7.0
current coverage prediction (BCCH, TCH, TCH_EGPRS,
Type:
TCH_INNER).
TRXTYPE PropertyContainer
UMTS HSPA: The carrier number to take into account for the
object
current coverage prediction (ALL=Best; 0=Carrier number 0;
Access: Read/Write
1=Carrier number 1; 2=Carrier number 2;)
138
Whether to use the lower reception threshold defined for Version  : 2.7.0

USESUBCELLRECEPTIONTHRESHOLD the transmitter subcell or not. When set to True, the Type: Boolean
FIELDMINIMUM property is ignored. Access: Read/Write
The coverage prediction lower threshold associated with Version  : 2.7.0

FIELDMINIMUM the FIELDTYPE property. When set to ‐32768, no minimum Type: Single
value will be considered. Access: Read/Write
The coverage prediction upper threshold associated with Version  : 2.7.0

FIELDMAXIMUM the FIELDTYPE property. When set to 32767, no maximum Type: Single
value will be considered. Access: Read/Write
11.4.4 Simulation‐based Coverage Conditions
These properties are called SIMULATIONCONDITIONS.
Name Attributes
Version  : 2.7.0
SIMULATIONCONDITIONS
Type: PropertyContainer object
These properties are available for the following coverage predictions:
• UMTS HSPA:
‐ Coverage by Total Noise Level (DL)
‐ Pilot Quality Analysis (Ec/Io)
‐ Service Area Analysis (Eb/Nt) (DL)
‐ Service Area Analysis (Eb/Nt) (UL)
‐ Effective Service Area Analysis (Eb/Nt) (DL+UL)
‐ Handoff Zones
‐ Pilot Pollution Analysis
‐ HSDPA Quality and Throughput Analysis
‐ HSUPA Quality and Throughput Analysis
‐ Scrambling Code Collision Zones
• WiMAX:
‐ Coverage by C/(I+N) Level (DL)
‐ Coverage by C/(I+N) Level (UL)
‐ Coverage by Bearer (DL)
‐ Coverage by Bearer (UL)
‐ Coverage by Throughput (DL)
‐ Coverage by Throughput (UL)
• LTE (Version  : 2.8.0):
‐ Coverage by C/(I+N) Level (DL)
‐ Coverage by C/(I+N) Level (UL)
‐ Coverage by Bearer (DL)
‐ Coverage by Bearer (UL)
‐ Coverage by Throughput (DL)
‐ Coverage by Throughput (UL)
‐ Coverage by Quality Indicator (DL)
‐ Coverage by Quality Indicator (UL)
The following SIMULATIONCONDITIONS are available:
Version  : 2.7.0
TERMINAL The name of the terminal type used for the prediction. Type: String
Access: Read/Write
Version  : 2.7.0
MOBILITY The name of the mobility type used for the prediction. Type: String
Access: Read/Write
139
Version  : 2.7.0
SERVICE The name of the service used for the prediction. Type: String
Access: Read/Write
The name of the simulation used for the prediction. When Version  : 2.7.0

SIMULATION set to an empty string, no simulation will be used to perform Type: String
the prediction. Access: Read/Write
Whether the average simulation will be used to perform the
Version  : 2.7.0
prediction. This property is not relevant when the
AVERAGESIMULATION Type: Boolean
SIMULATION property is empty. This property is not
Access: Read/Write
available for WiMAX and LTE predictions.
The minimum probability used to perform the prediction.
This property is only relevant when the SIMULATION Version  : 2.7.0
MINIMUMPROBABILITY property is not empty and when the AVERAGESIMULATION Type: Single
property is set to False. This property is not available for Access: Read/Write
WiMAX and LTE predictions.
Version  : 2.7.0
The carrier number used to perform the prediction. This
CARRIER Type: Integer
property is not available for WiMAX and LTE predictions.
Access: Read/Write
Whether downgrading will be considered to perform the Version  : 2.7.0

DOWNGRADINGALLOWED prediction, or not. This property is not available for WiMAX Type: Boolean
and LTE predictions. Access: Read/Write
The bearer used to perform the prediction. This property is Version  : 2.7.0

BEARER only relevant for a HSDPA Prediction. This property is not Type: Integer
available for WiMAX and LTE predictions. Access: Read/Write
11.4.5 Shadowing and Indoor Coverage Conditions
These properties are called CLUTTERCONDITIONS.
Name Attributes
Version  : 2.7.0
CLUTTERCONDITIONS
These properties are available for all kinds of coverage predictions:

Whether to calculate shadowing margins related to the
Version  : 2.7.0
defined cell edge coverage probability and the standard
SHADOWING Type: Boolean
deviation(s) per clutter class or not. When set to False, no
Access: Read/Write
shadowing effect is considered.
Whether to decrease the received signal level at the Version  : 2.7.0

INDOORCOVERAGE receiver of the indoor loss defined for the corresponding Type: Boolean
clutter class (clutter class properties) Access: Read/Write
Version  : 2.7.0
A value between 0 and 100, expressing in percentage value
EDGECOVERAGEPROBABILITY Type: Single
the required coverage probability at the cell edge.
Access: Read/Write
11.4.6 Display Properties
Display properties for coverage predictions are accessed through a property named "DISPLAYPROPERTIES." The "DISPLAY‐
PROPERTIES "property is a container object used to contain individual display properties.
140
Name Attributes
Version  : 2.7.0
DISPLAYPROPERTIES
The properties available in the "DISPLAYPROPERTIES" property container are, for all kinds of coverage predictions:
REPRESENTATION tabular data object
The "REPRESENTATION" tabular data object contains attributes of intervals or values used to display the prediction on the
map. This tabular data object can be edited to change, remove, or add display intervals or display values.
The "REPRESENTATION" tabular data object is available as a "DISPLAYPROPERTIES" property named "REPRESENTATION"
Name Attributes
Version  : 2.7.0
REPRESENTATION
Type: TabularData object
The schema of the "REPRESENTATION" tabular data object is:
Tabular Data Column Name Description Attributes
The style of the line used to display the interval or the value. Version  : 2.7.0

LINESTYLE The values are: 5=None; 0=Solid; 128=Solid Double Line; Type: Integer
1=Dash; 2=Dash Dot; 4=Dash Dot Dot; Access: Read/Write
The width of the line used to display the interval or the
Version  : 2.7.0
value, expressed in tenth of a point. For instance, to have a
LINEWIDTH Type: Integer
line width of 0,5 pt, the LINEWIDTH property value must be
Access: Read/Write
set to 5.
The graphical style used to fill the interior of the surface
Version  : 2.7.0
defined by the display interval or the display value. The
FILLSTYLE Type: Integer
values are: 0=None; 1=Full; 2=Horizontal; 3=Vertical;
Access: Read/Write
4=Down Diagonal; 5=Up Diagonal; 6=Grid; 7=Treillis;
The main color assigned to the display interval or the display
Version  : 2.7.0
value. The color format is RGB.
MAINCOLOR Type: Integer
See "Converting Integers to RGB and Vice‐versa" on
Access: Read/Write
page 142.
The secondary color assigned to the display interval or the
Version  : 2.7.0
display value. The color format is RGB.
SECONDARYCOLOR Type: Integer
Access: Read/Write
page 142.
Version  : 2.7.0
This property is not used to display a prediction interval or a
SYMBOL Type: Integer
prediction value.
Access: Read/Write
Version  : 2.7.0
This property is not used to display a prediction interval or a
SYMBOLSIZE Type: Integer
prediction value.
Access: Read/Write
The text assigned to the display value. When the display Version  : 2.7.0

VALUE type of the prediction is set to intervals, a Null value is Type: String or Null
returned. Access: Read/Write
The minimum value of the display interval. When the Version  : 2.7.0

MINVALUE display type of the prediction is set to display unique or Type: Double or Null
discrete values, a Null value is returned. Access: Read/Write
The maximum value of the display interval. When the Version  : 2.7.0

MAXVALUE display type of the prediction is set to display unique or Type: Double or Null
141
Converting Integers to RGB and Vice‐versa
To convert Integer to RGB color components:
Dim Red
Dim Green
Dim Blue
Let Red = (color And &HFF)
Let Green = ((color \ 256) And &HFF)
Let Blue = ((color \ 65536) And &HFF)
To convert RGB colour components to Integer:
Dim color
Let color = (Red + Green * 256 + Blue * 65536)
Other DISPLAYPROPERTIES properties
DISPLAYPROPERTIES
Description Attributes
Property Name
A value between 0 and 2 used to choose which value classes Version  : 2.7.0

TYPE to display on the map for the current prediction: 0=Unique; Type: Integer
1=Discrete Values; 2=Value Intervals; Access: Read/Write
The field title used to choose which coverage to display on Version  : 2.7.0

FIELD the map. The field title must be compatible with the display Type: String
type property. Access: Read/Write
Version  : 2.7.0
A value between 0 and 100 used to adjust the level of
TRANSPARENCY Type: Integer
transparency of the display interval or the display value.
Access: Read/Write
11.5 GSM Simulation Group Properties
The following properties are accessible for a GSM Monte Carlo simulation group.

Version  :3.2.1
The names of the traffic maps used by a simulation
TRAFFICMAPS Type: Array of Strings
group.
Access: Read/Write
Version  :3.2.1
NUMBEROFSIMULATIONS The number of simulations in a simulation group. Type: Integer
Access: Read/Write
Version  :3.2.1
When set to true, the group of simulations will be run as
EXECUTELATER Type: Boolean
part of the predictions calculation.
Access: Read
Version  :3.2.1
GLOBALSCALINGFACTOR Global traffic densities weighting. Type: Single
Access: Read/Write
142

Version  :3.2.1
The seed of the pseudo random number generator, used
GENERATORINITIALISATION Type: Integer
to obtain two identical user distributions.
Access: Read/Write
Version  :3.2.1
The maximum number of iterations if the convergence
MAXNUMBEROFITERATIONS Type: Integer
criteria cannot be reached.
Access: Read/Write
ULCONVERGENCETHRESHOLD Version  :3.2.1
(for Single‐RATdocuments)
The UL relative interference difference to reach between Type: Single
two iterative steps. Access: Read/Write
GSMULCONVERGENCETHRESHOLD
(for 3GPP Multi‐RAT documents)
DLCONVERGENCETHRESHOLD Version  :3.2.1
(for Single‐RAT documents)
The DL relative interference difference to reach between Type: Single
GSMDLCONVERGENCETHRESHOLD
(for 3GPP Multi‐RAT documents)
Version  :3.2.1
The UL noise rise relative interference to reach between
ULCONVERGENCEINTERFERENCES Type: Single
two iterative steps.
Access: Read/Write
Version  :3.2.1
The power control gain difference to reach DL between
DLCONVERGENCEPWRCTRLGAIN Type: Single
Access: Read/Write
11.6 UMTS Simulation Group Properties
Type returned by get_ObjectKind: {AF5E2B98‐1D54‐48FA‐89C5‐8BFA2936ABF2}
The following properties are accessible for a UMTS Monte Carlo simulation group.

Type: Array of Strings
TRAFFICMAPS The names of the traffic maps used by a simulation group.
Access: Read/Write
Version  : 2.7.1
Access: Read/Write
Version  : 2.7.1
Access: Read
The type of outputs needed in the "Mobiles" tab of each
simulation in the simulations group. Available values are: Version  : 2.7.1
INFORMATIONABOUTMOBILES 0=Only the Average Simulation And Statistics; 1=No Type: Integer
Information About Mobiles; 2=Standard Information About Access: Read/Write
Mobiles; 3=Detailed Information About Mobiles;
Version  : 2.7.1
BEARERRATEDOWNGRADING When set to true, R99 bearer downgrading is allowed. Type: Boolean
Access: Read/Write
Version  : 2.7.1
Access: Read/Write
Version  : 2.7.1
The seed of the pseudo random number generator, used to
obtain two identical user distributions.
Access: Read/Write
143
Version  : 2.7.1
Access: Read/Write
Version  : 2.7.1
The UL relative interference difference to reach between
ULCONVERGENCETHRESHOLD Type: Single
Access: Read/Write
Version  : 2.7.1
The DL relative interference difference to reach between
DLCONVERGENCETHRESHOLD Type: Single
Access: Read/Write
Version  : 2.7.1
When set to true, the maximum number of channel
CONSTRAINTNUMBEROFCES Type: Boolean
elements defined per site is respected.
Access: Read/Write
Version  : 2.7.1
CONSTRAINTNUMBEROFCODES When set to true, OVSF codes availibility is checked. Type: Boolean
Access: Read/Write
Version  : 2.7.1
CONSTRAINTULLOADFACTOR When set to true, the maximum UL load factor is respected. Type: Boolean
Access: Read/Write
Version  : 2.7.1
CONSTRAINTDLLOAD When set to true, the maximum DL load is respected. Type: Boolean
Access: Read/Write
Version  : 2.7.1
CONSTRAINTUSECELLMAXULLOADFA When set to true, the maximum UL load factor is defined
Type: Boolean
CTOR per cell.
Access: Read/Write
Version  : 2.7.1
CONSTRAINTUSECELLMAXDLLOAD When set to true, the maximum DL load is defined per cell. Type: Boolean
Access: Read/Write
Version  : 2.7.1
Global UL load factor to impose to cells.
MAXULOADFACTOR Type: Single
Valid values are comprised between 0 (0%) and 1(100%).
Access: Read/Write
Version  : 2.7.1
Global DL load to impose to cells.
MAXDLLOAD Type: Single
Valid values are comprised between 0 (0%) and 1(100%).
Access: Read/Write
Version  : 3.1.1
IUBTHROUGHPUTS Iub throughputs. Type: Boolean
Access: Read/Write
11.7 WiMAX and LTE Simulation Group Properties
Type returned by get_ObjectKind: {AF5E2B98‐1D54‐48FA‐89C5‐8BFA2936ABF2}
The following properties are accessible for a WiMAX or LTE Monte Carlo simulation group.
Version  : 2.8.1
TRAFFICMAPS The names of the traffic maps used by a simulation group. Type: Array of Strings
Access: Read/Write
Version  : 2.8.1
The names of the subscriber lists used by a simulations
SUBSCRIBERLISTS Type: Array of Strings
group.
Access: Read/Write
144
Version  : 2.8.1
Access: Read/Write
Version  : 2.8.1
Access: Read
Version  : 2.8.1
Access: Read/Write
Version  : 2.8.1
The seed of the pseudo random number generator, used to
obtain two identical user distributions.
Access: Read/Write
Version  : 2.8.1
Access: Read/Write
Version  : 2.8.1
The UL relative traffic load difference to reach between two
ULCONVERGENCETHRESHOLD Type: Single
iterative steps.
Access: Read/Write
Version  : 2.8.1
The DL relative traffic load difference to reach between two
DLCONVERGENCETHRESHOLD Type: Single
iterative steps.
Access: Read/Write
Version  : 2.8.1
ULNOISERISECONVERGENCETHRESH The UL noise rise relative interference to reach between
Type: Single
OLD two iterative steps.
Access: Read/Write
Version  : 2.8.1
CONSTRAINTUSECELLMAXULTRAFFIC When set to true, the maximum UL traffic load is defined
Type: Boolean
LOAD per cell.
Access: Read/Write
Version  : 2.8.1
CONSTRAINTUSECELLMAXDLTRAFFIC When set to true, the maximum DL traffic load is defined
Type: Boolean
LOAD per cell.
Access: Read/Write
Version  : 2.8.1
MAXULTRAFFICLOAD Global UL traffic load to impose to cells. Type: Single
Access: Read/Write
Version  : 2.8.1
MAXDLTRAFFICLOAD Global DL traffic load to impose to cells. Type: Single
Access: Read/Write
Version  : 3.2.1
Type: Boolean
BACKHAULCAPACITY Backhaul Capacity
Access: Read/Write
Version  : 3.2.1
Type: Boolean
NOISERISECONTROL Noise Rise Control
Access: Read/Write
11.8 3GPP Multi‐RAT Simulation Group Properties
The following properties are accessible for a 3GPP Multi‐RAT simulation group.
In a 3GPP Multi‐RAT document, you can access all the properties we have for all the technologies available in your document,
except ULCONVERGENCETHRESHOLD and DLCONVERGENCETHRESHOLD which are prefixed with the technology name.
145

For GSM technology: Version  :3.2.1
GSMULCONVERGENCETHRESHOLD The UL relative interference difference to reach between Type: Single
For GSM technology: Version  :3.2.1
GSMDLCONVERGENCETHRESHOLD The DL relative interference difference to reach between Type: Single

For UMTS technology: Version  :3.2.1
UMTSULCONVERGENCETHRESHOLD The UL relative interference difference to reach between Type: Single
For UMTS technology: Version  :3.2.1
UMTSDLCONVERGENCETHRESHOLD The DL relative interference difference to reach between Type: Single
For LTE technology: Version  :3.2.1

LTEULCONVERGENCETHRESHOLD The UL relative interference difference to reach between Type: Single
Access: Read/Write
For LTE technology: Version  :3.2.1
LTEDLCONVERGENCETHRESHOLD The DL relative interference difference to reach between Type: Single
11.9 Propagation Model Properties
The Type returned by get_ObjectKind for the Propagation Models folder: {4A2D160B‐7D11‐4D07‐92DF‐A3CF6B68D402}
get_ObjectKind is accessible for the Propagation Models folder for version  2.7.0.
The Type returned by get_ObjectKind for the Standard Propagation Model: Atoll.StdPropagModel.1
get_ObjectKind is accessible for the Standard Propagation Model for version  2.7.0.
The Standard Propagation Model properties are called MODELPROPERTIES.
Name Attributes
The property container holding the propagation model parameters
MODELPROPERTIES Version  : 2.7.0
The following MODELPROPERTIES are available for the Standard Propagation Model:
Version  : 2.7.0
EFFECTIVEANTENNAHEIGHTMETHO
Type: Integer
D
Access: Read/Write
Version  : 2.7.0
EFFECTIVEANTENNAHEIGHTDISTANC
Type: Double
EMIN
Access: Read/Write
146
Version  : 2.7.0
EFFECTIVEANTENNAHEIGHTDISTANC
Type: Single
EMAX
Access: Read/Write
Version  : 2.7.0
DIFFRACTIONMETHOD Type: Integer
Access: Read/Write
Loss for each clutter class defined in the Atoll document.
Version  : 2.7.0
When there are no clutter classes, the Null value is
CLUTTERLOSSES Type: Array of Single
returned, otherwise the size of the returned array is the
Access: Read/Write
number of clutter classes defined in the Atoll document.
Clearance for each clutter class defined in the Atoll
Version  : 2.7.0
document. When there are no clutter classes, the Null value
CLUTTERCLEARANCES Type: Array of Single
is returned, otherwise the size of the returned array is the
Access: Read/Write
number of clutter classes defined in the Atoll document.
Version  : 2.7.0
CLUTTERWEIGHTINGFUNCTION Type: Integer
Access: Read/Write
Version  : 2.7.0
CLUTTERMAXIMUMDISTANCE Type: Double
Access: Read/Write
Version  : 2.7.0
K1 Type: Array of Single
Access: Read/Write
Version  : 2.7.0
K2 Type: Array of Single
Access: Read/Write
Version  : 2.7.0
K3 Type: Double
Access: Read/Write
Version  : 2.7.0
K4 Type: Double
Access: Read/Write
Version  : 2.7.0
K5 Type: Double
Access: Read/Write
Version  : 2.7.0
K6 Type: Double
Access: Read/Write
Version  : 2.7.0
KCLUTTER Type: Double
Access: Read/Write
Version  : 2.7.0
NEARTRANSMITTERMAXIMUMDISTA
Type: Double
NCE
Access: Read/Write
Version  : 2.7.0
PROFILES Type: Integer
Access: Read/Write
Version  : 2.7.0
GRIDCALCULATION Type: Integer
Access: Read/Write
147
Version  : 2.7.0
CONSIDERCLUTTERHEIGHTSINDIFFR
Type: Integer
ACTION
Access: Read/Write
Version  : 2.7.0
HILLYTERRAINCORRECTION Type: Integer
Access: Read/Write
Height of the receiver for each clutter class defined in the
Version  : 2.7.0
Atoll document. When there are no clutter classes, the Null
CLUTTERRECEIVERHEIGHTS Type: Array of Single
value is returned, otherwise the size of the returned array is
Access: Read/Write
the number of clutter classes defined in the Atoll document.
Version  : 2.7.0
LIMITATIONTOFREESPACELOSS Type: Integer
Access: Read/Write
Version  : 2.7.0
RECEIVERONTOPOFCLUTTER Type: Integer
Access: Read/Write
11.10 CW Measurement Properties
The Type returned by get_ObjectKind for the CW Measurements folder: SID_CW_MEASUREMENTS
The following properties are accessible for the CW Measurements folder:

Advanced vector table filter, as it appears in CW Type: String
VECTORDATAFILTER
Measurements folders properties. Access: Read/Write
The Type returned by get_ObjectKind for a CW Measurements subfolder: MeasureTx
The following properties are accessible for a CW Measurements subfolder:

VECTORDATAFILTER
Measurements subfolder properties. Access: Read/Write
The Type returned by get_ObjectKind for a CW Measurements item: MeasureItem
The following properties are accessible for a CW Measurements item:

VECTORDATAFILTER
Measurements item properties. Access: Read/Write
Type: String
PREDICTIONMODEL Name of a propagation model.
Access: Read/Write
Type: String
HEADER
Access: Read/Write
Type: String
TRANSMITTERNAME Name of a transmitter.
Access: Read/Write
Type: Single
TRANSMITTERFREQUENCY
Access: Read/Write
Type: Single
RECEIVERHEIGHT
Access: Read/Write
148

Type: Single
RECEIVERGAIN
Access: Read/Write
Type: Single
RECEIVERLOSSES
Access: Read/Write
VECTORDATA Table content of the measurement path. Type: TabularData object
Version  : 3.1.1
TECHNOLOGYNAME Technology name : "UMTS", "LTE", or "GSM" Type: String
Access: Read/Write
11.11 Drive Test Data Properties
The Type returned by get_ObjectKind for a Drive Test Data item: NumMeasureItem
The following properties are accessible for a Drive Test Data item:

Type: String
HEADER
Access: Read/Write
Type: Single
RECEIVERHEIGHT
Access: Read/Write
Type: Single
RECEIVERGAIN
Access: Read/Write
Type: Single
RECEIVERLOSSES
Access: Read/Write
VECTORDATA Table content of the measurement path. Type: TabularData object
11.12 Custom ChildFolder Object Properties
The Type returned by get_ObjectKind for a custom ChildFolder object is the version dependent PROGID of the custom Child‐
Folder object.
get_ObjectKind is accessible for the custom ChildFolder objects for version  2.7.0.
The following properties are accessible for a custom ChildFolder object.

The property container holding the custom ChildFolder object
Version  : 2.7.0
properties.
Type: PropertyContainer
MODELPROPERTIES The MODELPROPERTIES PropertyContainer object will
object
contain properties exposed by the custom ChildFolder object
Access: Read/Write
.
Returns true when the custom ChildFolder object can be
Version  : 2.7.0
renamed.
CANRENAME Type: Boolean
When false is returned, the "Rename" context menu option
Access: Read/Write
for the ChildFolder object is unavailable.
Returns true when the custom ChildFolder object can be
Version  : 2.7.0
deleted.
CANDELETE Type: Boolean
When false is returned, the "Delete" context menu option for
Access: Read/Write
the ChildFolder object is unavailable.
Version  : 2.7.0
The global transparency between 0 and 100 associated with
the custom ChildFolder object.
Access: Read/Write
149
Version  : 3.2.1
The comment string associated with the custom ChildFolder
COMMENT Type: String
object.
Access: Read/Write
11.13 Master Link Properties
Master Link ChildFolder objects are located as top level items in either the Data tab or the Geo tab of the document explorer
window. They are used to specify links from one ChildFolder object to another ChildFolder object (the target ChildFolder
object), located in another Document object (the target Document object).
The Type returned by get_ObjectKind for Master Link ChildFolder objects is :
{16A53FB3-A961-4EEA-8C30-2387DBF1CC24}
The following properties are accessible for Master Link ChildFolder objects.

The target ChildFolder object. Type: Object, or Null
TARGET The Null value is returned when the target Document object value.
is not opened in the current session. Access: Read
The full path to the target document .ATL file. Type: String
TARGETDOCUMENTFULLNAME
An error is returned when the target file cannot be located. Access: Read
11.14 Link Properties
Link ChildFolder objects are children of Master Link ChildFolder objects.
The Type returned by get_ObjectKind for Link ChildFolder objects is :
{232BDB73-A68F-41A6-A954-75112D907BBF}
The following properties are accessible for Link ChildFolder objects.

The target ChildFolder object. Type: Object, or Null
TARGET The Null value is returned when the target Document object value.
is not opened in the current session. Access: Read
11.15 Vector Layer Properties
The following properties are accessible for Vector Layer ChildFolder objects.
Version  : 3.2.1
Type: TabularData
VECTORDATA The vector table of the vector layer.
object
Version  : 2.7.0
Type:
DISPLAYPROPERTIES The vector layer display properties. PropertyContainer
object
11.15.1 Display Properties
Display properties for vector layers are accessed through a property named "DISPLAYPROPERTIES." The "DISPLAYPROPERTIES
"property is a container object used to contain individual display properties.
150
The properties available in the "DISPLAYPROPERTIES" property container are, for all kinds of vector layers:
REPRESENTATION tabular data object
The "REPRESENTATION" tabular data object contains attributes of intervals or values used to display the vector layer on the
map. This tabular data object can be edited to change, remove, or add display intervals or display values.
The "REPRESENTATION" tabular data object is available as a "DISPLAYPROPERTIES" property named "REPRESENTATION"
DISPLAYPROPERTIES
Attributes
Property Name
Version  : 3.2.1
REPRESENTATION
Type: TabularData object
The schema of the "REPRESENTATION" tabular data object is:
Tabular Data Column Name Description Attributes
The style of the line used to display the interval or the value. Version  : 3.2.1

LINESTYLE The values are: 5=None; 0=Solid; 128=Solid Double Line; Type: Integer
1=Dash; 2=Dash Dot; 4=Dash Dot Dot; Access: Read/Write
The width of the line used to display the interval or the
Version  : 3.2.1
value, expressed in tenth of a point. For instance, to have a
LINEWIDTH Type: Integer
line width of 0,5 pt, the LINEWIDTH property value must be
Access: Read/Write
set to 5.
The graphical style used to fill the interior of the surface
Version  : 3.2.1
defined by the display interval or the display value. The
FILLSTYLE Type: Integer
values are: 0=None; 1=Full; 2=Horizontal; 3=Vertical;
Access: Read/Write
4=Down Diagonal; 5=Up Diagonal; 6=Grid; 7=Treillis;
The main color assigned to the display interval or the display
Version  : 3.2.1
value. The color format is RGB.
MAINCOLOR Type: Integer
Access: Read/Write
page 142.
The secondary color assigned to the display interval or the
Version  : 3.2.1
display value. The color format is RGB.
SECONDARYCOLOR Type: Integer
Access: Read/Write
page 142.
Version  : 3.2.1
This property is not used to display a vector layer interval or
SYMBOL Type: Integer
a vector layer value.
Access: Read/Write
Version  : 3.2.1
This property is not used to display a vector layer interval or
SYMBOLSIZE Type: Integer
a vector layer value.
Access: Read/Write
The text assigned to the display value. When the display Version  : 3.2.1

VALUE type of the vector layer is set to intervals, a Null value is Type: String or Null
returned. Access: Read/Write
The minimum value of the display interval. When the Version  : 3.2.1

MINVALUE display type of the vector layer is set to display unique or Type: Double or Null
The maximum value of the display interval. When the Version  : 3.2.1

MAXVALUE display type of the vector layer is set to display unique or Type: Double or Null
Converting Integers to RGB and Vice‐versa
To convert Integer to RGB color components:
151
Dim Red
Dim Green
Dim Blue
Let Red = (color And &HFF)
Let Green = ((color \ 256) And &HFF)
Let Blue = ((color \ 65536) And &HFF)
To convert RGB colour components to Integer:
Dim color
Let color = (Red + Green * 256 + Blue * 65536)
Other DISPLAYPROPERTIES properties
DISPLAYPROPERTIES
Description Attributes
Property Name
A value between 0 and 2 used to choose which value classes Version  : 3.2.1

TYPE to display on the map for the current vector layer: Type: Integer
0=Unique; 1=Discrete Values; 2=Value Intervals; Access: Read/Write
The field title used to choose which coverage to display on Version  : 3.2.1

FIELD the map. The field title must be compatible with the display Type: String
type property. Access: Read/Write
Version  : 3.2.1
A value between 0 and 100 used to adjust the level of
transparency of the display interval or the display value.
Access: Read/Write
11.16 User Density Traffic Map Properties
A user density traffic map is a particular type of traffic map available in Atoll. User density traffic maps are available in the
traffic maps folder of the document.
The Type returned by get_ObjectKind for the Traffic Maps folder is: {B3B25A07‐A994‐4E8d‐BBD1‐51556D6C4245}
The Type returned by get_ObjectKind for a User Density Traffic Map is: {2984F32F‐F737‐4250‐A6C0‐7439E249D039}
The following properties are available for User Density Traffic Maps:
Version  : 3.2.1
A Tabular Data Object used to access the traffic distribution Type: Tabular Data
DISTRIBUTIONPERSERVICE
per service, in percentage. Object
Access: Read only
Version  : 3.2.1
A Tabular Data Object used to access the traffic distribution Type: Tabular Data
DISTRIBUTIONPERTERMINAL
per terminal, in percentage. Object
Access: Read only
Version  : 3.2.1
A Tabular Data Object used to access the distribution per Type: Tabular Data
DISTRIBUTIONPERMOBILITY
mobility, in percentage. Object
Access: Read only
152
Version  : 3.2.1
A Tabular Data Object used to access the indoor traffic Type: Tabular Data
DISTRIBUTIONPERCLUTTERCLASS
distribution per clutter class, in percentage. Object
Access: Read only
An integer used to access the user density traffic map
activity status. Available values are:
0: Uplink Version  : 3.2.1
ACTIVITYSTATUS 1: Downlink Type: Integer
2: Uplink/Downlink Access: Read/Write
3: Inactive
4: All activity statuses
153
154
Chapter 12
ChildFolder Feature
Objects
156
AT321_TAG_E4 Chapter 12: ChildFolder Feature Objects
12 ChildFolder Feature Objects
Feature objects offer features closely tied to some Atoll document folders. The following ChildFolder Feature objects are avail‐
able through the Dispatch property of ChildFolder objects of Atoll document folders:
• "Clutter Feature Object" on page 157,
• "Traffic Feature Object" on page 160,
• "UMTS Traffic Scenario Provider Object" on page 163,
• "Environment Based Traffic Map Feature Object" on page 165,
• "Simulation Feature Object" on page 167,
• "Simulation Group Feature Object" on page 170.
12.1 Clutter Feature Object
The Clutter Feature object gives access to clutter classes properties. It is available for all Atoll documents. It is associated with
the Clutter Classes folder of an Atoll document.
The Clutter Feature object provides the following properties and methods:

get_Source Returns the Clutter Classes ChildFolder object.
get_ClassAttributes Returns a TabularData object holding the clutter class attributes.
Returns a TabularData object holding the clutter class default
get_DefaultAttributes
values.
12.1.1 How to Access the Clutter Feature Object
The ObjectKind property for the Clutter Classes folder is:
{7CB51DE8-A961-11D2-8688-0060086457D1}
Sample code to access the Clutter Feature object:
’ Returns the clutter feature object of the ’doc’ Atoll document object
Public Function ClutterFeatureObject(doc)
Const OBJECTKIND_CLUTTER = "{7CB51DE8-A961-11D2-8688-0060086457d1}"
Const atoGeo = 1
Dim oClutterClasses
Set oClutterClasses = doc.GetRootFolder(atoGeo).Item(OBJECTKIND_CLUTTER)
Set ClutterFeatureObject = oClutterClasses.Dispatch
End Function
12.1.2 get_Source
Returns the Clutter Classes ChildFolder object.
HRESULT get_Source(IDispatch **ppSource);
Parameters
[out] ppSource: Address of the IDispatch interface pointer used to return the Clutter Classes ChildFolder object.
157
Chapter 12: ChildFolder Feature Objects © Forsk 2014
12.1.3 get_ClassAttributes
Returns a TabularData object holding the clutter class attributes.
HRESULT get_ClassAttributes(ITabularData **ppTable);
Parameters
[out] ppTable: Address of the ITabularData interface pointer used to return the clutter class attributes. The content of the
TabularData object returned is the same as the content of the "Description" property page for the Clutter Classes folder of an
Atoll document, it is dependent on the type of the project template used by the Atoll document.
Remarks
The number of rows in the tabular data object returned depends on the state of the "Use only default values" checkbox.
When the "Use only default values" checkbox is checked, the number of rows returned is always 1, the tabular data object
returned is the same as the one returned by get_DefaultAttributes.
Version:  3.1.0
The schema of the tabular data object returned by get_ClassAttributes does not depend on the state of the "Use only default
value" checkbox. Whether the project is configured to use only default clutter class values or not, get_ClassAttributes returns
values used in calculations, in a consistent manner:
The number of rows or columns are the same in both cases.
Columns data types are the same in both cases.
To determine whether the "Use only default values" checkbox is checked or not, one can test the value returned by
get_CanEdit on the tabular data object returned by get _ClassAttributes. When using only default values, the tabular data
object returned is read‐only, and get_CanEdit output value is VARIANT_FALSE.
12.1.4 get_DefaultAttributes
Returns a TabularData object holding the clutter class default values.
HRESULT get_DefaultAttributes(ITabularData **ppTable);
Parameters
[out] ppTable: Address of the ITabularData interface pointer used to return the clutter class default values. The content of the
TabularData object returned is the same as the content of the "Default Values" property page for the Clutter Classes folder of
an Atoll document, it is dependent on the type of the project template used by the Atoll document.
12.1.5 Accessing Clutter Class Attributes
Sample macro to output the various clutter class attributes to the Atoll event viewer:
Private Function ClutterFeatureObject(doc)
Const OBJECTKIND_CLUTTER = "{7CB51DE8-A961-11D2-8688-0060086457d1}"
Const atoGeo = 1
Dim oClutterClasses
Set oClutterClasses = doc.GetRootFolder(atoGeo).Item(OBJECTKIND_CLUTTER)
Set ClutterFeatureObject = oClutterClasses.Dispatch
End Function
Private Sub DumpTable(t)
158
Dim c
Dim r
Dim values()
For r = 0 To t.RowCount
Redim values(t.ColumnCount)
For c = 0 To t.ColumnCount
values(c) = t.GetValue(r, c)
If IsNull(values(c)) Then
values(c) = "(Null)"
End If
If IsEmpty(values(c)) Then
values(c) = "(Empty)"
End If
If IsArray(values(c)) Then
values(c) = "(Array)"
End If
Next
LogMessage Join(values, ";")
Next
End Sub
Public Sub DumpClutterAttributes
Dim f
Set f = ClutterFeatureObject(ActiveDocument)
Dim classattrs
Dim defaultattrs
Set classattrs = f.ClassAttributes
LogMessage "Clutter Class Attributes..."
DumpTable(classattrs)
LogMessage "End Class Attributes."
Set defaultattrs = f.DefaultAttributes
LogMessage "Clutter Class Default Attributes..."
DumpTable(defaultattrs)
LogMessage "End Clutter Class Default Attributes."
159
End Sub
12.2 Traffic Feature Object
The Traffic Feature object gives access to features associated with the traffic folder, such as the export of the cumulated traf‐
fic. It is available for all Atoll documents except Microwave Links documents. It is associated with the Traffic folder of an Atoll
document.
The Traffic Feature object provides the following properties and methods:

get_Source Returns the Traffic ChildFolder object.
get_ScenarioProvider Creates a new Traffic Scenario Provider object instance.
ExportCumulatedTraffic Exports the cumulated traffic.
Determines if a traffic map contains traffic information for a given
HasTrafficForService
service.
12.2.1 How to Access the Traffic Feature Object
The ObjectKind property for the Traffic folder is:
{B3B25A07-A994-4E8D-BBD1-51556D6C4245}
Sample code to access the Traffic Feature Object:
' Returns the traffic feature object of the ’doc’ Atoll document object
Public Function TrafficFeatureObject(doc)
Const OBJECTKIND_TRAFFIC = "{B3B25A07-A994-4E8D-BBD1-51556D6C4245}"
Const atoGeo = 1
Dim oTraffic
Set oTraffic = doc.GetRootFolder(atoGeo).Item(OBJECTKIND_TRAFFIC)
Set TrafficFeatureObject = oTraffic.Dispatch
End Function
12.2.2 get_Source
Returns the Traffic ChildFolder object.
Parameters
[out] ppSource: Address of the IDispatch interface pointer used to return the Traffic ChildFolder object.
12.2.3 get_ScenarioProvider
Creates a new Traffic Scenario Provider object instance. See "UMTS Traffic Scenario Provider Object" on page 163 for more
information on the UMTS Traffic Scenario Provider object.
HRESULT get_ScenarioProvider(ITrafficScenarioProvider **ppProvider);
160
Parameters
[out] ppProvider: Address of the ITrafficScenarioProvider interface pointer used to return a new Traffic Scenario Provider
object instance.
Remarks
An error is returned when this method is called for an Atoll document not based on the UMTS HSPA template.
12.2.4 ExportCumulatedTraffic
Exports the cumulated traffic.
typedef enum _AtoRegion
atoEntireProjectArea = 0,
atoComputationZone = 1
} _AtoRegion;
typedef _AtoRegion AtoRegion;
typedef enum _AtoDirection
atoUplinkDownlink = 0,
atoUplink = 1,
atoDownlink = 2,
} _AtoDirection;
typedef _AtoDirection AtoDirection;
HRESULT ExportCumulatedTraffic(
BSTR bstrFileName,
enum _AtoRegion atoRegion,
BSTR bstrTerminal,
BSTR bstrMobility,
BSTR bstrService,
VARIANT vTrafficMaps,
long lResolution,
enum _AtoDirection atoDirection
);
Parameters
[in] bstrFileName:
A BSTR used to specify the absolute file path used to export the cumulated traffic. The BIL file format is used to export the
cumulated traffic.
[in] atoRegion:
161
An AtoRegion enumeration value used to specify the area used to export the cumulated traffic:
atoEntireProjectArea : The entire project area
atoComputationZone : The computation zone
[in] bstrTerminal:
A BSTR used to specify the terminal name used to export the cumulated traffic.
If "(ALL)" is specified, then all terminals are used to export the cumulated traffic.
[in] bstrMobility:
A BSTR used to specify the mobility name used to export the cumulated traffic.
If "(ALL)" is specified, then all mobilitiesare used to export the cumulated traffic.
[in] bstrService:
A BSTR used to specify the service name used to export the cumulated traffic.
If "(ALLCS)" is specified, then all circuit services are used to export the cumulated traffic.
If "(ALLPS)" is specified, then all packet services are used to export the cumulated traffic.
[in] vTrafficMaps:
A VARIANT used to specify the traffic maps used to export the cumulated traffic. The type of the VARIANT must be VT_ARRAY
| VT_VARIANT with VARIANTs of type VT_BSTR. The VARIANT array contains the names of the traffic maps.
[in] lResolution:
A long used to specify the resolution in meter used to export the cumulated traffic.
[in] atoDirection:
An AtoDirection enumeration value used to specify the kind of traffic used to export the cumulated traffic.
12.2.5 HasTrafficForService
Determines if a traffic map contains traffic information for a given service.
HRESULT HasTrafficForService(
BSTR bstrServiceName,
enum _AtoDirection atoDirection,
IChildFolder* pTrafficMap,
VARIANT_BOOL* pHasTraffic
);
Parameters
[in] bstrServiceName:
A BSTR used to specify the a service name.
[in] atoDirection:
An AtoDirection enumeration value used to specify the kind of traffic to look for:
atoUplinkDownlink (= 0) : Uplink and downlink traffic
atoUplink (= 1) : Uplink traffic
atoDownlink(=2) : Downlink traffic
[in] pTrafficMap:
A IChildFolder interface pointer used to specify the traffic map ChildFolder object. The traffic map is searched for traffic infor‐
mation related to the bstrServiceName service.
This parameter may be NULL. In this case, all traffic maps in the traffic map folder are searched.
162
[out] pHasTraffic:
A pointer to a VARIANT_BOOL value used to return whether the traffic map specified by pTrafficMap has some traf-
fic information for the service specified by bstrServiceName.
Remark
When HasTrafficForService returns VARIANT_FALSE, the traffic map is guaranteed not to contain traffic information for the
When HasTrafficForService returns VARIANT_TRUE, the traffic map still may not contain traffic information for the given
service.
12.3 UMTS Traffic Scenario Provider Object
The traffic scenario provider allows developing external UMTS simulation modules. Raw mobile data is generated by Atoll and
provided to the external UMTS simulator through this object.
The Traffic Scenario Provider object provides the following properties and methods:

GetMeanSize Returns the average count of mobiles.
Create Creates raw mobile data.
12.3.1 GetMeanSize
Returns the average count of mobiles.
HRESULT GetMeanSize(
const VARIANT aSelectedMapsNames,
double dScale,
const VARIANT aReserved,
ULONG *pMobilesCount
);
Parameters
[in] aSelectedMapsNames:
A VARIANT value used to specify the names of the traffic environment maps. The type of the VARIANT must be VT_ARRAY |
VT_UI1, it contains the names of the traffic environment maps, separated by the ASCII character code 0.
[in] dScale:
A double value used to specify the scaling factor used in the determination of the mobiles count.
[in] aReserved:
A VARIANT value reserved for future use. The VARIANT type must be VT_EMPTY.
[out] pMobilesCount:
Address of the ULONG integer used to return the average count of mobiles.
12.3.2 Create
Creates raw mobile data. The mobiles data is returned as a TabularData object containing the position of the mobiles and
other information related to the state of mobiles.
163
HRESULT Create(
const VARIANT aSelectedMapsNames,
double dScale,
enum AtoTrafficScenarioLaw aLaw,
const VARIANT aRreserved,
ITabularData **ppMobiles
);
Parameters
[in] aSelectedMapsNames:
A VARIANT value used to specify the names of the traffic maps. The type of the VARIANT must be VT_ARRAY | VT_UI1, it
contains the names of the traffic maps, separated by the ASCII character code 0.
[in] dScale:
A double value used to specify the scaling factor used in the determination of the mobiles count.
The scaling factor is relative to the average size of mobiles, as returned by GetMeanSize.
[in] aLaw: The AtoTrafficScenarioLaw enumeration value used to specify the law of probability used to get a random count of
mobiles.
[in] aReserved: A VARIANT value used to specify additional parameters.
Atoll version < 2.7.0:
The VARIANT type must be VT_EMPTY.
Atoll version >= 2.7.0:
When the VARIANT type is VT_DISPATCH, it is interpreted as a PropertyContainer object, implementing the
IPropertyContainer2 interface.
The property container object may contain the properties:
• Name: RANDOMSEED
• Type: VT_I4
• Description: An integer value used to specify the random seed of the pseudorandom number generator used to deter‐
mine the average count of mobiles, and the mobiles positions.
[out] ppMobiles:
Address of the ITabularData interface pointer used to return the position of the mobiles and other information related to the
state of mobiles. The tabular data schema is:
Column Name Value Type Description

X X coordinate Long Expressed in the document projection coordinate system
Y Y coordinate Long Expressed in the document projection coordinate system
SERVICE Service name String From the UMTSServices table
TERMINAL Terminal name String From the UMTSTerminals table
MOBILITY Mobility type String From the UMTSMobility table
CLUTTER Clutter code Short From the IClutter interface
ACTIVITY Mobile activity String "Active DL", "UL", "UL+DL"
164
12.4 Environment Based Traffic Map Feature Object
User profile environment based traffic map feature objects give access to user profile environment based traffic maps attrib‐
utes. They are available for all Atoll documents except Microwave Links documents. They are associated with user profile
environment base traffic maps contained in the Traffic folder of an Atoll document.
The User Profile Environment Based Traffic Map Feature object provides the following properties and methods:

Return the Traffic Map ChildFolder object associated with the
get_Source
Traffic Map per Environment Feature object.
Returns a TabularData object holding the traffic map environment
get_ClassAttributes
attributes.
get_DefaultAttributes Not implemented
12.4.1 How to Access Environment Based Traffic Map Feature
Objects
The ObjectKind property for User Profile Environment Based Traffic Maps is:
{E8784A75-AE03-4F4F-B923-6E8BF20725C5}
The User Profile Environment Based Traffic Map Feature object for a user profile environment based traffic map is returned
by the Dispatch property of the user profile environment based traffic map ChildFolder object.
12.4.2 get_Source
Return the User Profile Environment Base Traffic Map ChildFolder object associated with the User Profile Environment Based
Traffic Map Feature Object.
Parameters
[out] ppSource: Address of the IDispatch interface pointer used to return the User Profile Environment Based Traffic Map
ChildFolder Object.
12.4.3 get_ClassAttributes
Returns a TabularData object holding the user profile environment based traffic map attributes.
HRESULT get_ClassAttributes(ITabularData **ppTable);
Parameters
[out] ppTable: Address of the ITabularData interface pointer used to return the user profile environment based traffic map
attributes. The content of the TabularData object is the same as the one shown on the "Description" property page of user
profile environment based traffic maps property sheet.
12.4.4 get_DefaultAttributes
HRESULT get_DefaultAttributes(ITabularData **ppTable);
Remarks
This method is not implemented. Please don’t use this method.
165
12.4.5 Accessing Environment Based Traffic Maps Attributes
Private Function TrafficMapPerEnvironmentFeatureObjects(doc)
Const SID_TRAFFICFOLDER = "{B3B25A07-A994-4E8D-BBD1-51556D6C4245}"
Const OKIND_MAP_PER_ENVIRONMENT = "{E8784A75-AE03-4F4F-B923-6E8BF20725C5}"
Const atoGeo = 1
Dim maps()
Dim oTrafficFolder
Set oTrafficFolder = doc.GetRootFolder(atoGeo).Item(SID_TRAFFICFOLDER)
If Err Then
On Error Goto 0
Else
On Error Goto 0
Dim i
Dim n
n = 0
For i = 0 To oTrafficFolder.Count - 1
Dim map
Set map = oTrafficFolder.Item(i)
If map.ObjectKind = OKIND_MAP_PER_ENVIRONMENT Then
Redim Preserve maps(n)
Set maps(n) = map.Dispatch
n = n + 1
End If
Next
End If
TrafficMapPerEnvironmentFeatureObjects = maps
End Function
Dim c
Dim r
Dim values()
166
End If
End If
End If
Next
Next
End Sub
Public Sub DumpTrafficMapPerEnvironmentAttributes
Dim maps
maps = TrafficMapPerEnvironmentFeatureObjects(ActiveDocument)
Dim oFeature
For Each oFeature In maps
LogMessage "Traffic Map Per Environment [" & oFeature.Source.Name &

"]..."
Dim attrs
Set attrs = oFeature.ClassAttributes
DumpTable(attrs)
LogMessage "End Traffic Map Per Environment."
Next
End Sub
12.5 Simulation Feature Object
Simulation Feature objects give access to simulation results. They are associated with Simulation ChildFolder objects.
167
Simulation Feature objects are available in Atoll documents based on the templates:
• UMTS HSPA
• LTE
• CDMA 2000 1xRTT 1xEV‐DO
• WiMAX 802.16e
• TD‐SCDMA
•
•
The Simulation Feature object provides the following properties and methods:

get_Source Returns the associated Simulation ChildFolder object.
Returns a TabularData object holding the results as presented in
get_Statistics
the "Statistics" property page of the simulation property sheet.
get_Cells
the "Cells" property page of the simulation property sheet.
get_Sites
the "Sites" property page of the simulation property sheet.
get_Mobiles
the "Mobiles" property page of the simulation property sheet.
Returns a TabularData object holding the required results,
get_Results
depending on the parameter passed to this method.
12.5.1 How to Access Simulation Feature Objects
The ObjectKind property for the Simulation ChildFolder objects is:
{095C5D90-96F1-4BA8-85BB-B2F990AC2DD9}
Simulation ChildFolder objects are child of Simulation Groups ChildFolder objects.
Simulation Feature objects are available through the Dispatch property of Simulation ChildFolder objects:
Dim oSimulation
Dim oSimulationChildFolder
Set oSimulation = oSimulationChildFolder.Dispatch
12.5.2 get_Source
Returns the associated Simulation ChildFolder object.
Parameters
[out] ppSource: Address of the IDispatch interface pointer used to return the associated Simulation ChildFolder object.
Remarks
For a Simulation Feature object returned by a Simulation Group Feature object method, there is no associated ChildFolder
object, and the behaviour of this method is undefined.
12.5.3 get_Statistics
Returns a TabularData object holding the results as presented in the "Statistics" property page of the simulation property
sheet.
168
HRESULT get_Statistics(ITabularData **ppTable);
Remarks
12.5.4 get_Cells
Returns a TabularData object holding the results as presented in the "Cells" property page of the simulation property sheet.
HRESULT get_Cells(ITabularData **ppResults);
Parameters
[out] ppResults: Address of the ITabularData interface pointer used to return the "Cells" simulation results.
12.5.5 get_Sites
Returns a TabularData object holding the results as presented in the "Sites" property page of the simulation property sheet.
HRESULT get_Sites(ITabularData **ppResults);
Parameters
[out] ppResults: Address of the ITabularData interface pointer used to return the "Sites" simulation results.
12.5.6 get_Mobiles
Returns a TabularData object holding the results as presented in the "Mobiles" property page of the simulation property
sheet.
HRESULT get_Mobiles(ITabularData **ppResults);
Parameters
[out] ppResults: Address of the ITabularData interface pointer used to return the "Mobiles" simulation results.
Remarks
The content of the TabularData object returned depends on the "Information to retain" setting of the simulation. In particular,
when the information to retain is "No Information About Mobiles", the number of mobiles returned in the TabularData object
is 0.
All mobiles are returned, the focus zone is not taken into account.
12.5.7 get_Results
Returns a TabularData object holding the required results.
HRESULT get_Results(enum AtoSimulationResultsType aType, ITabularData **ppResults);
Parameters
[in] aType : An AtoSimulationResultsType enumeration value, used to specify the simulation results to return.
Enumeration values are:
169
atoSimulationResultsStatistics 0 Returns a TabularData object holding the results as presented in the
"Statistics" property page of the simulation property sheet.
atoSimulationResultsCells 1 Returns a TabularData object holding the results as presented in the
"Cells" property page of the simulation property sheet.
atoSimulationResultsSites 2 Returns a TabularData object holding the results as presented in the
"Sites" property page of the simulation property sheet.
atoSimulationResultsMobiles 3 Returns a TabularData object holding the results as presented in the
"Mobiles" property page of the simulation property sheet.
atoSimulationResultsGsmSubCells 100 Returns a TabularData object holding the results as presented in the
"SubCells" property page of the simulation property sheet.
atoSimulationResultsGsmTRXs 101 Returns a TabularData object holding the results as presented in the
"TRXs" property page of the GSM simulation property sheet.
[out] ppResults: Address of the ITabularData interface pointer used to return the simulation results.
12.6 Simulation Group Feature Object
Simulation Group Feature objects give access to group of simulations properties. An Atoll document can contain zero, one, or
more group of simulations. In turn, simulation groups can contain zero or more simulations. They are located in the "Simula‐
tions" folder of the Atoll document. Simulation Group Feature objects are associated with group of simulations ChildFolder
objects of an Atoll document.
Simulation Group Feature objects are available in Atoll documents based on the templates:
• UMTS HSPA
• LTE
• CDMA 2000 1xRTT 1xEV‐DO
• WiMAX 802.16e
• TD‐SCDMA
The Simulation Group Feature object provides the following properties and methods:

Returns the associated Simulation Group ChildFolder
get_Source
object.
Returns a TabularData object holding the statistics of the
get_Statistics
simulation group.
Returns a Simulation Feature object giving access to the
get_MeanSimulation
average simulation properties.
Returns a Simulation Feature object used to access the
get_StdDevSimulation
standard deviation simulation properties.
12.6.1 How to Access Simulation Group Feature Objects
The ObjectKind property for Group of Simulations folder is:
{AF5E2B98-1D54-48FA-89C5-8BFA2936ABF2}
Sample code to access Simulation Group Feature objects:
’ Returns ’True’ if there is at least one group of simulations in ’doc’,
’ ’False’ otherwise
’ Params:
’ [in] doc : Atoll document object
’ [out] array: Array of simulation group feature objects
170
Private Function SimulationGroupFeatureObjects(doc, ByRef array)
Const OBJECTKIND_SIMULATIONS = "{CDDF1E1D-1963-4D80-A057-D23A19570984}"
Const OBJECTKIND_SIMULATIONGROUP = "{AF5E2B98-1D54-48FA-89C5-

8BFA2936ABF2}"
Const atoData = 0
Dim oSimulations
’ oSimulations is the "Simulations" ChildFolder object
Set oSimulations = doc.GetRootFolder(atoData).Item(OBJECTKIND_SIMULATIONS)
If Err Then
’ There is no "Simulations" folder
On Error Goto 0
SimulationGroupFeatureObjects = False
Exit Function
End If
On Error Goto 0
If oSimulations.Count = 0 Then
Exit Function
End If
Redim array(oSimulations.Count - 1)
Dim oSimulationGroup
Dim n
n = 0
’ "Simulation Group" ChildFolder objects are located
’ in the "Simulations" folder
For Each oSimulationGroup In oSimulations
If oSimulationGroup.ObjectKind = OBJECTKIND_SIMULATIONGROUP Then
Set array(n) = oSimulationGroup.Dispatch
n = n + 1
End If
Next
SimulationGroupFeatureObjects = True
End Function
171
12.6.2 get_Source
Returns the associated Simulation Group ChildFolder object.
Parameters
[out] ppSource: Address of the IDispatch interface pointer used to return the associated Simulation Group ChildFolder object.
Returns a TabularData object holding the statistics of the simulation group.
HRESULT get_Statistics(ITabularData **ppTable);
Remarks
12.6.4 get_MeanSimulation
Returns a Simulation Feature object giving access to the average simulation properties.
HRESULT get_MeanSimulation(ISimulation **ppMeanValues);
Parameters
[out] ppMeanValues: Address of the ISimulation interface pointer used to return the Simulation Feature object corresponding
to the average simulation.
Remarks
The returned Simulation Feature object is not associated with a particular ChildFolder object in the Atoll document.
An error is returned when no simulation in the simulation group has converged. The average simulation is not available when
no simulation in the simulation group has converged.
An error is returned when the simulation group has not been calculated yet, for instance when the simulation group has been
created with the check box "Execute Later" set.
12.6.5 get_StdDevSimulation
Returns a Simulation Feature object used to access the standard deviation simulation properties.
HRESULT get_StdDevSimulation(ISimulation **ppStdDevValues);
[out] ppStdDevValues: Address of the ISimulation interface pointer used to return the Simulation Feature object correspond‐
ing to the standard deviation simulation.
Remarks
An error is returned when no simulation in the simulation group has converged. The standard deviation simulation is not avail‐
able when no simulation in the simulation group has converged.
An error is returned when the Atoll document is based on the LTE, WiMAX 802.16e templates. The standard deviation simu‐
lation is not available for LTE and WiMAX.
172
12.6.6 Accessing Mobiles, Cells, Sites, for Simulations and Simula‐
tion Groups
Here is a sample macro used to display the various available results for simulation groups and simulations in the Atoll event
viewer, for the active document:
’ Returns ’True’ if there is at least one group of simulation in ’doc’,
’ ’False’ ’ otherwise
' Params:
' [in] doc : Atoll document object
' [out] array: Array of simulation group feature objects
Private Function SimulationGroupFeatureObjects(doc, ByRef array)
Const OBJECTKIND_SIMULATIONS = "{CDDF1E1D-1963-4D80-A057-D23A19570984}"
Const OBJECTKIND_SIMULATIONGROUP = "{AF5E2B98-1D54-48FA-89C5-

8BFA2936ABF2}"
Const atoData = 0
Dim oSimulations
' oSimulations is the "Simulations" ChildFolder object
Set oSimulations = doc.GetRootFolder(atoData).Item(OBJECTKIND_SIMULATIONS)
If Err Then
' There is no "Simulations" folder
On Error Goto 0
Exit Function
End If
On Error Goto 0
If oSimulations.Count = 0 Then
Exit Function
End If
Redim array(oSimulations.Count - 1)
Dim n
n = 0
’ "Simulation Group" ChildFolder objects are located
173
’ in the "Simulations" folder
For Each oSimulationGroup In oSimulations
If oSimulationGroup.ObjectKind = OBJECTKIND_SIMULATIONGROUP Then
Set array(n) = oSimulationGroup.Dispatch
n = n + 1
End If
Next
SimulationGroupFeatureObjects = True
End Function
’ Returns 'True' if there is at least one simulation in 'oSimulationGroup',
’ ’False’ otherwise
’ Params:
’ [in] oSimulationGroup : Group of simulations ChildFolder object
’ [out] array: Array of simulation feature objects
Private Function SimulationFeatureObjects(oSimulationGroup, ByRef array)
If oSimulationGroup.Count = 0 Then
SimulationFeatureObjects = False
Exit Function
End If
Redim array(oSimulationGroup.Count - 1)
Dim oSimulation
Dim n
n = 0
For Each oSimulation In oSimulationGroup
Const OBJECTKIND_SIMULATION = "{095C5D90-96F1-4BA8-85BB-B2F990AC2DD9}"
If oSimulation.ObjectKind = OBJECTKIND_SIMULATION Then
Set array(n) = oSimulation.Dispatch
n = n + 1
End If
Next
SimulationFeatureObjects = True
End Function
174
Dim c
Dim r
Dim values()
End If
End If
End If
Next
Next
End Sub
Private Sub DumpSimulation(oSimulation, name)
LogMessage name
LogMessage "Cells..."
DumpTable(oSimulation.Cells)
LogMessage "End Cells."
LogMessage "Sites..."
DumpTable(oSimulation.Sites)
LogMessage "End Sites."
LogMessage "Mobiles..."
DumpTable(oSimulation.Mobiles)
LogMessage "End Mobiles."
LogMessage "End " & name & "."
End Sub
175
Public Sub DumpSimulationGroupAttributes
Dim f()
Dim arraySimulations()
If (SimulationGroupFeatureObjects(ActiveDocument, f) = False) Then
LogMessage "No Group of Simulations found in the document."
Exit Sub
End If
Dim oFeature
For Each oFeature In f
LogMessage "Group of Simulations [" & oFeature.Source.Name & "]..."
Dim average
Dim stddev
Set average = oFeature.MeanSimulation
If Err Then
’ The average simulation is not available when
’ no simulation has converged in the group.
LogMessage "The average simulation is not available."
On Error Goto 0
Else
On Error Goto 0
DumpSimulation average, "Average Simulation"
Set stddev = oFeature.StdDevSimulation
If Err Then
' The standard deviation simulation is not available
’ for LTE and WiMAX projects.
On Error Goto 0
Else
On Error Goto 0
DumpSimulation stddev, "Stddev Simulation"
End If
End If
176
' Dump all simulation in the group of simulations
Set oSimulationGroup = oFeature.Source
If (SimulationFeatureObjects(oSimulationGroup, arraySimulations) =
False) Then
LogMessage "There are no simulations in this group of simulations."
Else
Dim oSimulation
For Each oSimulation In arraySimulations
DumpSimulation oSimulation, oSimulation.Source.Name
Next
End If
LogMessage "End Group of Simulations."
Next
End Sub
12.7 3GPP Multi‐RAT Simulation Group Feature Object
Multi‐RAT Simulation Group Feature objects are available in Atolldocuments based on the templates:
• 3GPP Multi‐RAT
3GPP Multi‐RAT Simulation Group Feature objects are similar to Simulation Group Feature objects available in single‐RAT
documents, except some methods in 3GPP Multi‐RAT Simulation Group Feature objects require the name of the technology
to be specified.Multi‐RAT Simulation Group Feature objects provide the following properties and methods:

Returns the associated 3GPP Simulation Group ChildFolder
get_Source
object.
Returns a TabularData object holding the statistics of the
get_Statistics
simulation group for the specified technology.
Returns a Simulation Feature object giving access to the
get_MeanSimulation
average simulation properties for the specified technology.
Returns a Simulation Feature object used to access the
get_StdDevSimulation standard deviation simulation properties for the specified
technology.
12.7.1 get_Source
Returns the associated 3GPP Multi‐RAT Simulation Group ChildFolder object.
Parameters
[out] ppSource: Address of the IDispatch interface pointer used to return the associated 3GGP Multi‐RAT Simulation Group
ChildFolder object.
177
Returns a TabularData object holding the statistics of the simulation group for the specified technology.
HRESULT get_Statistics(const BSTR bstrTechno, ITabularData **ppTable);
Remarks
12.7.3 get_MeanSimulation
Returns a Simulation Feature object giving access to the average simulation properties for the specified technology.
HRESULT get_MeanSimulation(
const BSTR bstrTechno,
ISimulation **ppMeanValues
);
Parameters
[in] bstrTechno: A string used to specify the requested technology. Available values are "GSM”, “UMTS”, or “LTE”.
[out] ppMeanValues: Address of the ISimulation interface pointer used to return the Simulation Feature object corresponding
to the average simulation.
Remarks
An error is returned when no simulation in the simulation group has converged. The average simulation is not available when
no simulation in the simulation group has converged.
An error is returned when the simulation group has not been calculated yet, for instance when the 3GPP simulation group has
been created with the check box "Execute Later" set.
12.7.4 get_StdDevSimulation
Returns a Simulation Feature object used to access the standard deviation simulation properties for the specified technology.
HRESULT get_StdDevSimulation(
const BSTR bstrTechno,
ISimulation **ppStdDevValues
);
[in] bstrTechno: A string used to specify the requested technology. Available values are "GSM”, “UMTS”, or “LTE”.
[out] ppStdDevValues: Address of the ISimulation interface pointer used to return the Simulation Feature object correspond‐
ing to the standard deviation simulation.
Remarks
An error is returned when no simulation in the simulation group has converged. The standard deviation simulation is not avail‐
able when no simulation in the simulation group has converged.
An error is returned when the Atoll document is based on the LTE, WiMAX 802.16e templates. The standard deviation simu‐
lation is not available for LTE and WiMAX.
178
12.8 GSM Interference Matrix Feature Object
GSM Interference Matrix Feature objects give access to GSM interference matrices. A document can contain zero, one, or
more interference matrices. They are located in the "Interference matrices" folder of the document.
GSM Interference Matrix Feature objects are available in documents based on the GSM GPRS EDGE template.
GSM Interference Matrix Feature objects provide the following properties and methods:

Type: ChildFolder
get_Source Returns the "Interference Matrices" ChildFolder object. object
Access:Read
Load Loads an interference matrix.
CompleteScopeInfo Completes scope information.
Type: Tabular Data
get_Scope Returns the scope of the interference matrix. object
Access:Read
Type: Boolean
get_Active Returns the interference matrix active state.
Access:Read/Write
Type: Boolean
put_Active Sets the interference matrix active state.
Access:Read/Write
Type: Integer
get_Type Returns the type of the interference matrix.
Access:Read/Write
Type: Integer
put_Type Sets the type of the interference matrix.
Access:Read/Write
Type: Boolean
get_BasedOnTraffic
Access:Read/Write
Type: Boolean
put_BasedOnTraffic
Access:Read/Write
Returns the resolution of the interference matrix Type: Integer
get_Resolution
calculation. Access:Read/Write
Type: Integer
put_Resolution Sets the resolution of the interference matrix calculation.
Access:Read/Write
Type: Single
get_StdDev Returns the interference matrix standard deviation.
Access:Read/Write
Type: Single
put_StdDev Sets the interference matrix standard deviation.
Access:Read/Write
Returns the interference matrix information quantity Type: Integer
get_InfoQuantityIndicator
indicator. Access:Read/Write
Sets the interference matrix information quantity Type: Integer
put_InfoQuantityIndicator
indicator. Access:Read/Write
Type: Tabular Data
get_CdfTab Returns the interference matrix CDF tabular data. object
Access:Read
12.8.1 How to Access GSM Interference Matrix Feature Objects
The ObjectKind property for an Interference Matrix ChildFolder objects is:
{5144E1F9-E539-4F8C-BC0C-49A11C6389E8}
Interference Matrix ChildFolder objects are children of the folder named "Interference Matrices".
179
GSM Interference Matrix Feature objects are available through the Dispatch property of Interference Matrix ChildFolder
objects:
Dim oInterferenceMatrix
Dim oInterferenceMatricesChildFolder
Set oInterferenceMatricesChildFolder
= oDocument.GetRootFolder(atoData).Item("Interference Matrices")
Set oInterferenceMatrix = oInterferenceMatricesChildFolder.Dispatch
12.8.2 get_Source
Returns the "Interference Matrices" ChildFolder object.
Parameters
[out] ppSource: Address of the IDispatch interface pointer used to return the "Interference Matrices" ChildFolder object.
12.8.3 Load
Loads an interference matrix.
HRESULT Load();
Remarks
This method must be called before any access to an interference matrix.
12.8.4 CompleteScopeInfo
Completes scope information.
HRESULT CompleteScopeInfo();
Remarks
This method must be called after transmitters are added to the scope.
12.8.5 get_Scope
Returns the scope of the interference matrix.
HRESULT get_Scope(ITabularData **ppTable);
Parameters
[out] ppTable : The address of the ITabularData interface pointer used to return the scope of the interference matrix.
Remarks
The scope of an interference matrix is a Tabular Data object containing a mapping from the row identifier for a transmitter
to the following information:
The coverage percentage as victim, and as interferer. The default values are 100.
The BSIC and BCCH when the interference matrix information was collected. The default values are ‐1.
180
12.8.6 put_Active
Sets the active state.
HRESULT put_Active( VARIANT_BOOL isActiveVal);
Parameters
[in] isActiveVal : The VARIANT_BOOL value used to specify the active state of the interference matrix.
Remarks
An active interference matrix is used by the automatic frequency planning process when the interference matrix scope inter‐
sects the automatic frequency planning scope.
12.8.7 get_Active
Returns the active state.
HRESULT get_Active(VARIANT_BOOL *pIsActiveVal);
Parameters
[out] pIsActiveVal : Address of the VARIANT_BOOL used to return the active state of the interference matrix.
Remarks
An active interference matrix is used by the automatic frequency planning process when the interference matrix scope inter‐
sects the automatic frequency planning scope.
12.8.8 get_Type
Returrns the interference matrix type.
HRESULT get_Type(IM_TYPE *pImTypeVal);
Parameters
[out] pImTypeVal : Address of the enumeration value used to return the interference matrix type.
Remarks:
Available enumeration values used to specify an interference matrix type are:
1 : PROPAG_IM
For interference matrices based on propagation data. Their reliability depends on the accuracy and correctness of network
and geogrpahical data.
2 : OMC_RESELCTION_IM
For interference matrices based on reselection statistics from the OMC. Their reliability is usually low due to the difference
between the locations where mobiles are switched on and where they are actually used to access the network.
3 : OMC_SIMPLE_HO_IM
Their reliability is usually low due to the fact that interference is measured only among existing neighbours, which might not
be correctly assigned. This type of interference matrix is highly correlated with the neighbour relations. It can be used to
remove excessive neighbour constraints. However, it cannot be used to complete any missing neighbour information. Another
reason for low reliability is that interference information is collected from handover regions only, instead of from the service
area.
4 : OMC_NEI_EXT_HO_IM
Interference matrices based on RXLEV statistics from the OMC (neighbours, as well as temporary neighbours).
They can be a very good source of interference information if they are statistically stable because they are not sensitive to
data errors. On the other hand, they have many disadvantages, such as:
181
Transmitters with the same BSIC and BCCH cannot be differentiated.
Transmitters having the same BCCH will never have an interference entry.
Information is lost when more than 6 interferers exist at any location.
If many interferers share the same BCCH, they increase each other’s interference levels.
HCS layers can cause problems because there are more servers at any point, macro layer servers are stronger, or a correction
margin might be introduced for some equipment.
This type of interference matrix can be created using an extended neighbours list.
5 : TEST_MOBILE_DATA_IM
Interference matrices based on test mobile data.
Reliability can be low because usually the test mobile data sampling zone and the traffic model are not related. Secondly, the
measurements are carried out for existing neighbours only.
6 : CW_IM
Interference matrices based on CW measurements.
Their reliability can be low because the measurements usually do not reflect the traffic model. However, this source of infor‐
mation can be very reliable for a subset of transmitters that were properly scanned. Carrying out CW measurements is expen‐
sive which means that the collected information is often partial or out of date.
7 : SCAN_DATA_IM
Interference matrices based on scan data drive tests.
They are highly reliable and an excellent source of information, but are not useful in a radio planning tool because no infor‐
mation is available to map transmitters to the received signals at any pixel.
8 : UPPER_BOUND_ENTRY_COLLECTION
Upper bound interference matrix.
The source of this type of interference matrix is not defined. It can be based on user experience. The information contained
in this interference matrix is used as an upper limit, i.e., if this interference matrix indicates a certain level of interference, it
should not be exceeded because other interference matrices show higher interference. If an upper bound interference matrix
does not contain information about an entry, it is ignored.
9 : LOWER_BOUND_ENTRY_COLLECTION
Lower bound interference matrix.
The source of this type of interference matrix is not defined. It can be based on user experience. The information contained
in this interference matrix is used as a lower limit. This type of interference matrix can be very useful because you can edit
entries in this interference matrix, and be certain that the interference will be at least as high as the value you entered. This
approach can be used when user experience shows a certain level of interference which the radio network planning tool is
unable to calculate.
12.8.9 put_Type
Sets the interference matrix type.
HRESULT put_Type(IM_TYPE imTypeVal);
Parameters
[in] imTypeVal : The enumeration value used to specify the interference matrix type.
12.8.10 get_BasedOnTraffic
Returns based on traffic.
HRESULT get_BasedOnTraffic(VARIANT_BOOL *pbBasedOntraf) ;
Parameters
[out] pbBasedOntraf: The address of the VARIANT_BOOL value used to return based on traffic.
182
Remark
This method only makes sense for interference matrices of type PROPAG_IM. In that case, the return value indicates whether
the interference matrix takes into account non uniform traffic distributions within each cell.
12.8.11 put_BasedOnTraffic
Sets based on traffic.
HRESULT put_BasedOnTraffic(VARIANT_BOOL bBasedOntraf) ;
Parameters
[in] bBasedOntraf : The VARIANT_BOOL value used to specify based on traffic.
12.8.12 get_Resolution
Returns the resolution of the interference matrix calculation.
HRESULT get_Resolution(long *piResolutionParamVal);
Parameters
[out] piResolutionParamVal : The address of the long integer used to return the resolution of the interference matrix calcula‐
tion.
Remarks
For interference matrices of type PROPAG_IM, the return value is the resolution of the interference matrix calculation.
For interference matrices of type TEST_MOBILE_DATA_IM, CW_IM, or SCAN_DATA_IM, the return value is the number of
measurements per calculation point in the interference matrix.
12.8.13 put_Resolution
Sets the resolution of the interference matrix calculation.
HRESULT put_Resolution(long iResolutionParamVal) ;
Parameters
[in] :iResolutionParamVal : The long integer used to specify the resolution of the interference matrix calculation.
12.8.14 get_StdDev
Returns the interference matrix standard deviation.
HRESULT get_StdDev(float *pfStdDevParamVal);
Parameters
[out] pfStdDevParamVal: Address of the single precision floating point value used to return the interference matrix standard
deviation.
Remarks
For interference matrices of type PROPAG_IM, the return value is the standard deviation of the propagation model used in
the interference matrix calculation.
For interference matrices of type TEST_MOBILE_DATA_IM, CW_IM, or SCAN_DATA_IM, the return value is the standard devi‐
ation of the measurement equipment.
183
12.8.15 put_StdDev
Sets the interference matrix standard deviation.
HRESULT put_StdDev(float fStdDevParamVal);
Parameters
[in] fStdDevParamVal: The single precision floating point value used to specify the interference matrix standard deviation.
12.8.16 get_InfoQuantityIndicator
Returns the information quantity indicator.
HRESULT get_InfoQuantityIndicator(long *piInfoQuantIndic);
Parameters
[out] pilInfoQuantIndic: Address of the long integer used to return the information quantity indicator.
Remarks
For interference matrices of type PROPAG_IM, the return value is an information about the interference matrix calculation
parameters.
For interference matrices of type TEST_MOBILE_DATA_IM, CW_IM, or SCAN_DATA_IM, the return value is the number of
calculation points per victim.
For interference matrices of type OMC_RESELCTION_IM, OMC_SIMPLE_HO_IM, or OMC_NEI_EXT_HO_IM, the return value
is the number of days since the OMC statistics were collected.
12.8.17 put_InfoQuantityIndicator
Sets the information quantity indicator.
HRESULT put_InfoQuantityIndicator(long iInfoQuantIndic) ;
Parameters
[in] ilInfoQuantIndic : The long integer used to specify the information quantity indicator.
12.8.18 get_CdfTab
Returns the interference matrix CDF tabular data.
HRESULT get_CdfTab(ITabularData **ppTable) ;
Parameters
[out] ppTable : Address of the ITabularData interface pointer used to return the inteference matrix tabular data.
Remarks
The structure of the Tabular Data object returned is:
Column 1 : Row identifier of the victim transmitter
Column 2 : Row identifier of the interferer transmitter
Column 3 : A maximum loss value
Column 4 :
A safe array of type VT_ARRAY|VT_R4, VT_ARRAY|VT_R8, or VT_VARIANT having 1 dimension and containing the C/I values
of the CDF.
184
Column 5 :
A safe array of type VT_ARRAY|VT_R4, or VT_ARRAY|VT_R8, or VT_VARIANT having 1 dimension and containing the proba‐
bility values of the CDF.
Performance considerations:
When deleting elements, try to always delete the last element first.
When editing an existing element, do not change columns 1, 2, or 3.
185
186
Chapter 13
Document Commands
188
AT321_TAG_E4 Chapter 13: Document Commands
13 Document Commands
The Atoll API enables executing commands on Atoll documents.
Commands are invoked by their names, which must be known in advance.
The following commands are available for all Atoll documents:

This command performs the same task as the Atoll "File > Data
IMPORTXML Version:  2.7.1
Exchange > XML File Import..." main menu command.
This command performs the same task as the Atoll "File > Data
EXPORTXML Version:  2.7.0
Exchange > XML File Export..." main menu command.
This command adds a new column to a database table. This
APPENDTABLECOLUMN command is only available for Atoll documents that are not Version:  2.8.0
connected to databases.
The following commands are available for radio network technology documents:

This command returns signal levels in dBm for a given set of points
CALCULATEPOINTS Version:  2.6.0
and a set of transmitters.
This command imports a set of drive test data files into an Atoll
IMPORTTESTMOBILEDATA Version:  2.6.1
document.
RUNNEIGHBOURALLOCATI
Performs neighbour allocation on a GSM network. Version:  2.6.1
ON
RUNINTERTECHNOLOGYNE Performs inter technology neighbour allocation on a GSM or UMTS
Version:  2.6.1
IGHBOURALLOCATION network.
RUNINTRACARRIERNEIGHB
Performs intra carrier neighbour allocation on a UMTS network. Version:  2.6.1
OURALLOCATION
RUNINTERCARRIERNEIGHB
Performs inter carrier neighbour allocation on a UMTS network. Version:  2.6.1
OURALLOCATION
CLONESTUDY This command clones a coverage prediction. Version:  2.7.0
DUPLICATESTUDY This command duplicates a coverage prediction. Version:  2.7.0
COMPARESTUDY This command compares two coverage predictions. Version:  2.7.0
CALCULATEEQUIPMENTLO This command calculates equipment losses and noise figure for all
Version:  2.7.0
SSES transmitters in the document transmitters folder.
This command calculates propagation losses, azimuth, mechanical
CALCULATEREPEATERS Version:  2.7.0
tilt, or gains for all repeaters in the document transmitters folder.
This command calculates propagation losses, azimuth, mechanical
CALCULATEREMOTEANTEN
tilt, or gains for all remote antennas in the document transmitters Version:  2.7.0
NAS
folder.
EXPORTACTIVESETANALYSI
This command exports the active set analysis to text files. Version:  2.7.0
S
This command returns Ec/I0 values in dB for a given set of points and
CALCULATEPOINTSECI0 Version:  2.7.0
a set of transmitters.
RUNALLCARRIERSALLOCATI
Performs all carriers allocation on a TD‐SCDMA network. Version:  2.8.1
ON
RUNMASTERCARRIERALLO
Performs master carrier allocation on a TD‐SCDMA network. Version:  2.8.1
CATION
189
Chapter 13: Document Commands © Forsk 2014
MWRun This command runs analysis for a given set of links. Version:  2.6.1
EXPORTMAPWINDOW Exports a region of the map window as an image. Version:  3.1.0
IMPORTPLANETDATAFILE Imports a planet data file. Version:  3.1.0
ARCHIVETODATABASE Archives a document to the database. Version:  3.2.1
EXPORTMWLINKANALYSISP Exports a microwave link analysis profile picture to a Windows
Version:  3.1.0
ROFILEPICTURE bitmap file.
Input Parameters
Commands may have input parameters. The types and names of input parameters are unique and are specific to each
command. PropertyContainer objects are used to hold input parameters.
Results
Commands may return results. Results are specific to each command. The results of a command are returned using a Proper‐
tyContainer object. Each result has a unique name and an associated type.
13.1 How to Invoke a Document Command
The steps to invoke a command are the same for all commands.
Sample script invoking an Atoll document command:
Public Function ExecuteCommand(oDocument, strCommand, oParameters)
Set ExecuteCommand = oDocument.InvokeCommand(strCommand, oParameters)
End Function
oDocument is an Atoll Document Object. It can be the active document, or any document in the Documents collection.
strCommand is a string holding the Atoll command name.
oParameters is an Atoll PropertyContainer object used to hold the parameters specific to strCommandName. It can be a Prop‐
ertyContainer object holding the default parameters obtained with the GetCommandDefaults method available on the
IDocument4 interface.
The ExecuteCommand function returns the command results as a PropertyContainer object.
13.2 IMPORTXML
This command performs the same task as the Atoll "File > Data Exchange > XML File Import..." main menu command.
Version
 2.7.1
Input Parameters
The PATH input parameter is used to specify the source folder Version:  2.7.1

PATH
containing XML files to import. Type: String
Default Parameters
None. GetCommandDefaults on IDocument4 interface for the command IMPORTXML returns an empty PropertyContainer
object.
190
Results
None. The data in the Atoll document are updated with the content of XML files.
13.3 EXPORTXML
This command performs the same task as the Atoll "File > Data Exchange > XML File Export..." main menu command.
Version
 2.7.1
Input Parameters
The PATH input parameter is used to specify the destination folder Version:  2.7.1

PATH
where XML files will be exported. Type: String
Default Parameters
None. GetCommandDefaults for the command EXPORTXML returns an empty PropertyContainer object.
Results
None. The data in the Atoll document are exported to a set of XML files.
13.4 APPENDTABLECOLUMN
This command adds a new column to a database table. This command is only available for Atoll documents that are not
connected to databases.
Version
 2.8.0
Input Parameters
The TABLE input parameter is used to specify a table name. The new Version:  2.8.0

TABLE
column will be added to the table named TABLE. Type: String
The NAME input parameter is used to specify the database name of
Version:  2.8.0
NAME the new column to add to the TABLE table. The value is case
Type: String
insensitive and must not include spacesand dot characters.
The LEGEND input parameter is used to specify the display name of
Version:  2.8.0
LEGEND the new column to add to the TABLE table. The value is case sensitive
Type: String
and spaces characters are allowed.
The TYPE input parameter is used to specify the data type of the new
column to add to the table. Valid values are: 0=Text; 1=Short integer; Version:  2.8.0
TYPE
2=Long integer; 3=Single; 4=Double; 5=True/False; 6=Date/Time; Type: Integer
7=Currency;
The SIZE input parameter is used to specify the size, in bytes, for a
Version:  2.8.0
SIZE column of type 0 (Text). The SIZE input parameter is specific to the
Type: Integer
text data type.
191

The DEFAULT input parameter is used to specify the default value of
the new column. The default value is the column value for new rows, Version:  2.8.0
when the column value is not set explicitly. When the DEFAULT input Type: Null, String,
DEFAULT parameter is not specified, the default value for the new column is Integer, Boolean,
Null (VT_NULL). The type of the DEFAULT input parameter value Single, Double,
must match the data type of the new column, as specified by the Currency, or Date
TYPE input parameter.
The GROUP input parameter is used to specify the name of the group Version:  2.8.0

GROUP
the new column belongs to. Type: String
The CHOICELIST input parameter is used to specify the list of possible
values for a new column of type 0 (Text). The CHOICELIST input
parameter is specific to text columns. Please note that the actual Version:  2.8.0
CHOICELIST
column value is not restricted to the values defined in the choice list. Type: Array of Strings
The CHOICELIST parameter may be used by Atoll to display preferred
values to the user, for instance in a combobox control.
Default Parameters
The TABLE, NAME, LEGEND, and TYPE input parameters have no default values, they must be specified. Default values for
other input parameters are returned by GetCommandDefaultsfor the command APPENDTABLECOLUMN:
Input Parameter Name Default Value
LEGEND Empty.
SIZE 10 bytes.
DEFAULT Null
GROUP Empty.
CHOICELIST Empty.
Results
None. Upon successful completion the new column is added to the table.
13.5 CALCULATEPOINTS
This command returns signal levels in dBm for a given set of points and a set of transmitters.
Path loss matrices, whether they are valid or not, are not used. Therefore the CalculatePoints command is not dependent on
the path loss matrices resolution. Signal levels are calculated using the propagation model of each transmitter.
Version
 2.6.0
Input Parameters
Version:  2.6.1
POINTS The POINTS input parameter is used to define a set of points.
Type: Array of Integers
The TRANSMITTERS input parameter is used to define a set of Version:  2.6.1

TRANSMITTERS
transmitters. Type: Array of Strings
192

The TECHNOLOGY input parameter is used to specify the technology
of transmitters specified by the TRANSMITTERS input parameter.
Available values are:
"GSM" Version:  3.2.0
TECHNOLOGY "UMTS" Type: String
"LTE"
"CDMA2000"
This parameter is ignored for single‐RAT documents.
The POINTS array must have 2 dimensions, 0 and 1. The size of dimension 0 is the number of points. The size of dimension 1
is 2, index 0 and 1 for dimension 1 are the X and Y coordinates, respectively. The coordinates of points are expressed in the
projection coordinate system of the Atoll document.
The TRANSMITTERS array must have 1 dimension. The size of the array is the number of transmitters. Array values are trans‐
mitters IDs, as they appear in the TX_ID field of the Transmitters table
Default Parameters
None. GetCommandDefaults for the command CALCULATEPOINTS returns an empty PropertyContainer object.
Results
Version:  2.6.1
SIGNALS The SIGNALS result is used to return signals levels. Type: TabularData
object
The SIGNALS TabularData object has one record for each transmitter belonging to the TRANSMITTERS input parameter. The
row number n gives the signal received on the point number n. The SIGNALS TabularData object has the following structure:
Column Name Description Attributes

TX_ID A string holding a transmitter identifier. Type: String
The signal level received on point number n from the transmitter
identified by the field TX_ID.
Pn Type: Single or Null
When the signal level is less than ‐200 dBm, the type of the variant
returned for the field Pn is VT_NULL.
13.6 IMPORTTESTMOBILEDATA
This command imports a set of drive test data files into an Atoll document.
Version
 2.6.1
Input Parameters
Name of the Atoll Explorer item where the drive test data is Version:  2.6.1

NAME
imported. Type: String
Version:  2.6.1
RECEIVERHEIGHT Receiver height.
Type: Double
Version:  2.6.1
RECEIVERGAIN Receiver gain.
Type: Double
Version:  2.6.1
RECEIVERLOSSES Receiver losses.
Type: Double
193
Version:  2.6.1
MEASUREMENTUNIT Measurement unit. Valid values are: 0=dBm; 1=dBµV; 2=dBµV/m
Type: Integer
Code of the coordinate system used for measurement points in the
drive test data to import. Version:  2.6.1
MEASUREMENTCSCODE
The code for a coordinate system is reported in the Atoll properties Type: Integer
dialogue of the coordinate system.
Atoll configuration name, as reported in the Atoll drive test data
import dialogue.
Version:  2.6.1
CONFIGURATIONNAME Before importing drive test data, a drive test data configuration has
Type: String
to be defined in Atoll. CONFIGURATIONNAME is the name given to
the drive test data configuration.
The FILES input parameter is used to define the set of files to import. Version:  2.6.1

FILES
Each file must be specified using its absolute path. Type: Array of Strings
The CONFIGURATIONFILE input parameter is used to specify the full
Version:  3.2.0
path to the initialization file (.ini) containing the
CONFIGURATIONFILE
CONFIGURATIONNAME. This parameter is optional. When it is not
Type: String
specified the configuration file used is the one used in the project.
Default Parameters
None. GetCommandDefaults for the command IMPORTTESTMOBILEDATA returns an empty PropertyContainer object.
Results
None.
13.7 RUNNEIGHBOURALLOCATION
Performs neighbour allocation on a GSM network.
Version
 2.6.1
Input Parameters
Version:  2.6.1
A sub‐folder of the transmitters folder, or the transmitters folder
TRANSMITTERFOLDER Type: ChildFolder
itself.
object
Default Parameters
None. GetCommandDefaults for the command RUNNEIGHBOURALLOCATION returns an empty PropertyContainer object.
The neighbour allocation parameters used to compute neighbours are the ones set into the Atoll document. The neigbour
allocation parameters can be set by importing a user configuration file containing neighbour allocation parameters. Use the
Atoll Document object SetConfig method to import the neighbour allocation parameters.
Results
Version:  2.6.1
NEIGHBOURS The NEIGHBOURS result is used to return neighbour relations. Type: TabularData
object
The NEIGHBOURS TabularData object has one record for each neighbour relation between two transmitters belonging to

TRANSMITTERFOLDER.
194

Transmitter Type: String
Number Type: Integer
Maximum number Type: Integer
Neighbour Type: String
Importance (%) Type: Single
Cause Type: String
Coverage (%) Type: Single
Coverage (km²) Type: Single
13.8 RUNINTERTECHNOLOGYNEIGHBOURALLOCATION
Performs inter technology neighbour allocation.
Version
 2.6.1
Input Parameters
A sub‐folder of a transmitters folder, or a transmitters folder Version:  2.6.1

TRANSMITTERFOLDER
itself. Type: ChildFolder object
A string used to specify the technology of allocated
neighbours.
Available values are: Version:  3.1.0
NeighbourTechnologyName
"GSM", Type: String
"UMTS",
"LTE"
Default Parameters
None. GetCommandDefaults for the command RUNINTERTECHNOLOGYNEIGHBOURALLOCATION returns an empty Property‐
Container object. The neighbour allocation parameters used to calculate neighbours are the ones set in the Atoll document.
The neigbour allocation parameters can be set by importing a user configuration file containing neighbour allocation param‐
eters. Use the Atoll Document object SetConfig method to import the neighbour allocation parameters.
Results
Version:  2.6.1
object
TRANSMITTERFOLDER.

195

Cause Type: String
Distance (m) Type: Single
13.9 RUNINTRACARRIERNEIGHBOURALLOCATION
Performs intra carrier neighbour allocation on a UMTS network.
Version
 2.6.1
Input Parameters
Version:  2.6.1
itself.
object
Default Parameters
None. GetCommandDefaults for the command RUNINTRACARRIERNEIGHBOURALLOCATION returns an empty PropertyCon‐
tainer object. The neighbour allocation parameters used to calculate neighbours are the ones set in the Atoll document. The
neigbour allocation parameters can be set by importing a user configuration file containing neighbour allocation parameters.
Use the Atoll Document object SetConfig method to import the neighbour allocation parameters.
Results
Version:  2.6.1
object

TRANSMITTERFOLDER.

Cell Type: String
Cause Type: String
13.10 RUNINTERCARRIERNEIGHBOURALLOCATION
Performs inter carrier neighbour allocation on a UMTS network.
196
Version
 2.6.1
Input Parameters
Version:  2.6.1
itself.
object
Default Parameters
None. GetCommandDefaults for the command RUNINTERCARRIERNEIGHBOURALLOCATION returns an empty PropertyCon‐
tainer object. The neighbour allocation parameters used to compute neighbours are the ones set into the Atoll document.
The neigbour allocation parameters can be set by importing a user configuration file containing neighbour allocation param‐
eters. Use the Atoll Document object SetConfig method to import the neighbour allocation parameters.
Results
Version:  2.6.1
object
TRANSMITTERFOLDER.

Cell
Cell Type: String
Cause Type: String
13.11 CLONESTUDY
This command clones a coverage prediction.
Version
 2.7.0
Input Parameters
The STUDY input parameter holds the study to clone. The study to Version:  2.7.0

STUDY clone is a study object contained in the Predictions folder of the Atoll Type: ChildFolder
document. object
197
The NEWSTUDYNAME input parameter is used to define the name of Version:  2.7.0

NEWSTUDYNAME
the new cloned study. Type: String
Default Parameters
None. GetCommandDefaults for the command CLONESTUDY returns an empty PropertyContainer object.
Results
The NEWSTUDY result is used to return the new cloned Version:  2.7.0

NEWSTUDY
study object. Type: ChildFolder object
13.12 DUPLICATESTUDY
This command duplicates a coverage prediction.
Version
 2.7.0
Input Parameters
The STUDY input parameter holds the study to duplicate. The study Version:  2.7.0

STUDY to duplicate is a study object contained in the Predictions folder of Type: ChildFolder
the Atoll document. object

NEWSTUDYNAME
the new duplicated study. Type: String
The NEWSTUDYPARENT input parameter is used to specify a sub
folder of the Predictions folder. The new study will be created in the Version:  3.2.1
NEWSTUDYPARENT NEWSTUDYPARENT sub folder of the Predictions folder. Type: ChildFolder
This parameter is optional. If not specified the new study will be object
created at the root of the Predictions folder.
Default Parameters
None. GetCommandDefaults for the command DUPLICATESTUDY returns an empty PropertyContainer object.
Results
Version:  2.7.0
The NEWSTUDY result is used to return the new duplicated study
NEWSTUDY Type: ChildFolder
object.
object
13.13 COMPARESTUDY
This command compares two coverage predictions.
Version
 2.7.0
198
Input Parameters
The STUDY1 input parameter holds the first study involved in the Version:  2.7.0

STUDY1 comparison. It is a study object contained in the Predictions folder of Type: ChildFolder
The STUDY2 input parameter holds the second study involved in the Version:  2.7.0

STUDY2 comparison. It is a study object contained in the Predictions folder of Type: ChildFolder

NEWSTUDYNAME
the comparison study. Type: String
Default Parameters
None. GetCommandDefaults on IDocument4 interface for the command COMPARESTUDY returns an empty PropertyCon‐
tainer object.
Results
Version:  2.7.0
NEWSTUDY The NEWSTUDY result is used to return the comparison study object. Type: ChildFolder
object
13.14 CALCULATEEQUIPMENTLOSSES
This command calculates equipment losses and noise figure for all transmitters in a document transmitters folder.
Version
 2.7.0
Input Parameters
Version:  3.1.0
TRANSMITTERFOLDER A sub‐folder of a transmitters folder, or a transmitters folder itself. Type: ChildFolder
object
None.
Default Parameters
None. GetCommandDefaults for the command CALCULATEEQUIPMENTLOSSES returns an empty PropertyContainer object.
Results
None. The field "LOSSES" of the "TRANSMITTERS" table is updated for all transmitters in the document transmitters folder.
This command is the same as the "Equipment | Recalculate Losses" or the "Equipment | Recalculate Losses and Noise Figure"
menu option available in Atoll on the document transmitters folder.
13.15 CALCULATEREPEATERS
This command calculates propagation losses, azimuth, mechanical tilt, or gains for all repeaters in a document transmitters
folder.
Version
 2.7.0
199
Input Parameters
The PROPAGATIONLOSSES input parameter is used to specify Version:  2.7.0

PROPAGATIONLOSSES
whether repeaters donor side propagation losses will be calculated. Type: Boolean
The AZIMUTHSANDTILTS input parameter is used to specify whether Version:  2.7.0

AZIMUTHSANDTILTS
repeaters donor side azimuths and tilts will be calculated. Type: Boolean
The GAINS input parameter is used to specify whether repeaters Version:  2.7.0

GAINS
gains will be calculated. Type: Boolean
Version:  3.1.0
object
Default Parameters
GetCommandDefaults for the command CALCULATEREPEATERS returns a PropertyContainer object with the properties:

PROPAGATIONLOSSES Boolean True
AZIMUTHSANDTILTS Boolean True
GAINS Boolean True
Results
None. The "TRANSMITTERS" table content and the "REPEATERS" table content are updated depending on the requested
calculation.
If the PROPAGATIONLOSSES input parameter is set to True, then the calculation task "Repeaters | Calculate Donor Side Prop‐
agation Losses" on the document transmitters folder is performed.
If the AZIMUTHSANDTILTS input parameter is set to True, then the calculation task "Repeaters | Calculate Donor Side
Azimuths and Tilts" on the document transmitters folder is performed.
If the GAINS input parameter is set to True, then the calculation task "Repeaters | Calculate Gains" on the document trans‐
mitters folder is performed.
13.16 CALCULATEREMOTEANTENNAS
This command calculates propagation losses, azimuth, mechanical tilt, or gains for all remote antennas in a document trans‐
mitters folder.
Version
 2.7.0
Input Parameters

The PROPAGATIONLOSSES input parameter is used to specify
Version:  2.7.0
PROPAGATIONLOSSES whether remote antennas donor side propagation losses will be
Type: Boolean
calculated.
The AZIMUTHSANDTILTS input parameter is used to specify whether Version:  2.7.0

AZIMUTHSANDTILTS
remote antennas donor side azimuths and tilts will be calculated. Type: Boolean
The GAINS input parameter is used to specify whether remote Version:  2.7.0

GAINS
antennas gains will be calculated. Type: Boolean
200
Version:  3.1.0
object
Default Parameters
GetCommandDefaults for the command CALCULATEREMOTEANTENNAS returns a PropertyContainer object with the proper‐
ties:
Property Name Type Value

PROPAGATIONLOSSES Boolean True
AZIMUTHSANDTILTS Boolean True
GAINS Boolean True
Results
None. The "TRANSMITTERS" table content and the "REPEATERS" table content are updated depending on the requested
calculation.
If the PROPAGATIONLOSSES input parameter is set to True, then the calculation task "Remote Antennas | Calculate Donor
Side Propagation Losses" on the document transmitters folder is performed.
If the AZIMUTHSANDTILTS input parameter is set to True, then the calculation task "Remote Antennas | Calculate Donor Side
Azimuths and Tilts" on the document transmitters folder is performed.
If the GAINS input parameter is set to True, then the calculation task "Remote Antennas | Calculate Gains" on the document
transmitters folder is performed.
13.17 EXPORTACTIVESETANALYSIS
This command exports the active set analysis to text files.
Version
 2.7.1
Input Parameters
Input parameters include general parameters, simulation conditions (SIMULATIONCONDITIONS), shadowing and indoor
coverage conditions (CLUTTERCONDITIONS), and filtering parameters (RECORDSETCONDITIONS).

The SIMULATIONCONDITIONS PropertyContainer object used here
has a subset of the SIMULATIONCONDITIONS property of a "Pilot Version:  2.7.1
Quality Analysis (Ec/Io)" Prediction ChildFolder Object. Therefore the Type:
SIMULATIONCONDITIONS property of a "Pilot Quality Analysis (Ec/ PropertyContainer
Io)" Prediction ChildFolder Object can be used directly, additional object
content in this PropertyContainer object will be ignored.
Version:  2.7.1
Type:
CLUTTERCONDITIONS
PropertyContainer
object
The RECORDSETCONDITIONS PropertyContainer object used here
Version:  2.7.1
has a subset of the RECORDSETCONDITIONS property of a Prediction
Type:
RECORDSETCONDITIONS ChildFolder Object. Therefore the RECORDSETCONDITIONS property
PropertyContainer
of a Prediction ChildFolder Object can be used directly, additional
object
content in this PropertyContainer object will be ignored.
The general parameters include:
201
Version:  2.7.1
RESOLUTION The resolution in meter used to export the activeset analysis.
Type: Integer
The maximum number of cells in the activeset analysis to export on a Version:  2.7.1

DEPTH
given point. Type: Integer
The ASCII code of the character used as the field delimiter in the Version:  2.7.1

TEXTSEPARATOR
exported text files. Type: Integer
Version:  2.7.1
EXPORTFULLPATH The full path of the file where the activeset is exported.
Type: String
SIMULATIONCONDITIONS include:
Version:  2.7.1
TERMINAL The name of the terminal used to export the active set.
Type: String
Version:  2.7.1
MOBILITY The name of the mobility used to export the active set.
Type: String
Version:  2.7.1
SERVICE The name of the service used to export the active set.
Type: String
Version:  2.7.1
CARRIER The carrier number used to export the active set.
Type: Integer
CLUTTERCONDITIONS include:

Whether to calculate shadowing margins related to the defined cell
Version:  2.7.1
SHADOWING edge coverage probability and the standard deviation(s) per clutter
Type: Boolean
class or not. When set to False, no shadowing effect is considered.
Whether to decrease the received signal level at the receiver of the
Version:  2.7.1
INDOORCOVERAGE indoor loss defined for the corresponding clutter class (clutter class
Type: Boolean
properties).
EDGECOVERAGEPROBABILI A value between 0 and 100, expressing in percentage value the Version:  2.7.1

TY required coverage probability at the cell edge. Type: Single
RECORDSETCONDITIONS include:
"Filter" part of the recordset conditions, applied to the transmitters Version:  2.7.1

FILTER
table. Type: String
Default Parameters
Property Name Default Value
The same as the SIMULATIONCONDITIONS property of a new "Pilot
Quality Analysis (Ec/Io)" prediction.
The same as the RECORDSETCONDITIONS property of a new "Pilot
RECORDSETCONDITIONS
Quality Analysis (Ec/Io)" prediction.
The same as the RESOLUTION property of a new "Pilot Quality
RESOLUTION
Analysis (Ec/Io)" prediction.
3, ie by default the maximum number of cells of the activeset
DEPTH
analysis is 3.
202
Property Name Default Value
59, ie the ASCII code of the ’;’ character. Fields in the exported
TEXTSEPARATOR
fileswill be separated by the ’;’ character.
Results
None. The active set analysis is exported to the file specified by the EXPORTFULLPATH input parameter.
The area exported is the computation zone of the document.
When the area on wich the activeset analysis has to be exported is too large, the export is splitted into several text files. The
number and the size of these text files cannot be controlled. The text files are numbered starting from 0. For instance, when
the EXPORTFULLPATH input parameter is set to "c:\activeset.txt", the following files may be created:
c:\activeset‐0.txt
Text File Format
The text file in which the active set analysis is exported has a header, followed by the data. The data and the header are sepa‐
rated by a blank line.
• Header
The header is made of several [key;value] records. There is one [key;value] header record per line in the export file:
type;[Technology of the document used to export the activeset]
timestamp;[Date and time when the activeset has been exported]
resolution;[Resolution in meter used to export the activeset]
xmin;[Minimum X value of the rectangular area for which the activeset is exported]
xmax;[Maximum X value of the rectangular area for which the activeset is exported]
ymin;[Minimum Y value of the rectangular area for which the activeset is exported]
ymax;[Maximum Y value of the rectangular area for which the activeset is exported]
x_num_pixels;[Number of pixels of the export area along the X axis]
y_num_pixels;[Number of pixels of the export area along the Y axis]
• Data
The data format is made of one line per pixel. The line format for one pixel is:
X;Y;[Carrier;][Transmitter_1;Ec/I0;I0]...[Transmitter_n;Ec/I0;I0]
X: X coordinate of the pixel, in meter
Y: Y coordinate of the pixel, in meter
When the activeset is not empty, it is listed thereafter on the same line:
Carrier: Carrier of the activeset
There are at most n transmitters in the activeset analysis, where n is the DEPTH input parameter. Transmitter names
are listed along with the Ec/I0 and I0 value.
Transmitter_n : Name of the transmitter
Ec/I0: Ec/I0 in dB
I0: I0 in dB
Extract of an active set export file:
type;UMTS
timestamp;16:15:01 18-July-2008
resolution;50
xmin;23200
203
xmax;23700
ymin;-14250
ymax;-13650
x_num_pixels;10
y_num_pixels;12
[...]
23200;-14200;
23250;-14200;0;Site3_1;-10.06;-64.88;Site3_3;-12.62;-64.88;Site3_2;-13.56;-
64.88
23300;-14200;
23350;-14200;
[...]
13.18 CALCULATEPOINTSECI0
This command returns Ec/I0 values in dB for a given set of points and a set of transmitters.
Version
 2.7.1
Input Parameters
Version:  2.7.1
POINTS The POINTS input parameter is used to define a set of points.
Type: Array of Integers
The TRANSMITTERS input parameter is used to define a set of Version:  2.7.1

TRANSMITTERS
transmitters. Type: Array of Strings
The STUDY input parameter is used to define the parameters used to
Version:  2.7.1
calculate the Ec/I0 values. It is a study object contained in the
STUDY Type: ChildFolder
Predictions folder of the Atoll document. The STUDY input
object
parameter must be a study of type "Pilot Quality Analysis (Ec/I0)".
The POINTS array must have 2 dimensions, 0 and 1. The size of dimension 0 is the number of points. The size of dimension 1
is 2, index 0 and 1 for dimension 1 are the X and Y coordinates, respectively. The points coordinates are expressed in the
projection coordinate system of the Atoll document.
The TRANSMITTERS array must have 1 dimension. The size of the array is the number of transmitters. Array values are trans‐
mitters IDs, as they appear in the TX_ID field of the Transmitters table.
Default Parameters
None. GetCommandDefaults on the IDocument4 interface for the command CALCULATEPOINTSECI0 returns an empty Prop‐
ertyContainer object.
Results
Version:  2.7.1
VALUES The VALUES result is used to return Ec/I0 values. Type: TabularData
object
204
The VALUES tabular data object has one record for each transmitter belonging to the TRANSMITTERS input parameter. The
row number n gives the Ec/I0 value on the point number n.

TX_ID A string holding a transmitter identifier. Type: String
The Ec/I0 value on point number n from the transmitter identified by
Pn Type: Single or Null
the field TX_ID.
13.19 RUNALLCARRIERSALLOCATION
Performs all carriers allocation on a TD‐SCDMA network.
Version
 2.8.1
Input Parameters
Version:  2.8.1
itself.
object
CONFREQUENCYALLOCATI A boolean value used to specify whether to perform Co‐N frequency Version:  2.8.1

ON allocation (True) or Diff‐N frequency allocation (False). Type: Boolean
A boolean value used to specify whether the allocation results will be Version:  2.8.1

COMMITRESULTS
commited in the document (True), or not (False). Type: Boolean
Default Parameters
None. GetCommandDefaults for the command RUNALLCARRIERSALLOCATION returns an empty PropertyContainer object.
Results
Version:  2.8.1
CARRIERS The CARRIERS result is used to return carrier allocation information. Type: TabularData
object
The CARRIERS TabularData object has one record for each transmitter’s carrier allocation.

Carriers Type: Integer
Master Carrier Type: Integer
13.20 RUNMASTERCARRIERALLOCATION
Performs master carrier allocation on a TD‐SCDMA network.
Version
 2.8.1
205
Input Parameters
Version:  2.8.1
itself.
object
DELETEEXISTINGALLOCATI A boolean value used to specify whether to delete the existing Version:  2.8.1

ON allocation (True), or not (False). Type: Boolean
A boolean value used to specify whether the allocation results will be Version:  2.8.1

COMMITRESULTS
commited in the document (True), or not (False). Type: Boolean
Default Parameters
None. GetCommandDefaults for the command RUNMASTERCARRIERALLOCATION returns an empty PropertyContainer
object.
Results
The CARRIERS result is used to return carrier Version:  2.8.1

CARRIERS
allocation information. Type: TabularData object
The CARRIERS TabularData object has one record for each transmitter’s carrier allocation.

Master Carrier Type: Integer
13.21 MWRun
This command runs analysis for a given set of links. The analysis can take into account interferers.
The results are provided in a tabular data format. The fields are all the columns displayed when running link budgets or inter‐
ference calculation on a whole links folder.
Version
 2.6.1
Input Parameters
All the parameters that the user can provide as input through the GUI can be provided to this command.

Array containing the names of the links to be calculated. These
include the links which are filtered, active, and inside the focus zone. Version:  2.6.1
LINKS
This is the same list which is used by Atoll when running calculation Type: Array of Strings
on the Links folder.
Defines which propagation model is to be used for interference. If
Version:  2.6.1
INTERFERENCE true, recommendation ITU 452 is used. If false, the model defined in
Type: Boolean
the links properties is used.
Defines which quality model is to be used for analysis. Valid values
are: 0=ITU Recommendation 530‐5; 1=ITU Recommendation 530‐8; Version:  2.6.1
QUALITYMODEL
2=ITU Recommendation 530‐10; 3=Vigants Barnett method; 4=KQ Type: Integer
Factor method;
206

Defines the priority of objectives that Atoll must used to find the
QUALITYOBJECTIVE0 appropriate quality objective. "QualityObjective0" contains the
QUALITYOBJECTIVE1 objectives which are the higher‐priority objectives. Version:  2.6.1
QUALITYOBJECTIVE2 "QualityObjective3" contains the lowest‐priority objectives. Type: Integer
QUALITYOBJECTIVE3 Each "QualityObjectiveX" is set to an interger: 0="As a function of
Rate"; 1=ITU‐T G821; 2=ITU‐T G826; 3=Customized;
Defines the priority of objectives that Atoll must used to find the
AvailabilityObjective0 appropriate availability objective. "AvailabilityObjective0" contains
AvailabilityObjective1 the objectives which are the higher‐priority objectives. "Q Version:  2.6.1
AvailabilityObjective2 AvailabilityObjective 3" contains the lowest‐priority objectives. Type: Integer
AvailabilityObjective3 Each "AvailabilityObjectiveX" is set to an interger: 0="As a function of
Rate"; 1=ITU‐T G821; 2=ITU‐T G826; 3=Customized;
Defines which rain model is to be used for analysis: 0=ITU
Version:  2.6.1
RainModel Recommendation 530‐5; 1=ITU Recommendation 530‐8; 2=ITU
Type: Integer
Recommendation 530‐10; 3=Crane method;
Residual BER; used by Recommendation ITU 530‐8 and above to
Version:  2.6.1
RBER calculate performance parameters. Typically in the range from 10‐10
Type: Double
to 10‐13 for the bit rates of 2 to 155 Mbit/s, respectively.
Used by Recommendation ITU 530‐8 and above to calculate
performance parameters. Version:  2.6.1
ALFA1
10 to 30, number of errors per burst for the BER in the range from Type: Integer
10‐3 to BERSES
performance parameters. Version:  2.6.1
ALFA2
1 to 10, number of errors per burst for the BER in the range from Type: Integer
BERSES to RBER
prediction of outage in unprotected digital systems. Version:  2.6.1
RefDelayM
RefDelayM is the reference delay (ns) used to obtain the signature Type: Single
for minimum phase.
prediction of outage in unprotected digital systems. Version:  2.6.1
RefDelayNM
RefDelayNM is the reference delay (ns) used to obtain the signature Type: Single
for non‐minimum phase.
This percent is used to calculate the availability objective which will
Version:  2.6.1
EquipPercent be compared to the outage due to equipment failures.
Type: Single
Its value is supposed to be between 0 and 100.
This percent is used to calculate the availability objective which will
Version:  2.6.1
RainPercent be compared to the availability outage.
Type: Single
Its value is supposed to be between 0 and 100.
Version:  2.6.1
kMoy Defines the value of the average earth curvature used in calculation.
Type: Single
Defines the value of the second earth curvature used to display the
Version:  2.6.1
kMin ellipsoid. (not used during link budgets nor interferences
Type: Single
calculation).
Option which defines if power must be reduced or not with the ATPC Version:  2.6.1

UseAtpc
value. Type: Boolean
Defines which method must be used to calculate geoclimatic
Version:  2.6.1
Rec530Simple parameters (used for quality). For the simple one, Rec530Simple
Type: Boolean
must be set to True.
Boolean which tells if the calculation of fading due to XPD must be Version:  2.6.1

IgnoreXPD
taken into account or not in the total result. Type: Boolean
207
Boolean which tells if the calculation of fading due to enhancements Version:  2.6.1

IgnorePR
must be taken into account or not in the total result. Type: Boolean
Flag which defines if the calculation must be done for the BER
defined in the links properties (OneBER = 0/False) or if the Version:  2.6.1
OneBER
calculation must be done with the same BERs for all the links Type: Boolean
(OneBER = 1/True).
Version:  2.6.1
BER1 First value of BER which is used when OneBER = 1.
Type: Double
Second value of BER which is used when OneBER = 1.
Note that this value is not used when running calculations with this Version:  2.6.1
BER2
API. Using the API means that calculations are only displayed with Type: Double
BER1.
Defines which release of recommendation ITU‐838 must be used: Version:  2.6.1

Rec838
0=Rec 838‐1; 1=Rec 838‐3; Type: Double
Defines the expected results:
"all" means that all the ports of each link are calculated and
displayed in the final result. Version:  2.6.1
CALC_LINK_PORTS
"worst" means that the final result will display only the worst port. Type: String
"selected" means that the final result will display the result for the
port defined in the port parameter.
Defines the analysis is a link analysis without interferers (links
budgets, CALC_WITH_NOI = True) or if total interference must be
taken into account (CALC_WITH_NOI = False)
Version:  2.6.1
CALC_WITH_NOI Besides the interest of having results with or without interference,
Type: Boolean
the reader will see further in this document that calculation without
interference provides more detailed results on the link configuration
(sort of report of the link properties).
Defines the maximum distance (in meters) to search potential Version:  2.6.1

InterferenceDistanceMax
interferers. Type: Double
Defines the threshold of drop margin (in dB) under which an Version:  2.6.1

InterferenceDropMin
interference level is not added to the total result. Type: Double
Defines if the A>>B way must be calculated and displayed or not in
Version:  2.6.1
InterferenceCalcGo the final result. This option concerns not only interference
Type: Boolean
calculation but also links budgets.
Defines if the B>>A way must be calculated and displayed or not in
Version:  2.6.1
InterferenceCalcReturn the final result. This option concerns not only interference
Type: Boolean
calculation but also links budgets.
Defines if the uplink interference must be calculated and displayed Version:  2.6.1

InterferenceCalcUplink
or not in the final result. Type: Boolean
Defines if the downlink interference must be calculated and Version:  2.6.1

InterferenceCalcDownlink
displayed or not in the final result. Type: Boolean
InterferenceRainSurfCorrel Value of the area (km2) which is used to calculate the correlation Version:  2.6.1

ation between two links. Type: Single
Percent which defines if interferer level is more important or not
that interfering effects. This percent is only used for semi‐automatic Version:  2.6.1
InterferenceAutoWeight
channel allocation and has no influence when running calculation Type: Integer
with this API.
Option which defines if interferer power must be reduced or not Version:  2.6.1

InterferenceUseAtpc
with the ATPC value. Type: Boolean
Version:  2.6.1
InterferenceWidth Percent of the channels width which can interfere or be interfered.
Type: Integer
208

Flag which defines how passive repeaters are taken into account
when running interference: 0=interference through passive are not
Version:  2.6.1
InterferenceOverShoot taken into account; 1=links with passive repeaters may also interfere
Type: Integer
through their own passive; 2=any signal can interfere through a
repeater.;
Defines if results must contain details or not.
"none" means no detail
"uplink" means only for uplink results Version:  2.6.1
INTERF_DETAIL
"downlink" means only for downlink results Type: String
"both" means always.
This parameter has no effect when running calculation with this API.
When COCHANNELONLY is set to True, INTERFERENCEWIDTH is Version:  2.8.1

COCHANNELONLY
ignored. Type: Boolean
Default Parameters
The default values listed below are the default values set in Atoll. If these have been modified, the new default values will be
used instead.
Name Default Value
Links Array of links name
Interference False
QualityModel 1
QualityObjective0 0
QualityObjective1 1
QualityObjective2 2
QualityObjective3 3
AvailabilityObjective0 0
RainMod 1
RBER 1e‐12
ALFA1 10
ALFA2 1
RefDelayM 6.3
RefDelayNM 6.3
EquipPercent 33
RainPercent 33
kMoy 1.33
kMin NULL
UseAtpc False
Rec530Simple True
IgnoreXPD True
209
Name Default Value
IgnorePR False
OneBER 0
BER1 1e‐3
BER2 1e‐6
Rec838 0
CALC_LINK_PORTS "selected"
CALC_WITH_NOI True
InterferenceDistanceMax 50000
InterferenceDropMin 0.3
InterferenceCalcGo True
InterferenceCalcReturn True
InterferenceCalcUplink True
InterferenceCalcDownlink True
InterferenceRainSurfCorrelation 100
InterferenceAutoWeight 50
InterferenceUseAtpc False
InterferenceWidth 250
InterferenceOverShoot 0
INTERF_DETAIL "Both"
Analysis Results Without Interference Calculation

Version:  2.6.1
LINKNAME Name (primary key) of the link whose results are given.
Type: String
Version:  2.6.1
BAND Name (primary key) of the frequency band of the link.
Type: String
Length of the link calculated along the Great Circle (with latitude,
longitude and heights). Version:  2.6.1
LENGTH
This value is displayed as read‐only in the first page of links Type: Single
properties but is not saved in database.
Way of the link which is concerned with this result.
Version:  2.6.1
WAY "AB" means "go" (= Site A toward Site B)
Type: String
"BA" means "return" (= Site B toward Site A)
Name (primary key) of the subband of the link with the suffix "[‐]" or
"[+]" depending on the half subband of the link.
Version:  2.6.1
SUBBAND "[‐]" means lowest part
Type: String
"[+]" means highest part.
Can be null if the link has manual frequencies.
The calculated channel number. Version:  2.6.1

CHANNEL
If the link has manual frequency, channel number is "‐1". Type: String
String which contains either "H" for horizontal polarization, either
"V" for vertical polarization. Version:  2.6.1
POLAR
This value can be determined by the links properties (if no ports are Type: String
defined) or by the ports configuration if any.
210
Name (primary key) of the transmitting site of the link being Version:  2.6.1

SITE_TX
calculated (site A is the way is "AB", site B if the way if "BA"). Type: String
Name (primary key) of the transmitting antenna of the link. Version:  2.6.1

ANT_TX
(antenna A is the way is "AB", antenna B if the way if "BA"). Type: String
Version:  2.6.1
HEIGHT_TX Value of the height of transmitting antenna (in meters).
Type: Single
Value of the azimuth of the transmitting antenna. (in degrees). This
value is calculated, not displayed in the links properties, nor saved in Version:  2.6.1
AZIMUTH_TX
database. It takes into account the antenna misalignment and the Type: Single
direction of the receiver. (latitude, longitude and height).
Value of the tilt of the transmitting antenna. (in degrees). This value
is calculated, not displayed in the links properties, nor saved in Version:  2.6.1
TILT_TX
direction of the receiver. (latitude, longitude and height).
Value of the gain of the transmitting antenna (in dB). This value is Version:  2.6.1

ANTGAIN_TX
displayed in the antenna properties. Type: Single
Name (primary key) of the receiving site of the link being calculated Version:  2.6.1

SITE_RX
(site B is the way is "AB", site A if the way if "BA"). Type: String
Name (primary key) of the receiving antenna of the link. (antenna B Version:  2.6.1

ANT_RX
is the way is "AB", antenna A if the way if "BA"). Type: String
Version:  2.6.1
HEIGHT_RX Value of the height of receiving antenna (in meters).
Type: Single
Value of the azimuth of the receiving antenna. (in degrees). This
value is calculated, not displayed in the links properties, nor saved in Version:  2.6.1
AZIMUTH_RX
direction of the receiver. (Latitude, longitude and height).
Value of the tilt of the receiving antenna. (in degrees). This value is
calculated, not displayed in the links properties, nor saved in Version:  2.6.1
TILT_RX
direction of the receiver. (Latitude, longitude and height).
Value of the gain of the receiving antenna (in dB). This value is Version:  2.6.1

ANTGAIN_RX
displayed in the antenna properties. Type: Single
Name (primary key) of the transmitting equipment. (equipment A is Version:  2.6.1

EQ_TX
the way is "AB", equipment B if the way if "BA"). Type: String
Value of the nominal transmitted power, used if ATPC is not taken Version:  2.6.1

POWER_NOM
into account. Type: Single
Value of the coordinate transmitted power, used if ATPC is taken Version:  2.6.1

POWER_COORD
into account. Type: Single
Value the system configuration of the equipment. String formatted
as:
Version:  2.6.1
SYS_CFG "n+m" where n is an integer which corresponds to the main
Type: String
channels number, and "m" an interger which corresponds to the stad
by channels number. Ex: "1+1", "2+0" …
Value the capacity of the equipment. String is formatted with the
number of trunks (depending on the digital hierarchy) and the trunk
Version:  2.6.1
CAPA name.
Type: String
Example: "E1" or "3 x E1" or "2 x STM‐16" depending for if the
number of trunks is more than one or not.
211

Value of the total losses on the transmitter side: Shared losses,
Version:  2.6.1
TX_LOSS Connection losses, Shielding factor, port losses (filter + attenuation),
Type: Single
wave guide losses.
Value of the free space loss calculated between transmitter and Version:  2.6.1

FSL
receiver. Type: Single
Version:  2.6.1
LA Value of the attenuation due to dry air absorption.
Type: Single
Version:  2.6.1
LV Value of the attenuation due to vapor absorption.
Type: Single
Value of the total diffraction through the profile between the Version:  2.6.1

LD
transmitter and the receiver. Type: Single
Version:  2.6.1
LVEG Value of the vegetation loss along the profile.
Type: Single
Version:  2.6.1
LBS Value of the tropospheric loss along the profile.
Type: Single
Value of the total propagation loss along the profile. (Remember Version:  2.6.1

LTOT
that vegetation loss is never added). Type: Single
Name (primary key) of the receiving equipment. (equipment B is the Version:  2.6.1

EQ_RX
way is "AB", equipment A if the way if "BA"). Type: String
Value of the total losses on the receiver side: Shared losses,
Version:  2.6.1
RX_LOSS Connection losses, Shielding factor, port losses (filter + attenuation),
Type: Single
wave guide losses.
Value of the receiver threshold (dBm) defined as the sensitivity of Version:  2.6.1

RX_THRESOLD
the receiver for the BER1 value. Type: Single
Value of the total decoupling (dB) : losses due co‐polar patterns of
Version:  2.6.1
DECOUPLING the requested polarization for transmitter and receiver antenna.
Type: Single
(Generally null if antennas are aligned.)
Difference between the cross‐polar value of the receiver antenna Version:  2.6.1

XPD
and its co‐polar value (dB). Type: Single
Difference between the cross‐polar value of the transmitter antenna Version:  2.6.1

XPI
and its co‐polar value (dB). Type: Single
Wanted signal level (dBm) Takes into account the transmitted
Version:  2.6.1
RX_LEVEL power, transmitter and receiver losses, total propagation losses and
Type: Single
decoupling.
Calculated fade margin (uniform margin) which takes into account Version:  2.6.1

FADE_MARGIN
the received signal level et the receiver threshold. Type: String
Version:  2.6.1
PNS Percent of outage due to uniform fadings.
Type: Single
Version:  2.6.1
PS Percent of outage due to selective fadings.
Type: Single
Version:  2.6.1
pXPD Percent of outage due to cross‐polar discrimination fadings.
Type: Single
Percent of outage which determined the quality of the link (i.e Version:  2.6.1

PT
during clear air conditions). Type: Single
Version:  2.6.1
SESR Probability of SESR outage.
Type: Single
212
Version:  2.6.1
BBER Probability of BBER outage.
Type: Single
Version:  2.6.1
ESR Probability of ESR outage.
Type: Single
Version:  2.6.1
PR Percent of fadings due to enhancements.
Type: Single
Version:  2.6.1
P0 Percent of multipath occurrence.
Type: Single
Version:  2.6.1
PP Percent of fadings due to rain for the worst month.
Type: Single
Version:  2.6.1
PPA Percent of fadings due to rain for an average year.
Type: Single
Version:  2.6.1
PXPD Percent of rain fadings due to cross‐polar discrimination.
Type: Single
Version:  2.6.1
PPT Total percent of unavailability for an average year.
Type: Single
Version:  2.6.1
PFAILURES Percent of fadings due to equipment failures.
Type: Single
Version:  2.6.1
RAIN_SESR Probability of rain SESR outage.
Type: Single
Version:  2.6.1
RAIN_BBER Probability of rain BBER outage.
Type: Single
Version:  2.6.1
RAIN_ESR Probability of Rain ESR outage.
Type: Single
Version:  2.6.1
PASSIVE_GAIN Total gain (dB) of the passive repeaters.
Type: Single
Version:  2.6.1
AFF_RAIN Total rain attenuation (dB) along the path.
Type: Single
Total time of outage during clear‐air for the worst month. Value is Version:  2.6.1

SEC_M_Q
formatted is unit (hour, mn, sec). Ex: "6 sec", "19mn 27 sec". Type: String
Quality objective during clear‐air for the worst month. Value is Version:  2.6.1

OBJ_M_Q
formatted is unit (hour, mn, sec) Type: String
Total time of outage during clear‐air for an average year month. Version:  2.6.1

SEC_Y_Q
Value is formatted is unit (hour, mn, sec) Type: String
Total time of outage during rain condition for the worst month. Version:  2.6.1

SEC_M_RAIN
Value is formatted is unit (hour, mn, sec). Ex: "6 sec", "19mn 27 sec" Type: String
Quality objective during rain condition for the worst month. Value is Version:  2.6.1

OBJ_M_RAIN
Total time of outage during rain condition for an average year Version:  2.6.1

SEC_Y_RAIN
month. Value is formatted is unit (hour, mn, sec) Type: String
Status of the link for quality. Takes into account each probability and
corresponding objective for SESR, ESR and BBER, according to the
Version:  2.6.1
STATUS_Q equipment hierarchy too.
Type: String
The status can have following values: "OK"; "Not Respected"; "Not
Calculated"; "Not Defined";
213

Status of the link for avalability. Takes into account each probability
and corresponding objective for SESR, ESR and BBER, according to
Version:  2.6.1
STATUS_A the equipment hierarchy too.
Type: String
Value of the composite fade margin (dB) which takes into account all Version:  2.6.1

CFM
the margins; Corresponds to the SESR probability. Type: String
Value of the composite fade margin (dB) calculated from the quality Version:  2.6.1

REQ_CFM_Q
objectives set for the link. Type: String
Value of the uniform margin (dB) calculated from the quality
Version:  2.6.1
REQ_TFM objectives set for the link. Corresponds to the non‐selective outage
Type: String
probability.
Value of the composite fade margin (dB) calculated from the Version:  2.6.1

REQ_CFM_A
availability set for the link. Type: String
Version:  3.1.0
TX_PORT Transmission port. Type: String
Version:  3.1.0
RX_PORT Reception port. Type: String
Analysis Results With Interference Calculation
Version:  2.6.1
LINKNAME Name (primary key) of the link whose results are given.
Type: String
Way of the link which is concerned with this result.
Version:  2.6.1
WAY "AB" means "go" (= Site A toward Site B)
Type: String
"BA" means "return" (= Site B toward Site A)
Calculated interfered channel number. Version:  2.6.1

CHANNEL_IRX
If the link has manual frequency, channel number is "‐1". Type: String
Name (primary key) of the subband of the link with the suffixe "[‐]"
or "[+]" depending on the half subband of the link.
Version:  2.6.1
SUBBAND "[‐]" means lowest part
Type: String
"[+]" means highest part.
Can be null if the link has manual frequencies.
Wanted signal level (dBm) Takes into account the transmitted
power, transmitter and receiver losses, total propagation losses and Version:  2.6.1
C
decoupling. Same value as RX_LEVEL when running analysis without Type: Single
interference.
Value of the uniform margin (dB) calculated from the wanted signal Version:  2.6.1

FLAT_MARGIN
level and the receiver threshold. Type: Single
Aggregation of all the interferences (dBm) received from other links Version:  2.6.1

I
and receiver thermal noise (FKTB). Type: Single
Value of the differences between margin without interference and Version:  2.6.1

MARGIN_REDUCT
margin with interferences. Type: String
Value of C/I (dB) where C is the wanted signal level and I the total Version:  2.6.1

C_OVER_I
interference level. Type: Single
Value of the total interference level during rain condition which can
Version:  2.6.1
IRAIN be different from the "general" interference level depending on
Type: Single
correlation between links.
214
Value of the differences between margin without rain interference Version:  2.6.1

MARGIN_REDUCT_RAIN
and margin with interferences. Type: String
Value of the margin calculated from the receiver threshold and the Version:  2.6.1

EFF_MARGIN
received level when interference are taken into account. Type: Single
Version:  2.6.1
BER Value of the BER with which the current analysis is run.
Type: Single
Percent of outage which determined the quality of the link. (i.e Version:  2.6.1

QUALITY
during clear air conditions, and with interference). Type: Single
Percent of fadings due to rain for the worst month, when Version:  2.6.1

AVAIL
interference are taken into account. Type: Single
Total time of outage with interference during clear‐air for the worst
Version:  2.6.1
SEC_M_Q month. Value is formatted is unit (hour, mn, sec). Ex: "6 sec", "19mn
Type: String
27 sec"
Quality objective during clear‐air for the worst month. Value is Version:  2.6.1

OBJ_M_Q
Total time of outage with interference during clear‐air for an average Version:  2.6.1

SEC_Y_Q
year month. Value is formatted is unit (hour, mn, sec) Type: String
Total time of outage with interference during rain condition for the
Version:  2.6.1
SEC_M_RAIN worst month. Value is formatted is unit (hour, mn, sec). Ex: "6 sec",
Type: String
"19mn 27 sec"
Quality objective during rain condition for the worst month. Value is Version:  2.6.1

OBJ_M_RAIN
Total time of outage with interference during rain condition for an Version:  2.6.1

SEC_Y_RAIN
average year month. Value is formatted is unit (hour, mn, sec) Type: String
Status of the link for quality. Takes into account each probability and
corresponding objective for SESR, ESR and BBER, according to the
Version:  2.6.1
STATUS_Q equipment hierarchy too.
Type: String
Status of the link for avalability. Takes into account each probability
and corresponding objective for SESR, ESR and BBER, according to
Version:  2.6.1
STATUS_A the equipment hierarchy too.
Type: String
Version:  3.1.0
PORT_IRX Interferenced Port Type: Single
13.22 EXPORTMAPWINDOW
Exports a region of the map window as an image.
Version
 3.1.0
215
Input Parameters

The region to export. Available values are:
0: The region to export is specified by SELECTIONXMIN,
SELECTIONXMAX, SELECTIONYMIN, and SELECTIONYMAX input Version:  3.1.0
REGION
parameters. Type: Integer
1:The region to export is the geographic export zone.
2:The region to export is the printing zone.
The west coordinate of the region to export, expressed in meter in
Version:  3.1.0
SELECTIONXMIN the projection coordinate system of the document.
Type: Double
Only used when the REGION input parameter is set to 0.
The east coordinate of the region to export, expressed in meter in
Version:  3.1.0
SELECTIONXMAX the projection coordinate system of the document.
Type: Double
The south coordinate of the region to export, expressed in meter in
Version:  3.1.0
SELECTIONYMIN the projection coordinate system of the document.
Type: Double
The north coordinate of the region to export, expressed in meter in
Version:  3.1.0
SELECTIONYMAX the projection coordinate system of the document.
Type: Double
The absolute path of the file where the map window image is Version:  3.1.0

PATH
exported. Type: String
The file format used to export the map window image. Available
values are:
BMP : BMP file format
PNG : PNG file format Version:  3.1.0
FORMAT
ARCVIEWGRIDASCII : ArcView grid file format Type: String
TIF : TIFF file format
BIL : BIL file format
JP2 : JPEG 2000 file format
Pixel size (meters), used to export the map window image.
Version:  2.8.1
PIXELSIZE When the value specified is zero (0), then SCALE and RESOLUTION
Type: Integer
input parameters are used to determine the pixel size.
Scale of the map window used to export the map window image. Version:  3.1.0

SCALE
Only used when the PIXELSIZE input parameter is set to 0. Type: Integer
Resolution of the map window used to export the map window
Version:  3.1.0
RESOLUTION image, in dot per inch.
Type: Integer
Only used when the PIXELSIZE input parameter is set to 0.
Boolean value used to specify whether to include rulers in the
Version:  3.1.0
INCLUDERULERS exported image, or not.
Type: Boolean
Only used when the PIXELSIZE input parameter is set to 0.
Boolean value used to specify whether to include the scale in the Version:  3.2.1

INCLUDESCALE
exported image, or not. Type: Boolean
Default Parameters
None. GetCommandDefaults for the command EXPORTMAPWINDOW returns an empty PropertyContainer object.
Results
None. The map window image is exported to the file specified by the PATH input parameter.
13.23 IMPORTPLANETDATAFILE
Imports a planet data file.
216
Version
 3.1.0
Input Parameters
Version:  3.1.0
PATH The absolute path of the planet data file to import.
Type: String
Version:  3.1.0
EMBED Whether to embed data, or not.
Type: Boolean
The type of the planet data file to import.
Available values are:
0 : Digital terrain model
1: Digital height model
2 : Clutter classes
Version:  3.1.0
TYPE 3 : Environment based traffic map
Type: Integer
4: Planet vectors
5: Planet text data
6: Images
7: Antennas
8: Microwave antennas
Default Parameters
None. GetCommandDefaults for the command IMPORTPLANETDATAFILE returns an empty PropertyContainer object.
Results
None. The planet data is imported.
13.24 EXPORTMWLINKANALYSISPROFILEPICTURE
Exports a microwave link analysis profile picture to a Windows bitmap file.
Version
 3.1.0
Input Parameters
Version:  3.1.0
LINKNAME Name of the link.
Type: String
Link type. Available values are:
Version:  3.1.0
LINKTYPE 0 : A ‐> B
Type: Integer
1 : B ‐>A
Version:  3.1.0
PICTUREWIDTH Picture width, in pixels.
Type: Integer
Version:  3.1.0
PICTUREHEIGHT Picture height, in pixels.
Type: Integer
Version:  3.1.0
The absolute path of the Windows bitmap file where the link analysis
FILEPATH Type: String
picture is exported.
217
Default Parameters
None.GetCommandDefaults for the command EXPORTMWLINKANALYSISPROFILEPICTURE returns an empty PropertyCon‐

tainer object.
Results
None. The picture of the link profile is exported to the file specified by FILEPATH input parameter.
13.25 GETPOWERMODE
Retreives the document current power mode.
This command is only available for UMTS or LTE technologies.
Version
 3.1.0
Input Parameters

For single RAT documents, this parameter is not used. For multi‐RAT
parameter, a string used to specify the technology. Available values
Version:  3.1.0
TECHNOLOGY are:
Type: String
"UMTS",
"LTE"
Default Parameters
None. GetCommandDefaults for the command GETPOWERMODE returns an empty PropertyContainer object.
Results

The power mode. Available values are:
Version:  3.1.0
POWERMODE 0 : default
Type: Integer
1 : EIRP is calculated using the max power
13.26 SETPOWERMODE
Sets the document power mode.
This command is only available for UMTS or LTE technologies.
Version
 3.1.0
Input Parameters

For single RAT documents, this parameter is not used. For multi‐RAT
parameter, a string used to specify the technology. Available values
Version:  3.1.0
TECHNOLOGY are:
Type: String
"UMTS",
"LTE"
The power mode. Available values are: Version:  3.1.0

POWERMODE 0 : default Type: Integer
1 : EIRP is calculated using the max power
218
Default Parameters
None. GetCommandDefaults for the command SETPOWERMODE returns an empty PropertyContainer object.
Results
None. The document power mode is changed.
13.27 APPENDVECTORDATACOLUMN
This command adds a new column to a vector data table.
Version
 3.1.1
Input Parameters
The CHILDFOLDER input parameter is used to specify a vector data Version:  3.1.1

CHILDFOLDER table. The ChildFolder object specified must support the Type: ChildFolder
VECTORDATA property. object
The NAME input parameter is used to specify the name of the new
Version:  3.1.1
NAME column to add to the vector data table. The value is case insensitive
Type: String
and must not include spacesand dot characters.
The LEGEND input parameter is used to specify the display name of
Version:  3.1.1
LEGEND the new column to add to the vector data table. The value is case
Type: String
sensitive and space characters are allowed.
The TYPE input parameter is used to specify the data type of the new
column to add to the vector data table. Valid values are:
0=Text
1=Short integer
2=Long integer Version:  3.1.1
TYPE
3=Single Type: Integer
4=Double
5=True/False
6=Date/Time
7=Currency
The SIZE input parameter is used to specify the size, in bytes, for a
Version:  3.1.1
SIZE column of type 0 (Text).
Type: Integer
The SIZE input parameter is specific to the text data type.
The DEFAULT input parameter is used to specify the default value of
the new column. The default value is the column value for new rows, Version:  3.1.1
when the column value is not set explicitly. When the DEFAULT input Type: Null, String,
DEFAULT parameter is not specified, the default value for the new column is Integer, Boolean,
Null (VT_NULL). The type of the DEFAULT input parameter value Single, Double,
must match the data type of the new column, as specified by the Currency, or Date
TYPE input parameter.
The CHOICELIST input parameter is used to specify the list of possible
values for a new column of type 0 (Text).
The CHOICELIST input parameter is specific to text columns.
Version:  3.1.1
CHOICELIST Please note that the actual column value is not restricted to the
Type: Array of Strings
values defined in the choice list. The CHOICELIST parameter may be
used by Atoll to display preferred values to the user, for instance in a
combobox control.
Default Parameters
None.
219
Results
None. Upon successful completion the new column is added to the table.
13.28 LOADSAVEPRINTSETUP
This command loads or saves the print setup configuration.
Version
 3.1.1
Input Parameters

The DIRECTION input parameter is used to specify whether to load or
save the print setup configuration. Version:  3.1.1
DIRECTION
To load the print setup configuration, specify the value 1. Type: Integer
To save the print setup configuration, specify the value 0.
The PRINTERNAME input parameter is used to specify the default
printer to use in the print setup configuration. Version:  3.1.1
PRINTERNAME
This input parameter is not used when saving the print setup Type: String
configuration.
When loading the print setup configuration, the CFGPATH input
parameter is used to specify the file used to load the print setup
configuration. Version:  3.1.1
CFGPATH
When saving the print setup configuration, the CFGPATH input Type: String
parameter is used to specify the file used to save the print setup
configuration.
Default Parameters
None.
Results

The PRINTERNAME output
parameter is used to return the default printer used Version:  3.1.1
PRINTERNAME
int the print setup configuration file. Type: String
.
13.29 CALCULATEPATHLOSS
Performs pathloss matrix calculation on a transmitter folder.
Version
 3.2.0
Input Parameters
Version:  2.6.1
itself.
object
220

When True, the calculation is forced even for transmitters having
available valid results. When Version:  3.2.0
FORCECALCULATION
False, the calculation is made only for transmitters having Type: Boolean
unavailable or invalid results.
The boolean value used to specify whether the calculations will
occur in the background Version:  3.2.0
BLOCKING
(False), or if the method should wait for the calculations to finish Type: Boolean
before returning (True).
When False, the calculation is made for all active transmitters in the
Version:  3.2.0
FILTERED transmitter folder. When True, only
Type: Boolean
filtered transmitters are calculated
Default Parameters
None. GetCommandDefaults for the command CALCULATEPATHLOSS returns an empty PropertyContainer object.
13.30 MWLinksCustomExport
Performs microwave links custom export.
Version
 3.2.0
Input Parameters
Version:  2.6.1
EXPORTPATH Full path to the folder where link reports are exported.
Type: String
Version:  3.2.0
TEMPLATEFILEPATH Full path to the custom template used to perform the export.
Type: String
The microwave links folder containing links to export to the Version:  3.2.0

LINKSFOLDER EXPORTPATH folder, using the TEMPLATEFILEPATH custom Type: ChildFolder
template. object
Default Parameters
None. GetCommandDefaults for the command MWLinksCustomExport returns an empty PropertyContainer object.
13.31 ARCHIVETODATABASE
Archives a project to the database.
Version
 3.2.1
Input Parameters

A boolean used to specify whether to ignore all conflicts when Version:  3.2.1
IGNOREALLCONFLICTS
archiving. Type: Boolean
Default Parameters
None. GetCommandDefaults for the command ARCHIVETODATABASE returns an empty PropertyContainer object.
221
Results

The archive operation status.
Available values are: Version:  3.2.1
ARCHIVESTATUS 0: The archive operation has succeeded. Type: Integer
1: The archive operation has been interrupted
because of conflicts.
222
Chapter 14
1
Enumerations,
Structures, and
Interfaces
1.
224
AT321_TAG_E4 Chapter 14: Enumerations, Structures, and Interfaces
14 Enumerations, Structures, and Interfaces
14.1 Enumerations
Enumerations are used to specify constants. Two categories of enumerations are defined hereafter.
• The first category refers to all enumerations defined in the Atoll type library. All of them are prefixed with Ato.
• The second category refers to all enumerations defined in FSKGISLib library. All of them are prefixed with fg.
14.1.1 Atoll Type Library Enumerations
14.1.1.1 AtoSaveStatus
atoSaveSucceeded 0 Document has been successfully saved.
atoSaveCanceled 1 Changes in the document has been cancelled by the user.
14.1.1.2 AtoSaveChanges
atoSaveNo 0 Document is closed without being saved.
atoSaveYes 1 Document is saved before being closed.
The user is prompted whether the document must be saved before
atoSavePrompt 2
closed.
14.1.1.3 AtoRefreshPriority
All changes are cancelled before the document is refreshed from the
atoCancelChanges 0
database.
atoSkipChanges 1 Only refreshes data that have not been modified.
14.1.1.4 AtoArchiveStatus
atoArchiveSaveSucceeded 0 Archiving has succeeded without conflicts.
Archiving has been cancelled, either by the user or because conflicts
atoArchiveCanceled 1
occurred.
14.1.1.5 AtoWindowStatus
atoMaximized 0 Maximized (enlarged to maximum size).
atoNormal 1 Normal (Default).
atoMinimized 2 Minimized (minimized to an icon in the task bar).
225
Chapter 14: Enumerations, Structures, and Interfaces © Forsk 2014
14.1.1.6 AtoLogType
atoInfo 0 Information.
atoError 1 Error.
atoWarning 2 Warning.
14.1.1.7 AtoCompareOp
atoEQ 0 (Equal) The first value equal to searchVal is searched for.
(Strictly Lower Than) The first value less than searchVal is searched
atoLT 1
for.
(Lower or Equal) The first value less than or equal to searchVal is
atoLE 2
searched for.
(Greater or Equal) The first value greater than or equal to searchVal
atoGE 3
is searched for.
(Strictly Greater Than) The first value greater than searchVal is
atoGT 4
searched for.
atoNE 5 (Not Equal) The first value not equal to searchVal is searched for.
14.1.1.8 AtoTransmissionUnit
atoDbm 0 Transmission unit is dBm.
atoWatt 1 Transmission unit is Watt.
atoKWatt 2 Transmission unit is kWatt.
14.1.1.9 AtoReceptionUnit
atoDbmRx 0 Reception unit is dBm.
atoDbMicroVolt 1 Reception unit is dBV.
atoDbMicroVoltMeter 2 Reception unit is dBV/meter.
14.1.1.10 AtoDistanceUnit
atoM 0 Distance unit is meter.
atoKm 1 Distance unit is kilometer.
atoMiles 2 Distance unit is miles.
226
14.1.1.11 AtoRadiatedPowerUnit
atoRadiatedPowerEIRP 0 Radiated power is EIRP.
atoRadiatedPowerERP 1 Radiated power is ERP.
14.1.1.12 AtoAntennaGainUnit
atoAntennaGainDbi 0 Antenna gain unit is dBi.
atoAntennaGainDbd 1 Antenna gain unit is dBd.
14.1.1.13 AtoHeightOffsetUnit
atoHeightOffsetM 0 Height offset unit is meter.
atoHeightOffsetFeet 1 Height offset unit is feet.
14.1.1.14 AtoRootType
atoData 0 Atoll explorer window data tab.
atoGeo 1 Atoll explorer window geo tab.
atoModule 2 Atoll explorer window modules tab.
atoParameters 2 Atoll explorer window parameters tab.
14.1.1.15 AtoRowFilter
Constants to filter only modified, added, or deleted rows.

atoRowFilterNone 0 No filter.
atoRowFilterModifiedOrNew 1 Filter to retain only modified or new rows.
atoRowFilterDeleted 2 Filter to retain only deleted rows.
14.1.1.16 AtoRowStatus
All possible row statuses.

atoRowStatusNew 1 Row has been added.
atoRowStatusModified 2 Row has been modified.
atoRowStatusDeleted 4 Row has been deleted.
atoRowStatusUnmodified 8 Row is unmodified.
227
14.1.1.17 AtoTemperatureUnit
atoTempCelcius 0 Temperature unit is degree Celsius (°C).
atoTempFarenheit 1 Temperature unit is degree Farenheit (°F).
14.1.2 FSKGISLib Type Library Enumerations
14.1.2.1 GeographicUnit
fgUnspecifiedUnit ‐1 Value when nothing has been defined.
fgMeter 0 Length unit is meter.
fgKilometer 1 Length unit is kilometre.
fgFoot 2 Length unit is foot.
fgLink 3
fgChain 4
fgYard 5 Length unit is yard.
fgNauticalMile 6 Length unit is nautical mile.
fgMile 7 Length unit is mile.
fgRadian 100 Longitude / Latitude units are radian.
fgDegree 101 Longitude / Latitude units are degree.
fgGrad 102 Longitude / Latitude units are grads.
fgArcMinute 103 Longitude / Latitude units are minutes.
fgArcSecond 104 Longitude / Latitude units are seconds.
14.1.2.2 ProjectionMethod
fgUndefinedProjection 0 Value when nothing has been defined.
fgNoProjection 1 This system has no projection method.
fgLambertConfConic1SP 2 Lambert Conf Conic1 SP.
fgLambertConfConic2SP 3 Lambert Conf Conic2 SP.
fgMercator 4 Mercator.
fgCassiniSoldner 5 Cassini Soldner.
fgTransverseMercator 6 Transverse Mercator.
fgTransvMercatorSouthOriented 7 Transverse Mercator South Oriented.
fgObliqueStereographic 8 Oblique Stereographic.
fgNewZealandMapGrid 9 New Zealand Map Grid.
fgHotineObliqueMercator 10 Hotine Oblique Mercator.
fgLabordeObliqueMercator 11 Laborde Oblique Mercator.
228

fgSwissObliqueCylindrical 12 Swiss Oblique Cylindrical.
fgObliqueMercator 13 Oblique Mercator.
fgUTMProjection 14 UTM Projection.
14.1.2.3 ProjParameterIndices
fgUTMZoneNumber 0 Number of UTM zone.
fgLongitudeOfOrigin 0 Longitude of the origin of the zone.
fgLatitudeOfOrigin 1 Latitude of the origin of the zone.
fgFalseEasting 2 False "easting".
fgFalseNorthing 3 False "northing".
fgScaleFactorAtOrigin 4 Scaling factor at the origin.
fgLatitudeOf1stParallel 4 Latitude of the first parallel.
fgAzimuthOfCentralLine 5 Azimuth of the central line.
fgLatitudeOf2ndParallel 5 Latitude of the second parallel.
fgAngleFromRecttifiedToSkewed
6
Grid

EXTRACT_DEFAULT 0 All the geographic data present in the document will be used.

The value is point‐wise and is associated with the centre of a grid
PIXEL_POINT 0
mesh (corners of a 4‐point grid).
PIXEL_AREA 1 The value is surface‐area‐wise and associated with a mesh grid.

POLAR_NONE 0 No polarization or unknown polarization.
POLAR_HORIZ 1 Horizontal polarization.
POLAR_VERT 2 Vertical polarization.
229
230
AT321_TAG_E4 Atoll 3.2.1 Task Automation Guide
231
• 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
AT321_TAG_E4 www.forsk.com October 2014

Atoll 3.2.1 Task Automation Guide PDF

Hochgeladen von

Dokumentinformationen

Originaltitel

Copyright

Verfügbare Formate

Dieses Dokument teilen

Dokument teilen oder einbetten

Freigabeoptionen

Stufen Sie dieses Dokument als nützlich ein?

Sind diese Inhalte unangemessen?

Copyright:

Verfügbare Formate

Atoll 3.2.1 Task Automation Guide PDF

Hochgeladen von

Copyright:

Verfügbare Formate

Version 3.2.

1.3 Macro Tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

2.2 Properties and Methods Provided by Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

3.4 get_Active . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

3.5 put_Active . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

3.9 get_Path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

3.11 get_WindowStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

3.13 put_StatusBar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

3.15 put_Visible . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

3.16 get_Version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

3.17 Quit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

3.21 put_IniFileFullPath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .40

3.22 GetOption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .40

3.23 SetOption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41

3.25 SetAddinInfoEx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41

3.27 put_OLEBusyDialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .42

3.28 put_OLEMessagePendingDelay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .42

4.2 get_Count . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52

4.4 get_Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52

4.5 get_Parent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52

4.7 Add . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .53

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.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.20 Close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

5.21 FilePrint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

5.23 Refresh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

5.26 SetConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

5.29 Redraw . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

5.30 CenterMapOn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

5.31 GetRootFolder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

5.33 GetService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

5.34 ExportConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

5.38 put_RadiatedPowerUnit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

5.39 get_AntennaGainUnit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

5.40 put_AntennaGainUnit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

5.41 get_HeightOffsetUnit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

5.45 RunEx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

5.48 put_DisplayApplicationDialogues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

5.49 PutDatabaseSchemaString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .74

5.50 PutDatabaseConnectionString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .74

5.51 ChangeDatabaseConnection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .74

5.55 SetDocumentProperties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .75

6.2 get_ColumnCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .83

6.4 Edit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .83

6.5 AddNew . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .84

6.6 Update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .84

6.8 GetValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .84

6.9 SetValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .85

6.10 GetPrimaryKey . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .87

6.11 FindPrimaryKey . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .87

6.13 GetFormattedValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .88