Version 3.3.2
Task Automation Guide
AT332_TAG_E0
AT332_TAG_E0
Atoll 3.3.2 Task Automation Guide Release: AT332_TAG_E0 (November 2016) © Copyright 1997-2016 Forsk. All Rights Reserved. Published by: Forsk 7 rue des Briquetiers 31700 Blagnac, France Tel: +33 562 747 210 Fax: +33 562 747 211 The software described in this document is provided under a licence agreement. The software may only be used or copied under the terms and conditions of the licence agreement. No part of the contents of this document may be reproduced or transmitted in any form or by any means without written permission from the publisher. The product or brand names mentioned in this document are trademarks or registered trademarks of their respective registering parties. Third party services that are not part of Atoll are governed by the terms and conditions of their respective providers, which are subject to change without notice. The publisher has taken care in the preparation of this document, but makes no expressed or implied warranty of any kind and assumes no responsibility for errors or omissions. No liability is assumed for incidental or consequential damages in connection with or arising out of the use of the information contained herein.
Atoll 3.3.2 Task Automation Guide Table of Contents
AT332_TAG_E0
Table of Contents
1
Getting Started. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17
1.1
Supported Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
1.2 1.2.1 1.2.2 1.2.3 1.2.4 1.2.5
Script Tutorial. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 Writing a VBScript File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 Testing the Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 Scheduling the Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 Debugging the Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 Error Management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
1.3 1.3.1 1.3.2 1.3.3
Macro Tutorial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 Adding Macros to Atoll . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 Running a Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 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 2.2.1 2.2.2
Properties and Methods Provided by Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 Error Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
3
Application Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .33
3.1
How to Access the Application Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
3.2
get_Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
3.3
get_Parent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
3.4
get_Active . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
3.5
put_Active . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
3.6
get_Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
3.7
get_Name. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
3.8
get_FullName. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
3.9
get_Path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
3.10
get_ActiveDocument. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
3.11
get_WindowStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
3.12
put_WindowStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
3.13
put_StatusBar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
3.14
get_Visible . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
3.15
put_Visible . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
3.16
get_Version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
3.17
Quit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
3.18
LogMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
3.19
CreatePropertyContainer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
3
Atoll 3.3.2 Task Automation Guide Table of Contents
3.20
get_IniFileFullPath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .40
3.21
put_IniFileFullPath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .40
3.22
GetOption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .40
3.23
SetOption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41
3.24
Sleep . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41
3.25
SetAddinInfoEx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41
3.26
put_OLENotRespondingDialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .42
3.27
put_OLEBusyDialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .42
3.28
put_OLEMessagePendingDelay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .42
3.29
get_PID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .42
3.30 3.30.1 3.30.2 3.30.3 3.30.4 3.30.5 3.30.6 3.30.7 3.30.8 3.30.9 3.30.10 3.30.11 3.30.12 3.30.13 3.30.14 3.30.15 3.30.16
Application Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .42 WillQuitApp. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43 DocumentOpenComplete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43 WillCloseDocument . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43 WillSaveDocument . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43 DocumentSaveComplete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43 DocumentNewComplete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .44 WillRefreshDocument . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .44 RefreshDocumentComplete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .44 WillArchiveDocument. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .44 ArchiveDocumentComplete. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .44 WillRun . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45 RunComplete. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45 LicenceAcquireComplete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45 LicenceReleaseComplete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .46 WillNewDocumentFromDatabase. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .47 WillRunMicrowave . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .47
4
Documents Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
4.1
How to Access a Documents Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .51
4.2
get_Count . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52
4.3
get_Item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52
4.4
get_Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52
4.5
get_Parent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52
4.6
Open . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52
4.7
Add . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .53
4.8
OpenFromDatabase. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .53
4.9
CloseAll . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .54
4.10
SaveAll. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .55
5
4
© 2016 Forsk. All Rights Reserved.
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
AT332_TAG_E0
Atoll 3.3.2 Task Automation Guide Table of Contents
5.7
get_ReadOnly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
5.8
get_Saved. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
5.9
get_CoordSystemProjection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
5.10
putref_CoordSystemProjection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
5.11
get_CoordSystemDisplay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
5.12
putref_CoordSystemDisplay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
5.13
get_CoordSystemInternal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
5.14
get_TransmissionUnit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
5.15
put_TransmissionUnit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
5.16
get_ReceptionUnit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
5.17
put_ReceptionUnit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
5.18
get_DistanceUnit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
5.19
put_DistanceUnit. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
5.20
Close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
5.21
FilePrint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
5.22
Save. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
5.23
Refresh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
5.24
Archive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
5.25
Run . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
5.26
SetConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
5.27
Import. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
5.28
GetRecords. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
5.29
Redraw . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
5.30
CenterMapOn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
5.31
GetRootFolder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
5.32
RunPathloss . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
5.33
GetService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
5.34
ExportConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
5.35
GetCommandDefaults. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
5.36
InvokeCommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
5.37
get_RadiatedPowerUnit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
5.38
put_RadiatedPowerUnit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
5.39
get_AntennaGainUnit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
5.40
put_AntennaGainUnit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
5.41
get_HeightOffsetUnit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
5.42
put_HeightOffsetUnit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
5.43
get_DatabaseConnectionString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
5.44
HasRunningTask. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
5.45
RunEx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
5.46
get_DatabaseSchemaString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
5
Atoll 3.3.2 Task Automation Guide Table of Contents
5.47
get_DisplayApplicationDialogues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .73
5.48
put_DisplayApplicationDialogues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .74
5.49
PutDatabaseSchemaString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .74
5.50
PutDatabaseConnectionString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .74
5.51
ChangeDatabaseConnection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .74
5.52
get_TemperatureUnit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .75
5.53
put_TemperatureUnit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .75
5.54
GetDocumentProperties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .75
5.55
SetDocumentProperties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .75
5.56
get_RadioTableNames. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .77
5.57
LogMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .77
6
6
© 2016 Forsk. All Rights Reserved.
TabularData Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
6.1
How to Access a TabularData Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .82
6.2
get_ColumnCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .83
6.3
get_RowCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .83
6.4
Edit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .83
6.5
AddNew . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .84
6.6
Update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .84
6.7
Delete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .84
6.8
GetValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .84
6.9
SetValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .85
6.10
GetPrimaryKey . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .87
6.11
FindPrimaryKey . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .87
6.12
Find . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .87
6.13
GetFormattedValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .88
6.14
CancelUpdate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .89
6.15
get_ColumnNumber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .89
6.16
get_CanEdit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .89
6.17
get_CanAddNew . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .90
6.18
get_CanFilterSort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .90
6.19
get_Filter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .90
6.20
put_Filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .90
6.21
get_Sort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .91
6.22
put_Sort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .92
6.23
GetOriginalValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .92
6.24
get_RowStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .92
6.25
get_Columns. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .93
6.26
GetValues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .93
6.27
GetFormattedValues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .95
AT332_TAG_E0
Atoll 3.3.2 Task Automation Guide Table of Contents
6.28
SetValues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
6.29 6.29.1 6.29.2 6.29.3
Hidden Columns In Radio Tabular Data Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 Table MWLINKS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 Table MWOTLINKS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 Transmitters Tables, All Technologies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
7
Zones and Predictions Tabular Data Objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . .99
7.1
Zones Tabular Data Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
7.2
Predictions Tabular Data Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
8
CoordSystem Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .105
8.1
How to Access a CoordSystem Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
8.2
Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
8.3
ConvertCoordsTo. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
8.4
Datum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
8.5
DatumName. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
8.6
Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
8.7
Ellipsoid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
8.8
EllipsoidName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
8.9
Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
8.10
Pick . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
8.11
ProjMethod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
8.12
ProjParameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
8.13
SetDatum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
8.14
SetProjection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
8.15
Unit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
9
ChildFolder Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .113
9.1
How to Access a ChildFolder Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
9.2
get_Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
9.3
get_Parent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
9.4
get_Name. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
9.5
put_Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
9.6
get_Count. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
9.7
get_Item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
9.8
get__NewEnum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
9.9
get_Visible . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
9.10
put_Visible . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
9.11
get_Selected . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
9.12
put_Selected . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
9.13
Export . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
9.14
CentreOnMap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
9.15
Redraw . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
7
Atoll 3.3.2 Task Automation Guide Table of Contents
9.16
AddChild . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
9.17
Remove . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
9.18
get_position . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
9.19
put_position . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
9.20
get_Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
9.21
get_dispatch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
9.22
get_ObjectKind. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
9.23
GetProperty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
9.24
SetProperty. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
9.25
GetPropertiesInfo. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
9.26
PropertyIsPropertyContainer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
9.27
PropertyIsTabularData. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
9.28
LoadProperties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
9.29
SaveProperties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
9.30
RemoveItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
9.31
SetCustomIcon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
9.32
OpenPropertySheet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
10
PropertyContainer Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
10.1
Get. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
10.2
Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
10.3
GetInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
10.4
IsPropertyContainer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
10.5
IsTabularData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
10.6
Load. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
10.7
Save . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
10.8
RemoveAll. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
10.9
Remove . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
11
8
© 2016 Forsk. All Rights Reserved.
ChildFolder Object Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
11.1
How to Access ChildFolder Object Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
11.2
Common ChildFolder Object Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
11.3
Predictions Folder Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
11.4 11.4.1 11.4.2 11.4.3 11.4.4 11.4.5 11.4.6
Coverage Prediction Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . General Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Group, Filter, and Sort Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Non-Simulation-based Coverage Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Simulation-based Coverage Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Shadowing and Indoor Coverage Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Display Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
11.5
GSM Simulation Group Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
11.6
UMTS Simulation Group Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
11.7
WiMAX and LTE Simulation Group Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
137 140 141 141 143 144 144
AT332_TAG_E0
Atoll 3.3.2 Task Automation Guide Table of Contents
11.8
3GPP Multi-RAT Simulation Group Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
11.9
Standard Propagation Model Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
11.10
CW Measurement Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
11.11
Drive Test Data Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
11.12
Custom ChildFolder Object Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
11.13
Master Link Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
11.14
Link Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
11.15 11.15.1
Vector Layer Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154 Display Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
11.16
Aster Propagation Model Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
11.17
KPI Item Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
12
ChildFolder Feature Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .161
12.1 12.1.1 12.1.2 12.1.3 12.1.4 12.1.5
Clutter Feature Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161 How to Access the Clutter Feature Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161 get_Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161 get_ClassAttributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162 get_DefaultAttributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162 Accessing Clutter Class Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
12.2 12.2.1 12.2.2 12.2.3 12.2.4 12.2.5
Traffic Feature Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164 How to Access the Traffic Feature Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164 get_Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164 get_ScenarioProvider. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164 ExportCumulatedTraffic. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165 HasTrafficForService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
12.3 12.3.1 12.3.2
UMTS Traffic Scenario Provider Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167 GetMeanSize. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167 Create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
12.4 12.4.1 12.4.2 12.4.3 12.4.4 12.4.5
Environment Based Traffic Map Feature Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169 How to Access Environment Based Traffic Map Feature Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169 get_Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169 get_ClassAttributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169 get_DefaultAttributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169 Accessing Environment Based Traffic Maps Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
12.5 12.5.1 12.5.2 12.5.3 12.5.4 12.5.5 12.5.6 12.5.7
Simulation Feature Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171 How to Access Simulation Feature Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172 get_Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172 get_Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172 get_Cells . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173 get_Sites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173 get_Mobiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173 get_Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
12.6 12.6.1 12.6.2 12.6.3 12.6.4 12.6.5 12.6.6
Simulation Group Feature Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174 How to Access Simulation Group Feature Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174 get_Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176 get_Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176 get_MeanSimulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176 get_StdDevSimulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176 Accessing Mobiles, Cells, Sites, for Simulations and Simulation Groups. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
12.7 12.7.1 12.7.2 12.7.3 12.7.4
3GPP Multi-RAT Simulation Group Feature Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181 get_Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181 get_Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182 get_MeanSimulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182 get_StdDevSimulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
12.8
GSM Interference Matrix Feature Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
9
Atoll 3.3.2 Task Automation Guide Table of Contents
12.8.1 12.8.2 12.8.3 12.8.4 12.8.5 12.8.6 12.8.7 12.8.8 12.8.9 12.8.10 12.8.11 12.8.12 12.8.13 12.8.14 12.8.15 12.8.16 12.8.17 12.8.18
13
© 2016 Forsk. All Rights Reserved.
How to Access GSM Interference Matrix Feature Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . get_Source. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Load . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CompleteScopeInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . get_Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . put_Active . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . get_Active . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . get_Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . put_Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . get_BasedOnTraffic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . put_BasedOnTraffic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . get_Resolution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . put_Resolution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . get_StdDev . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . put_StdDev . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . get_InfoQuantityIndicator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . put_InfoQuantityIndicator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . get_CdfTab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
184 184 184 184 184 185 185 185 186 186 187 187 187 187 188 188 188 188
Document Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
13.1
How to Invoke a Document Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
13.2
IMPORTXML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
13.3
EXPORTXML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
13.4
APPENDTABLECOLUMN. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
13.5
CALCULATEPOINTS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
13.6
IMPORTTESTMOBILEDATA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
13.7
RUNNEIGHBOURALLOCATION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
13.8
RUNINTERTECHNOLOGYNEIGHBOURALLOCATION. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
13.9
RUNINTRACARRIERNEIGHBOURALLOCATION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200
13.10
RUNINTERCARRIERNEIGHBOURALLOCATION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
13.11
CLONESTUDY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
13.12
DUPLICATESTUDY. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
13.13
COMPARESTUDY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
13.14
CALCULATEEQUIPMENTLOSSES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
13.15
CALCULATEREPEATERS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
13.16
CALCULATEREMOTEANTENNAS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
13.17
EXPORTACTIVESETANALYSIS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
13.18
CALCULATEPOINTSECI0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
13.19
RUNALLCARRIERSALLOCATION . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
13.20
RUNMASTERCARRIERALLOCATION. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
13.21
MWRun . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
13.22
EXPORTMAPWINDOW. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
13.23
IMPORTPLANETDATAFILE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
13.24
EXPORTMWLINKANALYSISPROFILEPICTURE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
13.25
GETPOWERMODE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
13.26
SETPOWERMODE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
13.27
APPENDVECTORDATACOLUMN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
10
AT332_TAG_E0
Atoll 3.3.2 Task Automation Guide Table of Contents
13.28
LOADSAVEPRINTSETUP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
13.29
CALCULATEPATHLOSS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
13.30
MWLinksCustomExport. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
13.31
ARCHIVETODATABASE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
13.32
MWCalculateProfiles. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
13.33
PURGEPATHLOSSFOLDERS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
14 14.1 14.1.1 14.1.1.1 14.1.1.2 14.1.1.3 14.1.1.4 14.1.1.5 14.1.1.6 14.1.1.7 14.1.1.8 14.1.1.9 14.1.1.10 14.1.1.11 14.1.1.12 14.1.1.13 14.1.1.14 14.1.1.15 14.1.1.16 14.1.1.17 14.1.2 14.1.2.1 14.1.2.2 14.1.2.3
Enumerations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .231 Enumerations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231 Atoll Type Library Enumerations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231 AtoSaveStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231 AtoSaveChanges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231 AtoRefreshPriority . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231 AtoArchiveStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231 AtoWindowStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231 AtoLogType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232 AtoCompareOp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232 AtoTransmissionUnit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232 AtoReceptionUnit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232 AtoDistanceUnit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232 AtoRadiatedPowerUnit. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233 AtoAntennaGainUnit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233 AtoHeightOffsetUnit. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233 AtoRootType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233 AtoRowFilter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233 AtoRowStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233 AtoTemperatureUnit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234 FSKGISLib Type Library Enumerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234 GeographicUnit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234 ProjectionMethod. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234 ProjParameterIndices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
11
Atoll 3.3.2 Task Automation Guide Table of Contents
12
© 2016 Forsk. All Rights Reserved.
Atoll 3.3.2 Task Automation Guide Introduction
AT332_TAG_E0
Atoll 3.3.2 Task Automation Guide This Task Automation Guide is aimed at advanced administrators who plan to write scripts or macros to enhance the functionalities that are available in Atoll. This manual assumes that the reader has an advanced knowledge of Atoll and radio network planning and is familiar with Microsoft script technologies and the VBScript language in particular.
About Atoll Atoll is a 64-bit multi-technology wireless network design and optimisation platform. Atoll is open, scalable, flexible, and supports wireless operators throughout the network life cycle, from initial design to densification and optimisation. Atoll includes integrated single RAN – multiple RAT network design capabilities for both 3GPP (GSM/UMTS/LTE) and 3GPP2 (CDMA/LTE) technology streams. It provides operators and vendors with a powerful native 64-bit framework for designing and optimising current and future integrated multi-technology networks. Atoll supports multi-technology HetNets, small cell planning, and Wi-Fi offloading. Atoll Microwave is a complete backhaul and microwave link planning solution based on the leading Atoll platform, which includes a high performance GIS and advanced data and user management features. Atoll Microwave can share its site database with Atoll radio planning and optimisation modules, thus allowing easy data consistency management across the operator organisation. Atoll’s integration and automation features help operators smoothly automate planning and optimisation processes through flexible scripting and SOA-based mechanisms. Atoll supports a wide range of implementation scenarios, from standalone to enterprise-wide server-based configurations. If you are interested in learning more about Atoll, please contact your Forsk representative to inquire about our training solutions.
About Forsk Forsk is an independent company providing radio planning and optimisation software solutions to the wireless industry since 1987. In 1997, Forsk released the first version of Atoll, its flagship radio planning software. Since then, Atoll has evolved to become a comprehensive radio planning and optimisation platform and, with more than 7000 installed licenses worldwide, has reached the leading position on the global market. Atoll combines engineering and automation functions that enable operators to smoothly and gradually implement SON processes within their organisation. Today, Forsk is a global supplier with over 450 customers in 120 countries and strategic partnerships with major players in the industry. Forsk distributes and supports Atoll directly from offices and technical support centres in France, USA, and China as well as through a worldwide network of distributors and partners. Since the first release of Atoll, Forsk has been known for its capability to deliver tailored and turn-key radio planning and optimisation environments based on Atoll. To help operators streamline their radio planning and optimisation processes, Forsk provides a complete range of implementation services, including integration with existing IT infrastructure, automation, as well as data migration, installation, and training services.
Getting Help The online help system that is installed with Atoll is designed to give you quick access to the information you need to use the product effectively. It contains the same material as the Atoll 3.3.2 User Manual. You can browse the online help from the Contents view, the Index view, or you can use the built-in Search feature. You can also download manuals from the Forsk web site at: http://www.forsk.com/MyForskAccount/
Printing Help Topics You can print individual topics or chapters from the online help.
13
Atoll 3.3.2 Task Automation Guide Introduction
© Forsk 2016. All Rights Reserved.
To print help topics or chapters: 1. In Atoll, click Help > Help Topics. 2. In the Contents tab, expand the table of contents. 3. Right-click the section or topic that you want to print and click Print. The Print Topics dialog box appears. 4. In the Print Topics dialog box, select what you want to print: • •
If you want to print a single topic, select Print the selected topic. If you want to print an entire section, including all topics and sections in that section, select Print the selected heading and all subtopics.
5. Click OK.
About Atoll Documentation The following PDF manuals are available for Atoll and Atoll Microwave and can be downloaded from the Forsk web site at: http://www.forsk.com/MyForskAccount/ • • • • • •
Atoll User Manual Atoll Administrator Manual Atoll Data Structure Reference Guide Atoll Technical Reference Guide Atoll Task Automation Guide Atoll Model Calibration Guide
To read PDF manuals, download Adobe Reader from the Adobe web site at: http://get.adobe.com/reader/ Hardcopy manuals are also available. For more information, contact to your Forsk representative.
Contacting Technical Support Forsk provides global technical support for its products and services. To contact the Forsk support team, visit the My Forsk web site at: http://www.forsk.com/MyForskAccount/ Alternatively, depending on your geographic location, contact one of the following support teams: •
Forsk Head Office For regions other than North and Central America and China, contact the Forsk Head Office support team: • • •
Tel.: +33 562 747 225 Fax: +33 562 747 211 Email:
[email protected]
Opening Hours: Monday to Friday 9.00 am to 6.00 pm (GMT +1:00) •
Forsk US For North and Central America, contact the Forsk US support team: • • •
Tel.: 1-888-GO-ATOLL (1-888-462-8655) Fax: 1-312-674-4822 Email:
[email protected]
Opening Hours: Monday to Friday 8.00 am to 8.00 pm (Eastern Standard Time) •
Forsk China For China, contact the Forsk China support team: • • •
Tel: +86 20 8557 0016 Fax: +86 20 8553 8285 Email:
[email protected]
Opening Hours: Monday to Friday 9.00am to 5.30pm (GMT+08:00) Beijing, Chongqing, Hong Kong, Urumqi.
14
Chapter 1 Getting Started
Atoll 3.3.2 Task Automation Guide ©2016 Forsk. All Rights Reserved
16
Atoll 3.3.2 Task Automation Guide Chapter 1: Getting Started
AT332_TAG_E0
1 Getting Started Atoll provides an application programming interface that enables you to extend and customise Atoll. If you plan to write scripts or macros, you must be familiar with Microsoft Windows Script Technologies, especially with the VBScript language. You can start by: • •
Going through the section "Supported Extensions" on page 17 to learn which types of extensions can be developed. Reading the following tutorials before starting your own development: • •
"Script Tutorial" on page 17, "Macro Tutorial" on page 23,
1.1 Supported Extensions The following types of extensions are available. •
Scripts A script is a sequence of VBScript statements in a text file, executable from outside Atoll (Windows Script Host). Scripts allow task automation in Atoll when no interaction with the user is needed. Scripts do not require any setup and are specially useful for scheduling tasks in batch mode. Scripts use COM inter-process communication for communicating with Atoll. Sample code: Several scripts are available for download at www.forsk.com.
•
Macros A macro is a sequence of VBScript statements in a text file, executable from within Atoll. Macros allow task automation 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")
17
Atoll 3.3.2 Task Automation Guide Chapter 1: Getting Started
© 2016 Forsk. All Rights Reserved.
WScript.ConnectObject myapp, "Atoll_" myapp.Visible = False Set doc = myapp.Documents.OpenFromDatabase( "Provider=SQLOLEDB.1;Integrated Security=SSPI;Initial Catalog=myAtollDbName;Data Source=myServer", "dbo;;") 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 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.
18
Atoll 3.3.2 Task Automation Guide Chapter 1: Getting Started
AT332_TAG_E0
To open the Windows Task Scheduler: 1. Select Start > Settings > Control Panel. The Control Panel opens. 2. Double-click the Scheduled Tasks icon. 3. Double-click the Add Scheduled Task icon. The Scheduled Taks Wizard opens. 4. Click Next.
Figure 1.1: Scheduled Tasks Wizard 5. Click the Browse button. 6. Select cscript.exe. 7. Click Next.
Figure 1.2: Scheduled Tasks Wizard 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
Atoll 3.3.2 Task Automation Guide Chapter 1: Getting Started
© 2016 Forsk. All Rights Reserved.
Figure 1.3: Scheduled Tasks Wizard 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
Atoll 3.3.2 Task Automation Guide Chapter 1: Getting Started
AT332_TAG_E0
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
Atoll 3.3.2 Task Automation Guide Chapter 1: Getting Started
© 2016 Forsk. All Rights Reserved.
End If If IsObject(myapp) Then myapp.Documents.CloseAll atoSaveNo myapp.Quit 0 myapp = Null End If WScript.Quit -1 End Sub Sub Atoll_RunComplete(arg1, arg2) var = 1 End Sub Set myapp = CreateObject("Atoll.Application") If Err Then WScript.Echo "Can't create 'Atoll.Application' object." Err.Clear Call CatchError End If WScript.ConnectObject myapp, "Atoll_" myapp.Visible = False Set doc = myapp.Documents.OpenFromDatabase( "Provider=SQLOLEDB.1;Integrated Security=SSPI;Initial Catalog=myAtollDbName;Data Source=myServer", "dbo;;") If Err Then Call CatchError End If doc.Run True If Err Then Call CatchError End If var = 0 Do While var = 0 WScript.Sleep 1000 Loop doc.Save("C:\mydoc.atl") If Err Then Call CatchError End If WScript.DisconnectObject myapp doc = Null myapp.Documents.CloseAll atoSaveNo
22
Atoll 3.3.2 Task Automation Guide Chapter 1: Getting Started
AT332_TAG_E0
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 anAtoll Application object is automatically added as a script-level variable available to the macro code. Therefore, CreateObject or GetObject to access an Application object must not be called. The first line of your macro can be directly: 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 On Error Resume Next status = doc.Archive Const atoError = 1 Const atoArchiveCanceled = 1 If Err.Number 0 Then LogMessage "Archive on save failed. " & Err.Description & ".", atoError Else If status = atoArchiveCanceled Then LogMessage "Archive on save failed.", atoError LogMessage "You must resolve the conflicts manually.", atoError MsgBox "Archive on save failed. You must resolve the conflicts manually." Else LogMessage "Archive on save completed successfully."
23
Atoll 3.3.2 Task Automation Guide Chapter 1: Getting Started
© 2016 Forsk. All Rights Reserved.
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
Atoll 3.3.2 Task Automation Guide Chapter 1: Getting Started
AT332_TAG_E0
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 indicated. 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:
Only 32-bit Atoll installed Only 64-bit Atoll installed
Both 32-bit and 64-bit Atoll installed
32-bit WSH used to run the script
32-bit Atoll is launched
64-bit Atoll is launched
32-bit Atoll is launched
64-bit WSH used to run 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
Atoll 3.3.2 Task Automation Guide Chapter 1: Getting Started
26
© 2016 Forsk. All Rights Reserved.
Chapter 2 Object Model
Atoll 3.3.2 Task Automation Guide ©2016 Forsk. All Rights Reserved
28
Atoll 3.3.2 Task Automation Guide Chapter 2: Object Model
AT332_TAG_E0
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 TabularData 1
Document 2
PropertyContainer 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
Application Object
The Application object provides an entry point for clients to retrieve and navigate through the Atoll object model.
Documents Object
The Documents object is used to create a new document or to iterate through open documents in an Atoll session.
Document Object
The Document object provides access to ATL documents and database connections.
TabularData Object
The TabularData object provides access to Atoll tables whether an Atoll document is connected to a database or not. It also provides access to other tables which are not database tables, such as PREDICTIONS and ZONES.
CoordSystem Object
This object contains the entire definition of a coordinate system.
ChildFolder Object
A ChildFolder object represents an item in the Atoll Explorer window.
PropertyContainer Object
The PropertyContainer object is a generic container containing a set of named properties of arbitrary types
Transmitter Object
The Transmitter object provides read-only access to antenna patterns, antenna losses, and some transmitter properties.
2.1 Interfaces Implemented by Objects Atoll objects provide access to Atoll components through properties and methods.
29
Atoll 3.3.2 Task Automation Guide Chapter 2: Object Model
© 2016 Forsk. All Rights Reserved.
2.2 Properties and Methods Provided by Objects Access to Atoll components is available through properties and methods. Properties and methods usually have input and output parameters. For reading and writing a property, you write: 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 scriptlevel 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
Atoll 3.3.2 Task Automation Guide ©2016 Forsk. All Rights Reserved
32
Atoll 3.3.2 Task Automation Guide Chapter 3: Application Object
AT332_TAG_E0
3 Application Object The Application object provides an entry point for clients to retrieve and navigate through the Atoll object model. •
IApplication7
The Application object provides the following properties and methods: Name
Description
Attributes
get_Application
Returns the Atoll Application object.
Type: Application object Access: Read
get_Parent
Returns the Atoll Application object.
Type: Application object Access: Read
get_Active
Returns whether the Atoll window is active or not.
Type: Boolean Access: Read/Write
put_Active
Sets the Atoll window active.
Type: Boolean Access: Read/Write
get_Documents
Returns the Documents object.
Type: Documents object Access: Read
get_Name
Returns the application name. The application name is always "Atoll".
Type: String Access: Read
get_FullName
Returns the full path of the executable.
Type: String Access: Read
get_Path
Returns the path of the executable.
Type: String Access: Read
get_ActiveDocument
Returns the active document.
Type: Document object Access: Read
get_WindowStatus
Returns the window status of the Atoll application.
Type: Integer Access: Read/Write
put_WindowStatus
Sets the window status of the Atoll application.
Type: Integer Access: Read/Write
put_StatusBar
Sets the status bar text of the Atoll application.
Type: String Access: Write
get_Visible
Returns the application visible state.
Type: Boolean Access: Read/Write
put_Visible
Sets the application visible state.
Type: Boolean Access: Read/Write
get_Version
Returns the application version.
Type: String Access: Read
Quit
Quits the application.
LogMessage
Displays a message in the Atoll event observer window.
CreatePropertyContainer
Returns an empty PropertyContainer object.
get_IniFileFullPath
Returns the full path to the Atoll initialisation file.
Type: String Access: Read/Write
put_IniFileFullPath
Sets the full path to the Atoll initialisation file.
Type: String Access: Read/Write
GetOption
Returns an option read from the Atoll initialisation file.
33
Atoll 3.3.2 Task Automation Guide Chapter 3: Application Object
© 2016 Forsk. All Rights Reserved.
Name
Description
SetOption
Sets an option in the Atoll initialisation file.
Sleep
Suspends the application apartment execution.
Attributes
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 application 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".
34
Atoll 3.3.2 Task Automation Guide Chapter 3: Application Object
AT332_TAG_E0
3.2 get_Application Returns the Atoll Application object. 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 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.
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 Set app = CreateObject("Atoll.Application") 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.
35
Atoll 3.3.2 Task Automation Guide Chapter 3: Application Object
© 2016 Forsk. All Rights Reserved.
3.6 get_Documents Returns the Documents object. 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 app = CreateObject("Atoll.Application") 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".
36
Atoll 3.3.2 Task Automation Guide Chapter 3: Application Object
AT332_TAG_E0
3.10 get_ActiveDocument Returns the active document. 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 app = CreateObject("Atoll.Application") 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 Set app = CreateObject("Atoll.Application") 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.
37
Atoll 3.3.2 Task Automation Guide Chapter 3: Application Object
© 2016 Forsk. All Rights Reserved.
3.13 put_StatusBar Sets the status bar text of the Atoll application. HRESULT put_StatusBar(const BSTR bstrNewVal); Parameters [in] bstrNewVal: The text to display in the status bar. Example Dim app Set app = CreateObject("Atoll.Application") 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);
38
Atoll 3.3.2 Task Automation Guide Chapter 3: Application Object
AT332_TAG_E0
Parameters [out] pVal: Address of the BSTR used to return the version. Remarks The string is formatted like in the Atoll about dialogue, for example, "2.6.1". Atoll 3.1.0 and above: The application build number is included in the string, for example, "3.1.0 (Build 3730)"
3.17 Quit Quits the application. 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.
Remarks Once this method has returned the Atoll Application object has been destroyed and invoking any method on it will result in undefined behaviour.
3.18 LogMessage Displays a message in the Atoll event observer window. 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.
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
Atoll 3.3.2 Task Automation Guide Chapter 3: Application Object
© 2016 Forsk. All Rights Reserved.
Remarks The VARIANT returned if of type VT_DISPATCH, and it implements the IPropertyContainer interface. The empty container returned can be used to hold default parameters specific to an Atoll document command or to hold an Atoll ChildFolder Object properties.
3.20 get_IniFileFullPath Returns the full path to the Atoll Initialisation File. 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. Please note that for performance reasons, some options read from the Initialisation File by Atoll are cached for subsequent usage. After the path to the Initialisation File has been changed, and in order for some options to be used, it is necessary to quit Atoll and start it again. Therefore, it is recommended to change the full path to the Initialisation File as soon as the Atoll Application Object has been created. Please refer to the Atoll Administrator Manual for the list of available options.
3.22 GetOption Returns an option read from the Atoll Initialisation File. 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
Atoll 3.3.2 Task Automation Guide Chapter 3: Application Object
AT332_TAG_E0
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. Please note that for performance reasons, some options read from the Initialisation File by Atoll are cached for subsequent usage. Therefore, it is recommended to set options as soon as the Atoll Application Object has been created. Please refer to the Atoll Administrator Manual for the list of available sections and options.
3.24 Sleep Suspends the application apartment execution.
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
Atoll 3.3.2 Task Automation Guide Chapter 3: Application Object
© 2016 Forsk. All Rights Reserved.
Parameters
3.26 put_OLENotRespondingDialog Enables or disables OLE not responding dialog.
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 get_PID Returns the Windows Process ID of the Atoll session.
HRESULT get_PID(long* pVal); Parameters [out] pVal: Address of the long integer used to return the process ID of the Atoll session.
3.30 Application Events Events related to the application are fired: • • • • • • • • •
42
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,
Atoll 3.3.2 Task Automation Guide Chapter 3: Application Object
AT332_TAG_E0
• •
When a document has been archived in database, When a calculation is requested,
•
When a Microwave calculation is requested,
• • • •
After a calculation has completed, When a licence is acquired, When a licence is released, Before a new document is created from an existing database.
3.30.1 WillQuitApp Event fired when the user wants to exit an Atoll session. It occurs just before all add-ins are disconnected and after all documents have been closed. 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.30.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.30.3 WillCloseDocument Event fired when the user wants to close a document. It occurs just before the document closes, i.e., after all confirmations requested by Atoll have been answered (stop running tasks, save changes, etc...). 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.30.4 WillSaveDocument Event fired when the user wants to save a document. It occurs just before the document file is saved but after a valid file name is set. 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.30.5 DocumentSaveComplete Event fired just after a document has been saved.
43
Atoll 3.3.2 Task Automation Guide Chapter 3: Application Object
© 2016 Forsk. All Rights Reserved.
HRESULT DocumentSaveComplete (IDocument* document); Parameters [in] document: The IDocument interface pointer of the document which has been successfully saved.
3.30.6 DocumentNewComplete Event fired when a new document has been created. HRESULT DocumentNewComplete(IDocument* document); Parameters [in] document: The IDocument interface pointer of the document which has been created.
3.30.7 WillRefreshDocument Event fired when the user wants to refresh a document from database. It occurs just before the connection with the database is checked. 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.30.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.30.9 WillArchiveDocument Event fired when the user wants to archive a document to the database. It occurs just after the connection with the database is set up and after Atoll has checked if any changes have to be archived. If nothing requires archiving, this event is not fired. 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.30.10 ArchiveDocumentComplete Event fired when the document has been archived in database. It occurs just before the connection with the database is broken.
44
Atoll 3.3.2 Task Automation Guide Chapter 3: Application Object
AT332_TAG_E0
HRESULT ArchiveDocumentComplete(IDocument* document); Parameters [in] document: The IDocument interface pointer of the document which has been archived.
3.30.11 WillRun Event fired when the user wants to start a calculation. If all is set to VARIANT_TRUE, this event occurs after the user has confirmed that all previous calculations must be deleted. 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.30.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 calculation 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.30.13 LicenceAcquireComplete This feature enables the user to log Atoll licence token usage from an add-in. Licence token consumption is available globally for all Atoll instances running on one licence server using a dedicated application (monitor.exe). External licence tokens are not tracked by this event. Licence events for the Measurements module (Measures) is available for auto-connected add-ins only. Fired when one licence token is acquired. HRESULT LicenceAcquireComplete( IDocument *pDocument,
45
Atoll 3.3.2 Task Automation Guide Chapter 3: Application Object
© 2016 Forsk. All Rights Reserved.
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. 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.30.14 LicenceReleaseComplete This feature enables the user to log Atoll licence token usage from an add-in. Licence token consumption is available globally for all Atoll instances running on one licence server using a dedicated application (monitor.exe). External licence tokens are not tracked by this event. Licence events for the Measurements (Measures) module will be available for autoconnected add-ins only. Fired when one licence token is released. HRESULT LicenceReleaseComplete( IDocument *pDocument, long lModuleID );
46
Atoll 3.3.2 Task Automation Guide Chapter 3: Application Object
AT332_TAG_E0
Parameters [in] pDocument: The IDocument interface pointer of the document that just released the licence token. [in] lModuleID: The long integer used to specify the ID of the licence token that has just been released. Remarks lModuleID will be one of these constant values: • • • • • • • •
LICENCE_GSMTDMA LICENCE_MW LICENCE_PACK3G LICENCE_UMTS LICENCE_CDMA LICENCE_TDSCDMA LICENCE_WIMAX LICENCE_LTE
3.30.15 WillNewDocumentFromDatabase 3.2.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 identified by the connexion and schema parameters is allowed (VARIANT_TRUE) or not (VARIANT_FALSE).
3.30.16 WillRunMicrowave Event fired when the user wants to start a Microwave calculation. HRESULT WillRunMicrowave( IDocument* document, VARIANT_BOOL all, VARIANT_BOOL* evtStatus ); Parameters [in] document: The IDocument interface pointer of the document on which Microwave calculation is requested. [in] all: A VARIANT_BOOL value used to specify whether the user has requested "Calculate All (Ctrl+F7)" (VARIANT_TRUE) or "Calculate (F7)" (VARIANT_FALSE). [out] evtStatus: A VARIANT_BOOL pointer used to return whether Microwave calculation is allowed to run against the document (VARIANT_TRUE) or not (VARIANT_FALSE).
47
Atoll 3.3.2 Task Automation Guide Chapter 3: Application Object
48
© 2016 Forsk. All Rights Reserved.
Chapter 4 Documents Object
Atoll 3.3.2 Task Automation Guide ©2016 Forsk. All Rights Reserved
50
Atoll 3.3.2 Task Automation Guide Chapter 4: Documents Object
AT332_TAG_E0
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: Name
Description
Attributes
get_Count
Returns the number of currently open documents ina session.
Type: Integer Access: Read
get_Item
Returns one document currently open in a session.
Type: Documents object Access: Read
get_Application
Returns the Atoll application object.
Type: Application object Access: Read
get_Parent
Returns the Atoll application object.
Type: Application object Access: Read
Open
Opens an existing document and adds it to the collection of open documents.
Add
Creates a new document and adds it to the collection of open documents.
OpenFromDatabase
Creates a new document from a database and adds it to the collection of open documents.
CloseAll
Closes all open documents.
SaveAll
Saves all open documents.
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
Atoll 3.3.2 Task Automation Guide Chapter 4: Documents Object
© 2016 Forsk. All Rights Reserved.
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. HRESULT get_Application(IApplication **ppVal); 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
Atoll 3.3.2 Task Automation Guide Chapter 4: Documents Object
AT332_TAG_E0
HRESULT Open(const **pDoc);
BSTR
bstrPathName,
VARIANT_BOOL
aReadOnly,
IDocument
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: Value[;PropertyName = Value] Available properties are: Property Name
Value
Version
Description
Project
string
2.6.0
Database schema
53
Atoll 3.3.2 Task Automation Guide Chapter 4: Documents Object
© 2016 Forsk. All Rights Reserved.
Keep Connection
0|1
2.6.0
Whether to keep connection with the database or not
Field Groups
group name [,group name]
2.6.0
Comma separated values of field groups
Site Lists
site list[,site list]
2.6.0
Comma separated values of site lists
IntraTechnology Neighbours
0|1
2.6.1
Whether to load the table "NEIGHBOURS" or not
InterTechnology Neighbours
0|1
2.6.1
Whether to load the table "NEIGHBOURSEXT" or not
3.1.2
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: GSM UMTS LTE When no property named "Systems" is specified in the schema string, all radio technologies are loaded.
Systems
system,[system]
[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 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 "". 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: Creating a new document from a 3GPP Multi-RAT Oracle database, loading LTE and UMTS information only:
4.9 CloseAll Closes all open documents. HRESULT CloseAll(AtoSaveChanges saveChanges, AtoSaveStatus *status);
54
Atoll 3.3.2 Task Automation Guide Chapter 4: Documents Object
AT332_TAG_E0
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
Atoll 3.3.2 Task Automation Guide Chapter 4: Documents Object
56
© 2016 Forsk. All Rights Reserved.
Chapter 5 Document Object
Atoll 3.3.2 Task Automation Guide ©2016 Forsk. All Rights Reserved
58
Atoll 3.3.2 Task Automation Guide Chapter 5: Document Object
AT332_TAG_E0
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: Name
Description
Attributes
get_Application
Returns the Atoll Application Object.
Type: Application object Access: Read
get_Parent
Returns the Atoll Documents collection.
Type: Documents object Access: Read
get_FullName
Returns the document full path.
Type: String Access: Read
get_Name
Returns the document file name without the extension.
Type: String Access: Read
get_Path
Returns the document path.
Type: String Access: Read
get_ReadOnly
Returns true if the document is read-only, false otherwise.
Type: Boolean Access: Read
get_Saved
Returns false if the document contains unsaved changes, true otherwise.
Type: Boolean Access: Read
get_CoordSystemProjection
Returns the projection coordinate system of a document.
Type: CoordSystem object Access: Read/Write
putref_CoordSystemProjection
Sets the projection coordinate system of a document.
Type: CoordSystem object Access: Read/Write
get_CoordSystemDisplay
Returns the display coordinate system of a document.
Type: CoordSystem object Access: Read/Write
putref_CoordSystemDisplay
Sets the display coordinate system of a document.
Type: CoordSystem object Access: Read/Write
get_CoordSystemInternal
Returns the internal coordinate system of a document.
Type: CoordSystem object Access: Read
get_TransmissionUnit
Returns the transmission power unit.
Type: Integer Access: Read/Write
put_TransmissionUnit
Sets the transmission power unit.
Type: Integer Access: Read/Write
get_ReceptionUnit
Returns the signal level reception unit.
Type: Integer Access: Read/Write
put_ReceptionUnit
Sets the signal level reception unit.
Type: Integer Access: Read/Write
get_DistanceUnit
Returns the display distance unit.
Type: Integer Access: Read/Write
59
Atoll 3.3.2 Task Automation Guide Chapter 5: Document Object
60
© 2016 Forsk. All Rights Reserved.
Name
Description
Attributes
put_DistanceUnit
Sets the display distance unit.
Type: Integer Access: Read/Write
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.
GetRecords
Returns a TabularData object for a requested category of records.
Redraw
Refreshes all items in the document.
CenterMapOn
Centres map on a parameter point.
GetRootFolder
Returns the root ChildFolder object used to enumerate all ChildFolder objects belonging to one tab of the Atoll explorer window.
RunPathloss
Calculates the path loss matrices with no need for any predefined studies.
GetService
Returns a Document Service Object.
ExportConfig
Exports a subset of the current document configuration to a file.
GetCommandDefaults
Returns current default parameters specific to a command.
InvokeCommand
Invokes a command.
get_RadiatedPowerUnit
Returns the current radiated power unit.
Type: Integer Access: Read/Write
put_RadiatedPowerUnit
Sets the current radiated power unit.
Type: Integer Access: Read/Write
get_AntennaGainUnit
Returns the current antenna gain unit.
Type: Integer Access: Read/Write
put_AntennaGainUnit
Sets the current antenna gain unit.
Type: Integer Access: Read/Write
get_HeightOffsetUnit
Returns the current height offset unit.
Type: Integer Access: Read/Write
put_HeightOffsetUnit
Sets the current height offset unit.
Type: Integer Access: Read/Write
get_DatabaseConnectionString
Returns the database connection string.
Type: String Access: Read/Write
HasRunningTask
Returns true when there is some calculation in progress.
Type: Boolean Access: Read
RunEx
Starts calculations.
get_DatabaseSchemaString
Returns the database schema string.
Type: String Access: Read/Write
Atoll 3.3.2 Task Automation Guide Chapter 5: Document Object
AT332_TAG_E0
Name
Description
Attributes
get_DisplayApplicationDialogues
Returns true when some methods on some Atoll interfaces may display some dialogue boxes.
Type: Boolean Access: Read/Write
put_DisplayApplicationDialogues
Returns true when some methods on some Atoll interfaces may display some dialogue boxes.
Type: Boolean Access: Read/Write
PutDatabaseSchemaString
Sets the database schema string.
Type: String Access: Read/Write
PutDatabaseConnectionString
Sets the database connection string.
Type: String Access: Read/Write
ChangeDatabaseConnection
Changes the database connection string.
Type: 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. HRESULT get_Application(IApplication **ppVal); 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
Atoll 3.3.2 Task Automation Guide Chapter 5: Document Object
© 2016 Forsk. All Rights Reserved.
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. HRESULT get_Name(BSTR *pVal); Parameters [out] pVal: Address of the BSTR used to return the document file name without the extension. Remarks With a new document that has never been saved, or a document opened from a database, an empty string is returned.
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 With a new document that has never been saved, or a document opened from a database, an empty string is returned.
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
Atoll 3.3.2 Task Automation Guide Chapter 5: Document Object
AT332_TAG_E0
HRESULT get_CoordSystemProjection(IDispCoordSystem **ppVal); Parameters [out] ppVal: Address of the IDispCoordSystem interface pointer used to return the projection coordinate system of the document.
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 document. 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 coordinate system is changed. When the document is connected to a database, the internal coordinate system is the display coordinate 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
Atoll 3.3.2 Task Automation Guide Chapter 5: Document Object
© 2016 Forsk. All Rights Reserved.
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
Atoll 3.3.2 Task Automation Guide Chapter 5: Document Object
AT332_TAG_E0
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.
atoSavePrompt
2
The user is prompted whether the document must be saved before closed.
[out] pStatus: Address of the AtoSaveStatus enumeration value. Returned values are: Constant
Value
Description
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
Atoll 3.3.2 Task Automation Guide Chapter 5: Document Object
© 2016 Forsk. All Rights Reserved.
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 DisplayApplicationDialogue 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
Atoll 3.3.2 Task Automation Guide Chapter 5: Document Object
AT332_TAG_E0
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
Atoll 3.3.2 Task Automation Guide Chapter 5: Document Object
© 2016 Forsk. All Rights Reserved.
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 account 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: Pointers to double precision floating point values used to specify the coordinates of the point to centres the map view on, expressed in meters, using the document projected 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
Atoll 3.3.2 Task Automation Guide Chapter 5: Document Object
AT332_TAG_E0
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. 3) An error is returned when it is called on a Microwave Radio Links Atoll document. 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
Atoll 3.3.2 Task Automation Guide Chapter 5: Document Object
© 2016 Forsk. All Rights Reserved.
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.
Atoll 2.7.1 and above: bstrContent is parsed according to the format "OPTION[+OPTION]". The set of specified options are exported to bstrFile. Available options are: OPTION name
Description
GEO
Geographic Data Set
ZONES
Computation and Focus Zones
STUDIES
Prediction List
Atoll 3.1.0 and above: 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
Atoll 3.3.2 Task Automation Guide Chapter 5: Document Object
AT332_TAG_E0
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 parameters 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
Atoll 3.3.2 Task Automation Guide Chapter 5: Document Object
© 2016 Forsk. All Rights Reserved.
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
Atoll 3.3.2 Task Automation Guide Chapter 5: Document Object
AT332_TAG_E0
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. 2) An error is returned when it is called on a Microwave Radio Links Atoll document. 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
Atoll 3.3.2 Task Automation Guide Chapter 5: Document Object
© 2016 Forsk. All Rights Reserved.
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
Atoll 3.3.2 Task Automation Guide Chapter 5: Document Object
AT332_TAG_E0
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
Atoll 3.3.2 Task Automation Guide Chapter 5: Document Object
© 2016 Forsk. All Rights Reserved.
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
76
USER_PROPERTY_NAME0
String
USER_PROPERTY_NAME1
String
USER_PROPERTY_NAME2
String
USER_PROPERTY_NAME3
String
USER_PROPERTY_NAME4
String
USER_PROPERTY_NAME5
String
USER_PROPERTY_NAME6
String
USER_PROPERTY_NAME7
String
USER_PROPERTY_NAME8
String
Atoll 3.3.2 Task Automation Guide Chapter 5: Document Object
AT332_TAG_E0
USER_PROPERTY_NAME9
String
5.56 get_RadioTableNames Returns the names of Radio TabularData Objects in the document. HRESULT get_RadioTableNames(VARIANT* pTableNames); Parameters [out] pTableNames: Address of the VARIANT used to return the names of radio database tables in the document. The variant returned is an Array of variants, with variants of type String.
5.57 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.
77
Atoll 3.3.2 Task Automation Guide Chapter 5: Document Object
78
© 2016 Forsk. All Rights Reserved.
Chapter 6 TabularData Object
Atoll 3.3.2 Task Automation Guide ©2016 Forsk. All Rights Reserved
80
Atoll 3.3.2 Task Automation Guide Chapter 6: TabularData Object
AT332_TAG_E0
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 99. 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 database. Access is not given to the current content of the database. Therefore, it is not possible 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 database. They are stored in the Atoll document. The TabularData object provides the following properties and methods: Name
Description
Attributes
get_ColumnCount
Returns the number of columns of the TabularData Object.
Type: Integer Access: Read
get_RowCount
Returns the number of rows of the TabularData Object
Type: Integer Access: Read
Edit
Puts a row into edition mode.
AddNew
Adds a new empty row to the TabularData Object. The row added is put into edition mode.
Update
Commits a row changes and puts the row from edition mode 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.
FindPrimaryKey
Searches the row whose primary key equals the input value 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.
get_ColumnNumber
Returns a column number.
Type: Integer Access: Read
get_CanEdit
Checks if rows can be modified.
Type: Boolean Access: Read
get_CanAddNew
Checks if rows can be added.
Type: Boolean Access: Read
get_CanFilterSort
Checks if rows can be filtered or sorted.
Type: Boolean Access: Read
get_Filter
Returns the filter currently set on the table.
Type: String Access: Read/Write
81
Atoll 3.3.2 Task Automation Guide Chapter 6: TabularData Object
© 2016 Forsk. All Rights Reserved.
Name
Description
Attributes
put_Filter
Filters the table data according to a filter criteria.
Type: String Access: Read/Write
get_Sort
Returns the sort order currently set on the table.
Type: String Access: Read/Write
put_Sort
Sorts the table data.
Type: String Access: Read/Write
GetOriginalValue
Returns an original field value.
get_RowStatus
Returns a row status.
Type: Integer 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
Atoll 3.3.2 Task Automation Guide Chapter 6: TabularData Object
AT332_TAG_E0
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 99.
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
Atoll 3.3.2 Task Automation Guide Chapter 6: TabularData Object
© 2016 Forsk. All Rights Reserved.
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 = 3.3.1 May also be a ChildFolder object associated with a transmitter.
Version: 3.1.0 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.
203
Atoll 3.3.2 Task Automation Guide Chapter 13: Document Commands
© 2016 Forsk. All Rights Reserved.
Version 2.7.0
Input Parameters Name
Description
Attributes
PROPAGATIONLOSSES
The PROPAGATIONLOSSES input parameter is used to specify whether repeaters donor side propagation losses will be calculated.
Version: 2.7.0 Type: Boolean
AZIMUTHSANDTILTS
The AZIMUTHSANDTILTS input parameter is used to specify whether repeaters donor side azimuths and tilts will be calculated.
Version: 2.7.0 Type: Boolean
GAINS
The GAINS input parameter is used to specify whether repeaters gains will be calculated.
Version: 2.7.0 Type: Boolean
TRANSMITTERFOLDER
A sub-folder of a transmitters folder, or a transmitters folder itself. Atoll >= 3.3.1 May also be a ChildFolder object associated with a transmitter.
Version: 3.1.0 Type: ChildFolder object
Default Parameters GetCommandDefaults for the command CALCULATEREPEATERS returns a PropertyContainer object with the properties: Name
Description
Attributes
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 Propagation 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 transmitters folder is performed.
13.16 CALCULATEREMOTEANTENNAS This command calculates propagation losses, azimuth, mechanical tilt, or gains for all remote antennas in a document transmitters folder. Version 2.7.0
Input Parameters
204
Name
Description
Attributes
PROPAGATIONLOSSES
The PROPAGATIONLOSSES input parameter is used to specify whether remote antennas donor side propagation losses will be calculated.
Version: 2.7.0 Type: Boolean
AZIMUTHSANDTILTS
The AZIMUTHSANDTILTS input parameter is used to specify whether remote antennas donor side azimuths and tilts will be calculated.
Version: 2.7.0 Type: Boolean
Atoll 3.3.2 Task Automation Guide Chapter 13: Document Commands
AT332_TAG_E0
Name
Description
Attributes
GAINS
The GAINS input parameter is used to specify whether remote antennas gains will be calculated.
Version: 2.7.0 Type: Boolean
TRANSMITTERFOLDER
A sub-folder of a transmitters folder, or a transmitters folder itself. Atoll >= 3.3.1 May also be a ChildFolder object associated with a transmitter.
Version: 3.1.0 Type: ChildFolder object
Default Parameters GetCommandDefaults for the command CALCULATEREMOTEANTENNAS returns a PropertyContainer object with the properties: 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). Name
Description
Attributes
SIMULATIONCONDITIONS
The SIMULATIONCONDITIONS PropertyContainer object used here has a subset of the SIMULATIONCONDITIONS property of a "Pilot Quality Analysis (Ec/Io)" Prediction ChildFolder Object. Therefore the SIMULATIONCONDITIONS property of a "Pilot Quality Analysis (Ec/ Io)" Prediction ChildFolder Object can be used directly, additional content in this PropertyContainer object will be ignored.
Version: 2.7.1 Type: PropertyContainer object Version: 2.7.1 Type: PropertyContainer object
CLUTTERCONDITIONS
RECORDSETCONDITIONS
The RECORDSETCONDITIONS PropertyContainer object used here has a subset of the RECORDSETCONDITIONS property of a Prediction ChildFolder Object. Therefore the RECORDSETCONDITIONS property of a Prediction ChildFolder Object can be used directly, additional content in this PropertyContainer object will be ignored.
Version: 2.7.1 Type: PropertyContainer object
205
Atoll 3.3.2 Task Automation Guide Chapter 13: Document Commands
© 2016 Forsk. All Rights Reserved.
The general parameters include: Name
Description
Attributes
RESOLUTION
The resolution in meter used to export the activeset analysis.
Version: 2.7.1 Type: Integer
DEPTH
The maximum number of cells in the activeset analysis to export on a given point.
Version: 2.7.1 Type: Integer
TEXTSEPARATOR
The ASCII code of the character used as the field delimiter in the exported text files.
Version: 2.7.1 Type: Integer
EXPORTFULLPATH
The full path of the file where the activeset is exported.
Version: 2.7.1 Type: String
Name
Description
Attributes
TERMINAL
The name of the terminal used to export the active set.
Version: 2.7.1 Type: String
MOBILITY
The name of the mobility used to export the active set.
Version: 2.7.1 Type: String
SERVICE
The name of the service used to export the active set.
Version: 2.7.1 Type: String
CARRIER
The carrier number used to export the active set.
Version: 2.7.1 Type: Integer
SIMULATIONCONDITIONS include:
CLUTTERCONDITIONS include: Name
Description
Attributes
SHADOWING
Whether to calculate shadowing margins related to the defined cell edge coverage probability and the standard deviation(s) per clutter class or not. When set to False, no shadowing effect is considered.
Version: 2.7.1 Type: Boolean
INDOORCOVERAGE
Whether to decrease the received signal level at the receiver of the indoor loss defined for the corresponding clutter class (clutter class properties).
Version: 2.7.1 Type: Boolean
EDGECOVERAGEPROBABILITY
A value between 0 and 100, expressing in percentage value the required coverage probability at the cell edge.
Version: 2.7.1 Type: Single
RECORDSETCONDITIONS include: Name
Description
Attributes
FILTER
"Filter" part of the recordset conditions, applied to the transmitters table.
Version: 2.7.1 Type: String
Default Parameters
206
Property Name
Default Value
SIMULATIONCONDITIONS
The same as the SIMULATIONCONDITIONS property of a new "Pilot Quality Analysis (Ec/Io)" prediction.
RECORDSETCONDITIONS
The same as the RECORDSETCONDITIONS property of a new "Pilot Quality Analysis (Ec/Io)" prediction.
Atoll 3.3.2 Task Automation Guide Chapter 13: Document Commands
AT332_TAG_E0
Property Name
Default Value
RESOLUTION
The same as the RESOLUTION property of a new "Pilot Quality Analysis (Ec/Io)" prediction.
DEPTH
3, ie by default the maximum number of cells of the activeset analysis is 3.
TEXTSEPARATOR
59, ie the ASCII code of the ’;’ character. Fields in the exported 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 c:\activeset-1.txt c:\activeset-2.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 separated 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
207
Atoll 3.3.2 Task Automation Guide Chapter 13: Document Commands
© 2016 Forsk. All Rights Reserved.
timestamp;16:15:01 18-July-2008 resolution;50 xmin;23200 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 Name
Description
Attributes
POINTS
The POINTS input parameter is used to define a set of points.
Version: 2.7.1 Type: Array of Integers
TRANSMITTERS
The TRANSMITTERS input parameter is used to define a set of transmitters.
Version: 2.7.1 Type: Array of Strings
STUDY
The STUDY input parameter is used to define the parameters used to calculate the Ec/I0 values. It is a study object contained in the Predictions folder of the Atoll document. The STUDY input parameter must be a study of type "Pilot Quality Analysis (Ec/I0)".
Version: 2.7.1 Type: ChildFolder object
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 transmitters 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 PropertyContainer object.
208
Atoll 3.3.2 Task Automation Guide Chapter 13: Document Commands
AT332_TAG_E0
Results Name
Description
Attributes
VALUES
The VALUES result is used to return Ec/I0 values.
Version: 2.7.1 Type: TabularData object
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. Column Name
Description
Attributes
TX_ID
A string holding a transmitter identifier.
Type: String
Pn
The Ec/I0 value on point number n from the transmitter identified by the field TX_ID.
Type: Single or Null
13.19 RUNALLCARRIERSALLOCATION Performs all carriers allocation on a TD-SCDMA network. Version 2.8.1
Input Parameters Name
Description
Attributes
TRANSMITTERFOLDER
A sub-folder of the transmitters folder, or the transmitters folder itself.
Version: 2.8.1 Type: ChildFolder object
CONFREQUENCYALLOCATION
A boolean value used to specify whether to perform Co-N frequency allocation (True) or Diff-N frequency allocation (False).
Version: 2.8.1 Type: Boolean
COMMITRESULTS
A boolean value used to specify whether the allocation results will be commited in the document (True), or not (False).
Version: 2.8.1 Type: Boolean
Default Parameters None. GetCommandDefaults for the command RUNALLCARRIERSALLOCATION returns an empty PropertyContainer object. Results Name
Description
Attributes
CARRIERS
The CARRIERS result is used to return carrier allocation information.
Version: 2.8.1 Type: TabularData object
The CARRIERS TabularData object has one record for each transmitter’s carrier allocation. Name
Description
Attributes
Transmitter
Type: String
Carriers
Type: Integer
Master Carrier
Type: Integer
209
Atoll 3.3.2 Task Automation Guide Chapter 13: Document Commands
© 2016 Forsk. All Rights Reserved.
13.20 RUNMASTERCARRIERALLOCATION Performs master carrier allocation on a TD-SCDMA network. Version 2.8.1
Input Parameters Name
Description
Attributes
TRANSMITTERFOLDER
A sub-folder of the transmitters folder, or the transmitters folder itself.
Version: 2.8.1 Type: ChildFolder object
DELETEEXISTINGALLOCATION
A boolean value used to specify whether to delete the existing allocation (True), or not (False).
Version: 2.8.1 Type: Boolean
COMMITRESULTS
A boolean value used to specify whether the allocation results will be commited in the document (True), or not (False).
Version: 2.8.1 Type: Boolean
Default Parameters None. GetCommandDefaults for the command RUNMASTERCARRIERALLOCATION returns an empty PropertyContainer object. Results Name
Description
Attributes
CARRIERS
The CARRIERS result is used to return carrier allocation information.
Version: 2.8.1 Type: TabularData object
The CARRIERS TabularData object has one record for each transmitter’s carrier allocation. Column Name
Description
Attributes
Transmitter
Type: String
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 interference 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.
210
Name
Description
Attributes
LINKS
Array containing the names of the links to be calculated. These include the links which are filtered, active, and inside the focus zone. This is the same list which is used by Atoll when running calculation on the Links folder.
Version: 2.6.1 Type: Array of Strings
Atoll 3.3.2 Task Automation Guide Chapter 13: Document Commands
AT332_TAG_E0
Name
Description
Attributes
INTERFERENCE
Defines which propagation model is to be used for interference. If true, recommendation ITU 452 is used. If false, the model defined in the links properties is used.
Version: 2.6.1 Type: Boolean
QUALITYMODEL
Defines which quality model is to be used for analysis. Valid values are: 0=ITU Recommendation 530-5; 1=ITU Recommendation 530-8; 2=ITU Recommendation 530-10; 3=Vigants Barnett method; 4=KQ Factor method;
Version: 2.6.1 Type: Integer
QUALITYOBJECTIVE0 QUALITYOBJECTIVE1 QUALITYOBJECTIVE2 QUALITYOBJECTIVE3
Defines the priority of objectives that Atoll must used to find the appropriate quality objective. "QualityObjective0" contains the objectives which are the higher-priority objectives. "QualityObjective3" contains the lowest-priority objectives. Each "QualityObjectiveX" is set to an interger: 0="As a function of Rate"; 1=ITU-T G821; 2=ITU-T G826; 3=Customized;
Version: 2.6.1 Type: Integer
AvailabilityObjective0 AvailabilityObjective1 AvailabilityObjective2 AvailabilityObjective3
Defines the priority of objectives that Atoll must used to find the appropriate availability objective. "AvailabilityObjective0" contains the objectives which are the higher-priority objectives. "Q AvailabilityObjective 3" contains the lowest-priority objectives. Each "AvailabilityObjectiveX" is set to an interger: 0="As a function of Rate"; 1=ITU-T G821; 2=ITU-T G826; 3=Customized;
Version: 2.6.1 Type: Integer
RainModel
Defines which rain model is to be used for analysis: 0=ITU Recommendation 530-5; 1=ITU Recommendation 530-8; 2=ITU Recommendation 530-10; 3=Crane method;
Version: 2.6.1 Type: Integer
RBER
Residual BER; used by Recommendation ITU 530-8 and above to calculate performance parameters. Typically in the range from 10-10 to 10-13 for the bit rates of 2 to 155 Mbit/s, respectively.
Version: 2.6.1 Type: Double
ALFA1
Used by Recommendation ITU 530-8 and above to calculate performance parameters. 10 to 30, number of errors per burst for the BER in the range from 10-3 to BERSES
Version: 2.6.1 Type: Integer
ALFA2
Used by Recommendation ITU 530-8 and above to calculate performance parameters. 1 to 10, number of errors per burst for the BER in the range from BERSES to RBER
Version: 2.6.1 Type: Integer
RefDelayM
Used by Recommendation ITU 530-8 and above to calculate prediction of outage in unprotected digital systems. RefDelayM is the reference delay (ns) used to obtain the signature for minimum phase.
Version: 2.6.1 Type: Single
RefDelayNM
Used by Recommendation ITU 530-8 and above to calculate prediction of outage in unprotected digital systems. RefDelayNM is the reference delay (ns) used to obtain the signature for non-minimum phase.
Version: 2.6.1 Type: Single
EquipPercent
This percent is used to calculate the availability objective which will be compared to the outage due to equipment failures. Its value is supposed to be between 0 and 100.
Version: 2.6.1 Type: Single
RainPercent
This percent is used to calculate the availability objective which will be compared to the availability outage. Its value is supposed to be between 0 and 100.
Version: 2.6.1 Type: Single
kMoy
Defines the value of the average earth curvature used in calculation.
Version: 2.6.1 Type: Single
kMin
Defines the value of the second earth curvature used to display the ellipsoid. (not used during link budgets nor interferences calculation).
Version: 2.6.1 Type: Single
UseAtpc
Option which defines if power must be reduced or not with the ATPC value.
Version: 2.6.1 Type: Boolean
211
Atoll 3.3.2 Task Automation Guide Chapter 13: Document Commands
212
© 2016 Forsk. All Rights Reserved.
Name
Description
Attributes
Rec530Simple
Defines which method must be used to calculate geoclimatic parameters (used for quality). For the simple one, Rec530Simple must be set to True.
Version: 2.6.1 Type: Boolean
IgnoreXPD
Boolean which tells if the calculation of fading due to XPD must be taken into account or not in the total result.
Version: 2.6.1 Type: Boolean
IgnorePR
Boolean which tells if the calculation of fading due to enhancements must be taken into account or not in the total result.
Version: 2.6.1 Type: Boolean
OneBER
Flag which defines if the calculation must be done for the BER defined in the links properties (OneBER = 0/False) or if the calculation must be done with the same BERs for all the links (OneBER = 1/True).
Version: 2.6.1 Type: Boolean
BER1
First value of BER which is used when OneBER = 1.
Version: 2.6.1 Type: Double
BER2
Second value of BER which is used when OneBER = 1. Note that this value is not used when running calculations with this API. Using the API means that calculations are only displayed with BER1.
Version: 2.6.1 Type: Double
Rec838
Defines which release of recommendation ITU-838 must be used: 0=Rec 838-1; 1=Rec 838-3;
Version: 2.6.1 Type: Double
CALC_LINK_PORTS
Defines the expected results: "all" means that all the ports of each link are calculated and displayed in the final result. "worst" means that the final result will display only the worst port. "selected" means that the final result will display the result for the port defined in the port parameter.
Version: 2.6.1 Type: String
CALC_WITH_NOI
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) Besides the interest of having results with or without interference, 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).
Version: 2.6.1 Type: Boolean
InterferenceDistanceMax
Defines the maximum distance (in meters) to search potential interferers.
Version: 2.6.1 Type: Double
InterferenceDropMin
Defines the threshold of drop margin (in dB) under which an interference level is not added to the total result.
Version: 2.6.1 Type: Double
InterferenceCalcGo
Defines if the A>>B way must be calculated and displayed or not in the final result. This option concerns not only interference calculation but also links budgets.
Version: 2.6.1 Type: Boolean
InterferenceCalcReturn
Defines if the B>>A way must be calculated and displayed or not in the final result. This option concerns not only interference calculation but also links budgets.
Version: 2.6.1 Type: Boolean
InterferenceCalcUplink
Defines if the uplink interference must be calculated and displayed or not in the final result.
Version: 2.6.1 Type: Boolean
InterferenceCalcDownlink
Defines if the downlink interference must be calculated and displayed or not in the final result.
Version: 2.6.1 Type: Boolean
InterferenceRainSurfCorrel ation
Value of the area (km2) which is used to calculate the correlation between two links.
Version: 2.6.1 Type: Single
Atoll 3.3.2 Task Automation Guide Chapter 13: Document Commands
AT332_TAG_E0
Name
Description
Attributes
InterferenceAutoWeight
Percent which defines if interferer level is more important or not that interfering effects. This percent is only used for semi-automatic channel allocation and has no influence when running calculation with this API.
Version: 2.6.1 Type: Integer
InterferenceUseAtpc
Option which defines if interferer power must be reduced or not with the ATPC value.
Version: 2.6.1 Type: Boolean
InterferenceWidth
Percent of the channels width which can interfere or be interfered.
Version: 2.6.1 Type: Integer
InterferenceOverShoot
Flag which defines how passive repeaters are taken into account when running interference: 0=interference through passive are not taken into account; 1=links with passive repeaters may also interfere through their own passive; 2=any signal can interfere through a repeater.;
Version: 2.6.1 Type: Integer
INTERF_DETAIL
Defines if results must contain details or not. "none" means no detail "uplink" means only for uplink results "downlink" means only for downlink results "both" means always. This parameter has no effect when running calculation with this API.
Version: 2.6.1 Type: String
COCHANNELONLY
When COCHANNELONLY is set to True, INTERFERENCEWIDTH is ignored.
Version: 2.8.1 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
AvailabilityObjective1
1
AvailabilityObjective2
2
AvailabilityObjective3
3
RainMod
1
RBER
1e-12
ALFA1
10
ALFA2
1
RefDelayM
6.3
RefDelayNM
6.3
EquipPercent
33
213
Atoll 3.3.2 Task Automation Guide Chapter 13: Document Commands
© 2016 Forsk. All Rights Reserved.
Name
Default Value
RainPercent
33
kMoy
1.33
kMin
NULL
UseAtpc
False
Rec530Simple
True
IgnoreXPD
True
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
214
Name
Description
Attributes
LINKNAME
Name (primary key) of the link whose results are given.
Version: 2.6.1 Type: String
BAND
Name (primary key) of the frequency band of the link.
Version: 2.6.1 Type: String
LENGTH
Length of the link calculated along the Great Circle (with latitude, longitude and heights). This value is displayed as read-only in the first page of links properties but is not saved in database.
Version: 2.6.1 Type: Single
WAY
Way of the link which is concerned with this result. "AB" means "go" (= Site A toward Site B) "BA" means "return" (= Site B toward Site A)
Version: 2.6.1 Type: String
Atoll 3.3.2 Task Automation Guide Chapter 13: Document Commands
AT332_TAG_E0
Name
Description
Attributes
SUBBAND
Name (primary key) of the subband of the link with the suffix "[-]" or "[+]" depending on the half subband of the link. "[-]" means lowest part "[+]" means highest part. Can be null if the link has manual frequencies.
Version: 2.6.1 Type: String
CHANNEL
The calculated channel number. If the link has manual frequency, channel number is "-1".
Version: 2.6.1 Type: String
POLAR
String which contains either "H" for horizontal polarization, either "V" for vertical polarization. This value can be determined by the links properties (if no ports are defined) or by the ports configuration if any.
Version: 2.6.1 Type: String
SITE_TX
Name (primary key) of the transmitting site of the link being calculated (site A is the way is "AB", site B if the way if "BA").
Version: 2.6.1 Type: String
ANT_TX
Name (primary key) of the transmitting antenna of the link. (antenna A is the way is "AB", antenna B if the way if "BA").
Version: 2.6.1 Type: String
HEIGHT_TX
Value of the height of transmitting antenna (in meters).
Version: 2.6.1 Type: Single
AZIMUTH_TX
Value of the azimuth of the transmitting antenna. (in degrees). This value is calculated, not displayed in the links properties, nor saved in database. It takes into account the antenna misalignment and the direction of the receiver. (latitude, longitude and height).
Version: 2.6.1 Type: Single
TILT_TX
Value of the tilt of the transmitting antenna. (in degrees). This value is calculated, not displayed in the links properties, nor saved in database. It takes into account the antenna misalignment and the direction of the receiver. (latitude, longitude and height).
Version: 2.6.1 Type: Single
ANTGAIN_TX
Value of the gain of the transmitting antenna (in dB). This value is displayed in the antenna properties.
Version: 2.6.1 Type: Single
SITE_RX
Name (primary key) of the receiving site of the link being calculated (site B is the way is "AB", site A if the way if "BA").
Version: 2.6.1 Type: String
ANT_RX
Name (primary key) of the receiving antenna of the link. (antenna B is the way is "AB", antenna A if the way if "BA").
Version: 2.6.1 Type: String
HEIGHT_RX
Value of the height of receiving antenna (in meters).
Version: 2.6.1 Type: Single
AZIMUTH_RX
Value of the azimuth of the receiving antenna. (in degrees). This value is calculated, not displayed in the links properties, nor saved in database. It takes into account the antenna misalignment and the direction of the receiver. (Latitude, longitude and height).
Version: 2.6.1 Type: Single
TILT_RX
Value of the tilt of the receiving antenna. (in degrees). This value is calculated, not displayed in the links properties, nor saved in database. It takes into account the antenna misalignment and the direction of the receiver. (Latitude, longitude and height).
Version: 2.6.1 Type: Single
ANTGAIN_RX
Value of the gain of the receiving antenna (in dB). This value is displayed in the antenna properties.
Version: 2.6.1 Type: Single
EQ_TX
Name (primary key) of the transmitting equipment. (equipment A is the way is "AB", equipment B if the way if "BA").
Version: 2.6.1 Type: String
POWER_NOM
Value of the nominal transmitted power, used if ATPC is not taken into account.
Version: 2.6.1 Type: Single
POWER_COORD
Value of the coordinate transmitted power, used if ATPC is taken into account.
Version: 2.6.1 Type: Single
215
Atoll 3.3.2 Task Automation Guide Chapter 13: Document Commands
216
© 2016 Forsk. All Rights Reserved.
Name
Description
Attributes
SYS_CFG
Value the system configuration of the equipment. String formatted as: "n+m" where n is an integer which corresponds to the main channels number, and "m" an interger which corresponds to the stad by channels number. Ex: "1+1", "2+0" …
Version: 2.6.1 Type: String
CAPA
Value the capacity of the equipment. String is formatted with the number of trunks (depending on the digital hierarchy) and the trunk name. Example: "E1" or "3 x E1" or "2 x STM-16" depending for if the number of trunks is more than one or not.
Version: 2.6.1 Type: String
TX_LOSS
Value of the total losses on the transmitter side: Shared losses, Connection losses, Shielding factor, port losses (filter + attenuation), wave guide losses.
Version: 2.6.1 Type: Single
FSL
Value of the free space loss calculated between transmitter and receiver.
Version: 2.6.1 Type: Single
LA
Value of the attenuation due to dry air absorption.
Version: 2.6.1 Type: Single
LV
Value of the attenuation due to vapor absorption.
Version: 2.6.1 Type: Single
LD
Value of the total diffraction through the profile between the transmitter and the receiver.
Version: 2.6.1 Type: Single
LVEG
Value of the vegetation loss along the profile.
Version: 2.6.1 Type: Single
LBS
Value of the tropospheric loss along the profile.
Version: 2.6.1 Type: Single
LTOT
Value of the total propagation loss along the profile. (Remember that vegetation loss is never added).
Version: 2.6.1 Type: Single
EQ_RX
Name (primary key) of the receiving equipment. (equipment B is the way is "AB", equipment A if the way if "BA").
Version: 2.6.1 Type: String
RX_LOSS
Value of the total losses on the receiver side: Shared losses, Connection losses, Shielding factor, port losses (filter + attenuation), wave guide losses.
Version: 2.6.1 Type: Single
RX_THRESOLD
Value of the receiver threshold (dBm) defined as the sensitivity of the receiver for the BER1 value.
Version: 2.6.1 Type: Single
DECOUPLING
Value of the total decoupling (dB) : losses due co-polar patterns of the requested polarization for transmitter and receiver antenna. (Generally null if antennas are aligned.)
Version: 2.6.1 Type: Single
XPD
Difference between the cross-polar value of the receiver antenna and its co-polar value (dB).
Version: 2.6.1 Type: Single
XPI
Difference between the cross-polar value of the transmitter antenna and its co-polar value (dB).
Version: 2.6.1 Type: Single
RX_LEVEL
Wanted signal level (dBm) Takes into account the transmitted power, transmitter and receiver losses, total propagation losses and decoupling.
Version: 2.6.1 Type: Single
FADE_MARGIN
Calculated fade margin (uniform margin) which takes into account the received signal level et the receiver threshold.
Version: 2.6.1 Type: String
PNS
Percent of outage due to uniform fadings.
Version: 2.6.1 Type: Single
Atoll 3.3.2 Task Automation Guide Chapter 13: Document Commands
AT332_TAG_E0
Name
Description
Attributes
PS
Percent of outage due to selective fadings.
Version: 2.6.1 Type: Single
pXPD
Percent of outage due to cross-polar discrimination fadings.
Version: 2.6.1 Type: Single
PT
Percent of outage which determined the quality of the link (i.e during clear air conditions).
Version: 2.6.1 Type: Single
SESR
Probability of SESR outage.
Version: 2.6.1 Type: Single
BBER
Probability of BBER outage.
Version: 2.6.1 Type: Single
ESR
Probability of ESR outage.
Version: 2.6.1 Type: Single
PR
Percent of fadings due to enhancements.
Version: 2.6.1 Type: Single
P0
Percent of multipath occurrence.
Version: 2.6.1 Type: Single
PP
Percent of fadings due to rain for the worst month.
Version: 2.6.1 Type: Single
PPA
Percent of fadings due to rain for an average year.
Version: 2.6.1 Type: Single
PXPD
Percent of rain fadings due to cross-polar discrimination.
Version: 2.6.1 Type: Single
PPT
Total percent of unavailability for an average year.
Version: 2.6.1 Type: Single
PFAILURES
Percent of fadings due to equipment failures.
Version: 2.6.1 Type: Single
RAIN_SESR
Probability of rain SESR outage.
Version: 2.6.1 Type: Single
RAIN_BBER
Probability of rain BBER outage.
Version: 2.6.1 Type: Single
RAIN_ESR
Probability of Rain ESR outage.
Version: 2.6.1 Type: Single
PASSIVE_GAIN
Total gain (dB) of the passive repeaters.
Version: 2.6.1 Type: Single
AFF_RAIN
Total rain attenuation (dB) along the path.
Version: 2.6.1 Type: Single
SEC_M_Q
Total time of outage during clear-air for the worst month. Value is formatted is unit (hour, mn, sec). Ex: "6 sec", "19mn 27 sec".
Version: 2.6.1 Type: String
OBJ_M_Q
Quality objective during clear-air for the worst month. Value is formatted is unit (hour, mn, sec)
Version: 2.6.1 Type: String
SEC_Y_Q
Total time of outage during clear-air for an average year month. Value is formatted is unit (hour, mn, sec)
Version: 2.6.1 Type: String
SEC_M_RAIN
Total time of outage during rain condition for the worst month. Value is formatted is unit (hour, mn, sec). Ex: "6 sec", "19mn 27 sec"
Version: 2.6.1 Type: String
217
Atoll 3.3.2 Task Automation Guide Chapter 13: Document Commands
© 2016 Forsk. All Rights Reserved.
Name
Description
Attributes
OBJ_M_RAIN
Quality objective during rain condition for the worst month. Value is formatted is unit (hour, mn, sec)
Version: 2.6.1 Type: String
SEC_Y_RAIN
Total time of outage during rain condition for an average year month. Value is formatted is unit (hour, mn, sec)
Version: 2.6.1 Type: String
STATUS_Q
Status of the link for quality. Takes into account each probability and corresponding objective for SESR, ESR and BBER, according to the equipment hierarchy too. The status can have following values: "OK"; "Not Respected"; "Not Calculated"; "Not Defined";
Version: 2.6.1 Type: String
STATUS_A
Status of the link for avalability. Takes into account each probability and corresponding objective for SESR, ESR and BBER, according to the equipment hierarchy too. The status can have following values: "OK"; "Not Respected"; "Not Calculated"; "Not Defined";
Version: 2.6.1 Type: String
CFM
Value of the composite fade margin (dB) which takes into account all the margins; Corresponds to the SESR probability.
Version: 2.6.1 Type: String
REQ_CFM_Q
Value of the composite fade margin (dB) calculated from the quality objectives set for the link.
Version: 2.6.1 Type: String
REQ_TFM
Value of the uniform margin (dB) calculated from the quality objectives set for the link. Corresponds to the non-selective outage probability.
Version: 2.6.1 Type: String
REQ_CFM_A
Value of the composite fade margin (dB) calculated from the availability set for the link.
Version: 2.6.1 Type: String
TX_PORT
Transmission port.
Version: 3.1.0 Type: String
RX_PORT
Reception port.
Version: 3.1.0 Type: String
Name
Description
Attributes
LINKNAME
Name (primary key) of the link whose results are given.
Version: 2.6.1 Type: String
WAY
Way of the link which is concerned with this result. "AB" means "go" (= Site A toward Site B) "BA" means "return" (= Site B toward Site A)
Version: 2.6.1 Type: String
CHANNEL_IRX
Calculated interfered channel number. If the link has manual frequency, channel number is "-1".
Version: 2.6.1 Type: String
SUBBAND
Name (primary key) of the subband of the link with the suffixe "[-]" or "[+]" depending on the half subband of the link. "[-]" means lowest part "[+]" means highest part. Can be null if the link has manual frequencies.
Version: 2.6.1 Type: String
C
Wanted signal level (dBm) Takes into account the transmitted power, transmitter and receiver losses, total propagation losses and decoupling. Same value as RX_LEVEL when running analysis without interference.
Version: 2.6.1 Type: Single
FLAT_MARGIN
Value of the uniform margin (dB) calculated from the wanted signal level and the receiver threshold.
Version: 2.6.1 Type: Single
Analysis Results With Interference Calculation
218
Atoll 3.3.2 Task Automation Guide Chapter 13: Document Commands
AT332_TAG_E0
Name
Description
Attributes
I
Aggregation of all the interferences (dBm) received from other links and receiver thermal noise (FKTB).
Version: 2.6.1 Type: Single
MARGIN_REDUCT
Value of the differences between margin without interference and margin with interferences.
Version: 2.6.1 Type: String
C_OVER_I
Value of C/I (dB) where C is the wanted signal level and I the total interference level.
Version: 2.6.1 Type: Single
IRAIN
Value of the total interference level during rain condition which can be different from the "general" interference level depending on correlation between links.
Version: 2.6.1 Type: Single
MARGIN_REDUCT_RAIN
Value of the differences between margin without rain interference and margin with interferences.
Version: 2.6.1 Type: String
EFF_MARGIN
Value of the margin calculated from the receiver threshold and the received level when interference are taken into account.
Version: 2.6.1 Type: Single
BER
Value of the BER with which the current analysis is run.
Version: 2.6.1 Type: Single
QUALITY
Percent of outage which determined the quality of the link. (i.e during clear air conditions, and with interference).
Version: 2.6.1 Type: Single
AVAIL
Percent of fadings due to rain for the worst month, when interference are taken into account.
Version: 2.6.1 Type: Single
SEC_M_Q
Total time of outage with interference during clear-air for the worst month. Value is formatted is unit (hour, mn, sec). Ex: "6 sec", "19mn 27 sec"
Version: 2.6.1 Type: String
OBJ_M_Q
Quality objective during clear-air for the worst month. Value is formatted is unit (hour, mn, sec)
Version: 2.6.1 Type: String
SEC_Y_Q
Total time of outage with interference during clear-air for an average year month. Value is formatted is unit (hour, mn, sec)
Version: 2.6.1 Type: String
SEC_M_RAIN
Total time of outage with interference during rain condition for the worst month. Value is formatted is unit (hour, mn, sec). Ex: "6 sec", "19mn 27 sec"
Version: 2.6.1 Type: String
OBJ_M_RAIN
Quality objective during rain condition for the worst month. Value is formatted is unit (hour, mn, sec)
Version: 2.6.1 Type: String
SEC_Y_RAIN
Total time of outage with interference during rain condition for an average year month. Value is formatted is unit (hour, mn, sec)
Version: 2.6.1 Type: String
STATUS_Q
Status of the link for quality. Takes into account each probability and corresponding objective for SESR, ESR and BBER, according to the equipment hierarchy too. The status can have following values: "OK"; "Not Respected"; "Not Calculated"; "Not Defined";
Version: 2.6.1 Type: String
STATUS_A
Status of the link for avalability. Takes into account each probability and corresponding objective for SESR, ESR and BBER, according to the equipment hierarchy too. The status can have following values: "OK"; "Not Respected"; "Not Calculated"; "Not Defined";
Version: 2.6.1 Type: String
PORT_IRX
Interferenced Port
Version: 3.1.0 Type: Single
219
Atoll 3.3.2 Task Automation Guide Chapter 13: Document Commands
© 2016 Forsk. All Rights Reserved.
13.22 EXPORTMAPWINDOW Exports a region of the map window as an image. Version 3.1.0
Input Parameters Name
Description
Attributes
REGION
The region to export. Available values are: 0: The region to export is specified by SELECTIONXMIN, SELECTIONXMAX, SELECTIONYMIN, and SELECTIONYMAX input parameters. 1:The region to export is the geographic export zone. 2:The region to export is the printing zone.
Version: 3.1.0 Type: Integer
SELECTIONXMIN
The west coordinate of the region to export, expressed in meter in the projection coordinate system of the document. Only used when the REGION input parameter is set to 0.
Version: 3.1.0 Type: Double
SELECTIONXMAX
The east coordinate of the region to export, expressed in meter in the projection coordinate system of the document. Only used when the REGION input parameter is set to 0.
Version: 3.1.0 Type: Double
SELECTIONYMIN
The south coordinate of the region to export, expressed in meter in the projection coordinate system of the document. Only used when the REGION input parameter is set to 0.
Version: 3.1.0 Type: Double
SELECTIONYMAX
The north coordinate of the region to export, expressed in meter in the projection coordinate system of the document. Only used when the REGION input parameter is set to 0.
Version: 3.1.0 Type: Double
PATH
The absolute path of the file where the map window image is exported.
Version: 3.1.0 Type: String
FORMAT
The file format used to export the map window image. Available values are: BMP : BMP file format PNG : PNG file format ARCVIEWGRIDASCII : ArcView grid file format TIF : TIFF file format BIL : BIL file format JP2 : JPEG 2000 file format
Version: 3.1.0 Type: String
PIXELSIZE
Pixel size (meters), used to export the map window image. When the value specified is zero (0), then SCALE and RESOLUTION input parameters are used to determine the pixel size.
Version: 2.8.1 Type: Integer
SCALE
Scale of the map window used to export the map window image. Only used when the PIXELSIZE input parameter is set to 0.
Version: 3.1.0 Type: Integer
RESOLUTION
Resolution of the map window used to export the map window image, in dot per inch. Only used when the PIXELSIZE input parameter is set to 0.
Version: 3.1.0 Type: Integer
INCLUDERULERS
Boolean value used to specify whether to include rulers in the exported image, or not. Only used when the PIXELSIZE input parameter is set to 0.
Version: 3.1.0 Type: Boolean
INCLUDESCALE
Boolean value used to specify whether to include the scale in the exported image, or not.
Version: 3.2.1 Type: Boolean
Default Parameters None. GetCommandDefaults for the command EXPORTMAPWINDOW returns an empty PropertyContainer object.
220
Atoll 3.3.2 Task Automation Guide Chapter 13: Document Commands
AT332_TAG_E0
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. Version 3.1.0
Input Parameters Name
Description
Attributes
PATH
The absolute path of the planet data file to import.
Version: 3.1.0 Type: String
EMBED
Whether to embed data, or not.
Version: 3.1.0 Type: Boolean
TYPE
The type of the planet data file to import. Available values are: 0 : Digital terrain model 1: Digital height model 2 : Clutter classes 3 : Environment based traffic map 4: Planet vectors 5: Planet text data 6: Images 7: Antennas 8: Microwave antennas
Version: 3.1.0 Type: Integer
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 Name
Description
Attributes
LINKNAME
Name of the link.
Version: 3.1.0 Type: String
LINKTYPE
Link type. Available values are: 0 : A -> B 1 : B ->A
Version: 3.1.0 Type: Integer
PICTUREWIDTH
Picture width, in pixels.
Version: 3.1.0 Type: Integer
221
Atoll 3.3.2 Task Automation Guide Chapter 13: Document Commands
© 2016 Forsk. All Rights Reserved.
Name
Description
Attributes
PICTUREHEIGHT
Picture height, in pixels.
Version: 3.1.0 Type: Integer
FILEPATH
The absolute path of the Windows bitmap file where the link analysis picture is exported.
Version: 3.1.0 Type: String
Default Parameters None.GetCommandDefaults for the command EXPORTMWLINKANALYSISPROFILEPICTURE returns an empty PropertyContainer 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 Name
Description
Attributes
TECHNOLOGY
For single RAT documents, this parameter is not used. For multi-RAT parameter, a string used to specify the technology. Available values are: "UMTS", "LTE"
Version: 3.1.0 Type: String
Default Parameters None. GetCommandDefaults for the command GETPOWERMODE returns an empty PropertyContainer object. Results Name
Description
Attributes
POWERMODE
The power mode. Available values are: 0 : default 1 : EIRP is calculated using the max power
Version: 3.1.0 Type: Integer
13.26 SETPOWERMODE Sets the document power mode. This command is only available for UMTS or LTE technologies. Version 3.1.0
222
Atoll 3.3.2 Task Automation Guide Chapter 13: Document Commands
AT332_TAG_E0
Input Parameters Name
Description
Attributes
TECHNOLOGY
For single RAT documents, this parameter is not used. For multi-RAT parameter, a string used to specify the technology. Available values are: "UMTS", "LTE"
Version: 3.1.0 Type: String
POWERMODE
The power mode. Available values are: 0 : default 1 : EIRP is calculated using the max power
Version: 3.1.0 Type: Integer
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 Name
Description
Attributes
CHILDFOLDER
The CHILDFOLDER input parameter is used to specify a vector data table. The ChildFolder object specified must support the VECTORDATA property.
Version: 3.1.1 Type: ChildFolder object
NAME
The NAME input parameter is used to specify the name of the new column to add to the vector data table. The value is case insensitive and must not include spacesand dot characters.
Version: 3.1.1 Type: String
LEGEND
The LEGEND input parameter is used to specify the display name of the new column to add to the vector data table. The value is case sensitive and space characters are allowed.
Version: 3.1.1 Type: String
TYPE
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 3=Single 4=Double 5=True/False 6=Date/Time 7=Currency
Version: 3.1.1 Type: Integer
SIZE
The SIZE input parameter is used to specify the size, in bytes, for a column of type 0 (Text). The SIZE input parameter is specific to the text data type.
Version: 3.1.1 Type: Integer
223
Atoll 3.3.2 Task Automation Guide Chapter 13: Document Commands
© 2016 Forsk. All Rights Reserved.
Name
Description
Attributes
DEFAULT
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, when the column value is not set explicitly. When the DEFAULT input parameter is not specified, the default value for the new column is Null (VT_NULL). The type of the DEFAULT input parameter value must match the data type of the new column, as specified by the TYPE input parameter.
Version: 3.1.1 Type: Null, String, Integer, Boolean, Single, Double, Currency, or Date
CHOICELIST
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 column value is not restricted to the 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.
Version: 3.1.1 Type: Array of Strings
Default Parameters None. 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 Name
Description
Attributes
DIRECTION
The DIRECTION input parameter is used to specify whether to load or save the print setup configuration. To load the print setup configuration, specify the value 1. To save the print setup configuration, specify the value 0.
Version: 3.1.1 Type: Integer
PRINTERNAME
The PRINTERNAME input parameter is used to specify the default printer to use in the print setup configuration. This input parameter is not used when saving the print setup configuration.
Version: 3.1.1 Type: String
CFGPATH
When loading the print setup configuration, the CFGPATH input parameter is used to specify the file used to load the print setup configuration. When saving the print setup configuration, the CFGPATH input parameter is used to specify the file used to save the print setup configuration.
Version: 3.1.1 Type: String
Default Parameters None.
224
Atoll 3.3.2 Task Automation Guide Chapter 13: Document Commands
AT332_TAG_E0
Results Name
Description
Attributes
PRINTERNAME
The PRINTERNAME output parameter is used to return the default printer used int the print setup configuration file. .
Version: 3.1.1 Type: String
13.29 CALCULATEPATHLOSS Performs pathloss matrix calculation on a transmitter folder. Version 3.2.0
Input Parameters Name
Description
Attributes
TRANSMITTERFOLDER
A sub-folder of the transmitters folder, or the transmitters folder itself.
Version: 2.6.1 Type: ChildFolder object
FORCECALCULATION
When True, the calculation is forced even for transmitters having available valid results. When False, the calculation is made only for transmitters having unavailable or invalid results.
Version: 3.2.0 Type: Boolean
BLOCKING
The boolean value used to specify whether the calculations will occur in the background (False), or if the method should wait for the calculations to finish before returning (True).
Version: 3.2.0 Type: Boolean
FILTERED
When False, the calculation is made for all active transmitters in the transmitter folder. When True, only filtered transmitters are calculated
Version: 3.2.0 Type: Boolean
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 Name
Description
Attributes
EXPORTPATH
Full path to the folder where link reports are exported.
Version: 2.6.1 Type: String
TEMPLATEFILEPATH
Full path to the custom template used to perform the export.
Version: 3.2.0 Type: String
LINKSFOLDER
The microwave links folder containing links to export to the EXPORTPATH folder, using the TEMPLATEFILEPATH custom template.
Version: 3.2.0 Type: ChildFolder object
225
Atoll 3.3.2 Task Automation Guide Chapter 13: Document Commands
© 2016 Forsk. All Rights Reserved.
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 Name
IGNOREALLCONFLICTS
Description
Attributes
A boolean used to specify whether to ignore all conflicts when archiving.
Version: 3.2.1 C++ Type: VT_VARIANT of type VT_BOOL VBScript Type: Boolean
Default Parameters None. GetCommandDefaults on IDocument4 interface for the command ARCHIVETODATABASE returns an empty PropertyContainer object. Results Name
Description
Attributes
ARCHIVESTATUS
The archive operation status. Available values are: 0: The archive operation has succeeded. 1: The archive operation has been interrupted because of conflicts.
Version: 3.2.1 C++ Type: VT_VARIANT of type VT_I4 VBScript Type: Integer
13.32 MWCalculateProfiles Calculates Microwave profile files. Version 3.3.0
Input Parameters
226
Name
Description
Attributes
LINKS
Array containing the names of the links to be calculated. These include the links which are filtered, active, and inside the focus zone. This is the same list which is used by Atoll when running calculation on the Links folder. If not set, this defaults to the name of filtered links whose all sites are in the computation zone. When there is no computation zone, this defaults to all filtered links.
Version: 3.3.0 Type: Array of Strings
INTERFERENCEDISTANCEMAX
Defines the maximum distance (in meters) to search for potential interferers. If not set, the default value is 50000.
Version: 3.3.0 Type: Double
Atoll 3.3.2 Task Automation Guide Chapter 13: Document Commands
AT332_TAG_E0
Name
Description
Attributes
PRIVATESTORAGE
Path to the profile files folder. If not set, the default value is the one set in the Atoll document.
Version: 3.3.0 Type: String
Default Parameters None. GetCommandDefaults for the command MWCalculateProfiles an empty PropertyContainer object.
13.33 PURGEPATHLOSSFOLDERS Deletes orphan path loss matrices files (.los files) in the private path losses folders of the document. An orphan path loss file is a path loss file for which there is no corresponding transmitter in the document. Version 3.3.1 Input Parameters None Default Parameters None. GetCommandDefaults on IDocument4 interface for the command PURGEPATHLOSSFOLDERS returns an empty PropertyContainer object. Results Name
Description
DELETEDFILES
The list of deleted files. Each file is specified using its full path name.
Attributes Version: 3.3.1 Array of variants, with variants of type String
227
Atoll 3.3.2 Task Automation Guide Chapter 13: Document Commands
228
© 2016 Forsk. All Rights Reserved.
Chapter 14 Enumerations, Structures, and Interfaces
Atoll 3.3.2 Task Automation Guide ©2016 Forsk. All Rights Reserved
230
Atoll 3.3.2 Task Automation Guide Chapter 14: Enumerations
AT332_TAG_E0
14 Enumerations 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 the FSKGIS type library. All of them are prefixed with fg.
14.1.1 Atoll Type Library Enumerations 14.1.1.1 AtoSaveStatus Constant
Value
Description
atoSaveSucceeded
0
Document has been successfully saved.
atoSaveCanceled
1
Changes in the document has been cancelled by the user.
Constant
Value
Description
atoSaveNo
0
Document is closed without being saved.
atoSaveYes
1
Document is saved before being closed.
atoSavePrompt
2
The user is prompted whether the document must be saved before being closed.
Constant
Value
Description
atoCancelChanges
0
All changes are cancelled before the document is refreshed from the database.
atoSkipChanges
1
Only refreshes data that have not been modified.
Constant
Value
Description
atoArchiveSaveSucceeded
0
Archiving has succeeded without conflicts.
atoArchiveCanceled
1
Archiving has been cancelled, either by the user or because conflicts occurred.
Constant
Value
Description
atoMaximized
0
Maximized (enlarged to maximum size).
atoNormal
1
Normal (Default).
atoMinimized
2
Minimized (minimized to an icon in the task bar).
14.1.1.2 AtoSaveChanges
14.1.1.3 AtoRefreshPriority
14.1.1.4 AtoArchiveStatus
14.1.1.5 AtoWindowStatus
231
Atoll 3.3.2 Task Automation Guide Chapter 14: Enumerations
© 2016 Forsk. All Rights Reserved.
14.1.1.6 AtoLogType Constant
Value
Description
atoInfo
0
Information.
atoError
1
Error.
atoWarning
2
Warning.
Constant
Value
Description
atoEQ
0
(Equal) The first value equal to searchVal is searched for.
atoLT
1
(Strictly Lower Than) The first value less than searchVal is searched for.
atoLE
2
(Lower or Equal) The first value less than or equal to searchVal is searched for.
atoGE
3
(Greater or Equal) The first value greater than or equal to searchVal is searched for.
atoGT
4
(Strictly Greater Than) The first value greater than searchVal is searched for.
atoNE
5
(Not Equal) The first value not equal to searchVal is searched for.
Constant
Value
Description
atoDbm
0
Transmission unit is dBm.
atoWatt
1
Transmission unit is Watt.
atoKWatt
2
Transmission unit is kWatt.
Constant
Value
Description
atoDbmRx
0
Reception unit is dBm.
atoDbMicroVolt
1
Reception unit is dBV.
atoDbMicroVoltMeter
2
Reception unit is dBV/meter.
Constant
Value
Description
atoM
0
Distance unit is meter.
atoKm
1
Distance unit is kilometer.
atoMiles
2
Distance unit is miles.
14.1.1.7 AtoCompareOp
14.1.1.8 AtoTransmissionUnit
14.1.1.9 AtoReceptionUnit
14.1.1.10 AtoDistanceUnit
232
Atoll 3.3.2 Task Automation Guide Chapter 14: Enumerations
AT332_TAG_E0
14.1.1.11 AtoRadiatedPowerUnit Constant
Value
Description
atoRadiatedPowerEIRP
0
Radiated power is EIRP.
atoRadiatedPowerERP
1
Radiated power is ERP.
Constant
Value
Description
atoAntennaGainDbi
0
Antenna gain unit is dBi.
atoAntennaGainDbd
1
Antenna gain unit is dBd.
Constant
Value
Description
atoHeightOffsetM
0
Height offset unit is meter.
atoHeightOffsetFeet
1
Height offset unit is feet.
Constant
Value
Description
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.12 AtoAntennaGainUnit
14.1.1.13 AtoHeightOffsetUnit
14.1.1.14 AtoRootType
14.1.1.15 AtoRowFilter Constants to filter only modified, added, or deleted rows. Constant
Value
Description
atoRowFilterNone
0
No filter.
atoRowFilterModifiedOrNew
1
Filter to retain only modified or new rows.
atoRowFilterDeleted
2
Filter to retain only deleted rows.
Constant
Value
Description
atoRowStatusNew
1
Row has been added.
atoRowStatusModified
2
Row has been modified.
atoRowStatusDeleted
4
Row has been deleted.
atoRowStatusUnmodified
8
Row is unmodified.
14.1.1.16 AtoRowStatus All possible row statuses.
233
Atoll 3.3.2 Task Automation Guide Chapter 14: Enumerations
© 2016 Forsk. All Rights Reserved.
14.1.1.17 AtoTemperatureUnit Constant
Value
Description
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 Constant
Value
Description
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.
Constant
Value
Description
fgUndefinedProjection
0
Value when nothing has been defined.
fgNoProjection
1
This system has no projection method.
fgLambertConfConic1SP
2
Lambert Conformal Conic 1SP.
fgLambertConfConic2SP
3
Lambert Conformal Conic 2SP.
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.
14.1.2.2 ProjectionMethod
234
Atoll 3.3.2 Task Automation Guide Chapter 14: Enumerations
AT332_TAG_E0
Constant
Value
Description
fgSwissObliqueCylindrical
12
Swiss Oblique Cylindrical.
fgObliqueMercator
13
Oblique Mercator.
fgUTMProjection
14
UTM Projection.
Constant
Value
Description
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.
fgAngleFromRectfifiedToSkewed Grid
6
14.1.2.3 ProjParameterIndices
235
• Head Office 7 rue des Briquetiers 31700 Blagnac, France Tel: +33 562 747 210 Fax: +33 562 747 211
AT332_TAG_E0
• US Office
• China Office
200 South Wacker Drive – Suite 3100 Chicago, IL 60606, USA Tel: +1 312 674 4800 Fax: +1 312 674 4847
Suite 302, 3/F, West Tower, Jiadu Commercial Building, No. 66 Jianzhong Road, Tianhe Hi-Tech Industrial Zone, Guangzhou, 510665, P. R. of China Tel: +86 20 8553 8938 Fax: +86 20 8553 8285
www.forsk.com
November 2016
