Atoll 3.3.2 Task Automation Guide

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


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


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


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


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


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


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


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


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


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


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


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


12


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



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


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



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


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



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


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



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


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 WSH used to run the script




You need to explicitly use 32-bit or 64-bit Windows Script Host on machines where both 32-bit Atoll and 64-bit Atoll are installed.

25


26


Chapter 2 Object Model


28

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


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


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.


get_Active

Returns whether the Atoll window is active or not.

Type: Boolean Access: Read/Write

put_Active

Sets the Atoll window active.


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.


get_Path

Returns the path of the executable.


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.


put_StatusBar

Sets the status bar text of the Atoll application.

Type: String Access: Write

get_Visible

Returns the application visible state.


put_Visible

Sets the application visible state.


get_Version

Returns the application version.


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.


GetOption

Returns an option read from the Atoll initialisation file.

33



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


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



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


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



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


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



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


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



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,


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



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


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



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


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


48


Chapter 4 Documents Object


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.


get_Application

Returns the Atoll application object.


get_Parent

Returns the Atoll application object.


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



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


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



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


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


56


Chapter 5 Document Object


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.


get_Parent

Returns the Atoll Documents collection.


get_FullName

Returns the document full path.


get_Name

Returns the document file name without the extension.


get_Path

Returns the document path.


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.


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.


get_CoordSystemDisplay

Returns the display coordinate system of a document.


putref_CoordSystemDisplay

Sets the display coordinate system of a document.


get_CoordSystemInternal

Returns the internal coordinate system of a document.

Type: CoordSystem object Access: Read

get_TransmissionUnit

Returns the transmission power unit.


put_TransmissionUnit

Sets the transmission power unit.


get_ReceptionUnit

Returns the signal level reception unit.


put_ReceptionUnit

Sets the signal level reception unit.


get_DistanceUnit

Returns the display distance unit.


59


60


Name

Description

Attributes

put_DistanceUnit

Sets the display distance unit.


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.


put_RadiatedPowerUnit

Sets the current radiated power unit.


get_AntennaGainUnit

Returns the current antenna gain unit.


put_AntennaGainUnit

Sets the current antenna gain unit.


get_HeightOffsetUnit

Returns the current height offset unit.


put_HeightOffsetUnit

Sets the current height offset unit.


get_DatabaseConnectionString

Returns the database connection string.


HasRunningTask

Returns true when there is some calculation in progress.


RunEx

Starts calculations.

get_DatabaseSchemaString

Returns the database schema string.



AT332_TAG_E0

Name

Description

Attributes

get_DisplayApplicationDialogues

Returns true when some methods on some Atoll interfaces may display some dialogue boxes.


put_DisplayApplicationDialogues

Returns true when some methods on some Atoll interfaces may display some dialogue boxes.


PutDatabaseSchemaString

Sets the database schema string.


PutDatabaseConnectionString

Sets the database connection string.


ChangeDatabaseConnection

Changes the database connection string.


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



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


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



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


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



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


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



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


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



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


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



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


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



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


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



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


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


78


Chapter 6 TabularData Object


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.


get_RowCount

Returns the number of rows of the TabularData Object


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.


get_CanEdit

Checks if rows can be modified.


get_CanAddNew

Checks if rows can be added.


get_CanFilterSort

Checks if rows can be filtered or sorted.


get_Filter

Returns the filter currently set on the table.


81



Name

Description

Attributes

put_Filter

Filters the table data according to a filter criteria.


get_Sort

Returns the sort order currently set on the table.


put_Sort

Sorts the table data.


GetOriginalValue

Returns an original field value.

get_RowStatus

Returns a row status.


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


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



Don’t forget to call this method before a call to SetValue and to call Update to commit the changes in the row.

6.5 AddNew Adds a new empty row to the TabularData Object. The row added is put into edition mode. HRESULT AddNew();

Don’t forget to call this method before a call to SetValue and to call Update to actually add the new row.

6.6 Update Commits a row changes and puts the row from edition mode to normal mode. HRESULT Update(long *piRow); Parameters [out] piRow: The long integer pointer used to return the number of the row that was in edition mode. If the method Edit started the editing, the same iRow as in Edit is returned. If it was AddNew method, the number is the row number where the new record has been added. Remarks At one point in time, only one record can be put into edition mode. This method must be called once after each Edit and AddNew. Editing another record without updating the previous one will throw an error. Edit/Update cannot be mixed up for different records, neither can be AddNew/Update.

6.7 Delete Deletes a record. HRESULT Delete(long iRow); Parameters [in] iRow: The long integer used to specify the row number of the record to delete. Remarks A valid iRow number is any integer, such that 0 < iRow <= RowCount. Deletion can fail if the record to delete is related to another one. For instance an antenna from the table "ANTENNAS" cannot be deleted if it is being used by a transmitter from the table "TRANSMITTERS". Even if the record deletion doesn’t break integrity relations between tables, deleting a record may involve updating other tables or records. For instance, be careful when using this method with the "TRANSMITTERS" table and the "TRXs" table. If you delete one TRX, you want to edit the "TRANSMITTERS" table in order to update the field "NUM_TRX".

6.8 GetValue Returns a value of a column for a given row.

84


AT332_TAG_E0

HRESULT GetValue(long iRow, const VARIANT iCol, VARIANT *pVal); Parameters [in] iRow: The long integer used to specify the row number. [in] iCol: The VARIANT used to specify a column. When iCol is of type VT_I4, iCol is interpreted as a column number. When iCol is of type VT_BSTR, iCol is interpreted as a column name. [out] pVal: Address of the VARIANT used to return the column value. Remarks A valid iRow number is any integer, such that 0< iRow<= RowCount. A valid iCol is either an integer such that 0< iCol <= ColumnCount or a string containing the name of an existing column. The column names are not case sensitive. You should never assume that the type of the returned VARIANT is the one you expect. For instance, a VARIANT of type VT_NULL may be returned when the value of the column is the "Null" value. You should explicitly convert the returned VARIANT to the type you expect and handle conversion errors. When using a TabularData Object to access database tables, please refer to the Atoll Administrator Manual for the available column names, types, units, and to check if the column specification allows for "Null" values. For site coordinates values, please refer to the Atoll Technical Reference Guide for coordinate systems and units. Site coordinates are expressed in the internal coordinate system of the Atoll document. Example Set sites = app.ActiveDocument.GetRecords(“Sites”) For i = 1 To sites.ColumnCount colName = sites.GetValue(0, i) Next

6.9 SetValue Sets the value of a column for the row being edited or added. HRESULT SetValue(const VARIANT iCol, const VARIANT newVal); Parameters [in] iCol: The VARIANT used to specify a column. [in] newVal: The VARIANT used to specify the column value. Remarks A valid iCol is either an integer such that 0 < iCol <= ColumnCount or a string containing the name of an existing column. The column names are not case sensitive. You must have previously called Edit or AddNew to specify the row to edit before writing the column value.If this method is used for a large number of records, it is recommended to get the column numbers beforehand and then to use the SetValue method with this number and not with a VARIANT of type VT_BSTR. This will run faster. To get the column number, you can search the row number 0 for the field name you want to use. Example This example increments all the TXLOSSES of all the transmitters in the active document by 1 dB. Dim transmitters Dim doc

85


Dim i Dim txLosses Set doc = app.ActiveDocument Set transmitters = doc.GetRecords(“Transmitters”) For i = 1 To transmitters.RowCount txLosses = transmitters.GetValue(i, “LOSSES”) transmitters.Edit(i) transmitters.SetValue(“LOSSES”, txLosses + 1) transmitters.Update Next Instead, we could have used: For i = 1 To transmitters.RowCount txLosses = transmitters.GetValue(i, 12) transmitters.Edit(i) transmitters.SetValue(12, txLosses + 1) transmitters.Update Next

Updating the main contour of the focus zone: Public Sub WriteZone() Set doc = ActiveDocument Set zones = doc.GetRecords("Zones", true) row = zones.Find(0, "NAME", atoEQ, "FocusZone") Dim pts(3,1) pts(0,0) = 555000 pts(0,1) = 2188000 pts(1,0) = 600000 pts(1,1) = 2188000 pts(2,0) = 600000 pts(2,1) = 2140000 pts(3,0) = 555000 pts(3,1) = 2140000

86



AT332_TAG_E0

zones.Edit row zones.SetValue "POINTS", pts zones.Update End Sub

6.10 GetPrimaryKey Returns the value of the primary key for a given row number. HRESULT GetPrimaryKey(long iRow, VARIANT* pVal); Parameters [in] iRow: The row number. [out] pVal: Address of the VARIANT used to return the primary key. Remarks A valid iRow number is an integer whose value is greater than zero or equal to zero and lower than or equal to the row count of the TabularData object. Most of TabularData objects have a primary key. If no primary key is defined, the value of the column RECORD_ID for the row iRow is returned. When the TabularData object primary key is made of several columns, the type of the variant returned is a one dimension VARIANT array, of type VT_ARRAY|VT_VARIANT, and VARIANT array values are the values of the columns defining the primary key. Otherwise, the VARIANT returned is the value of the column used to define the primary key. When 0 is used for the iRow parameter, the names of the columns defining the primary key are returned. The variant returned is of type VT_BSTR or VT_ARRAY|VT_VARIANT with variants of type VT_BSTR, whether the primary key is made of one or several columns, respectively.

6.11 FindPrimaryKey Searches the row whose primary key equals the input value and returns the row number of the row found. If no row is found, returns –1. HRESULT FindPrimaryKey(VARIANT val, long* iRow); Parameters [in] val: The VARIANT used to specify the key value to search for. [out] iRow: Address of the long integer used to return the number of the row whose primary key equals val. If no row is found, -1 is returned. Remarks When the primary key is made of several columns, the input variant must be of type VT_ARRAY|VT_VARIANT.

6.12 Find Searches a column for a value. HRESULT Find( long iRowStart, const VARIANT iCol,

87



enum AtoCompareOp op, const VARIANT value, long* piRow ); Parameters [in] iRowStart: The long integer used to specify the row number from which the value will be searched for. [in] iCol: The VARIANT used to specify the column number or the column name that will be searched. [in] op: The atoCompareOp enumeration value used to specify the search criteria (greater than, less than, equal to, etc). [in] value: The VARIANT used to specify the value to search. [out] piRow: The long integer pointer used to return the row number of the first row matching the search criteria. –1 is returned if no row is found. Remarks Patch iRowStart inside a loop in order to scan several rows matching the search criteria. This method should be used only for a few searches, because on the Atoll side, this method scans the rows one after the other and can be very time consuming. If the column is the primary key of the TabularData Object, use FindPrimaryKey instead. For repetitive search operations, use a collection (map) of all the rows and write your own filter. Example In this example, we search for all transmitters whose LOSSES are equal to 2, and replace them with 3. Dim transmitters Dim iRow Const atoEQ = 0 Set transmitters = ActiveDocument.GetRecords(“Transmitters”, False) iRow = 0 While iRow <> -1 iRow = transmitters.Find(iRow + 1, "LOSSES", atoEQ, 2) If iRow <> -1 Then transmitters.Edit(iRow) transmitters.SetValue("LOSSES", 3) transmitters.Update End If Wend

6.13 GetFormattedValue Returns a column value formatted as a string.

88


AT332_TAG_E0

HRESULT GetFormattedValue(long iRow, const VARIANT iCol, BSTR *pVal); Parameters [in] Row: The row number. •

A valid iRow number is an integer whose value is greater than zero or equal to zero, and lower than or equal to the row count of the TabularData object.

[in] iCol: The VARIANT used to define the column. • •

When iCol variant type if VT_I4, iCol is interpreted as a column number. A valid column number is an integer whose value is greater than zero or equal to zero, and lower than or equal to the column count of the TabularData object. When iCol variant type if VT_BSTR, iCol is interpreted as a column name. Column names are not case sensitive.

[out] pVal: Address of a BSTR string used to return the formatted value. Remarks When 0 is used for the iRow parameter, the title of the column specified by iCol is returned. The title of a column is localized and may be shown to a user, as opposed to the column name.

6.14 CancelUpdate Cancels a pending update. This method may be called after Edit or AddNew to cancel the operation. HRESULT CancelUpdate();

6.15 get_ColumnNumber Returns a column number. HRESULT get_ColumnNumber(const VARIANT vColName, long *pCol); Parameters [in] vColName: The VARIANT used to specify the name of the column. [ou] pCol: Address of the long integer used to return column number. Remarks It is faster to read data from tables using the column number instead of the column name. It also works for linked fields. For instance you can write: Set sites = doc.GetRecords("SITES", False) colLatitude = sites.ColumnNumber("LATITUDE") For i = 1 To sites.RowCount latitude = sites.GetValue i, colLatitude Next

6.16 get_CanEdit Checks if rows can be modified. HRESULT get_CanEdit(VARIANT_BOOL *pVal);

89



Parameters [out] pVal: Address of the VARIANT_BOOL used to return whether rows can be modified or not. Remarks If VARIANT_FALSE is returned, then the Edit operation on this table is undefined.

6.17 get_CanAddNew Checks if rows can be added. HRESULT get_CanAddNew(VARIANT_BOOL *pVal); Parameters [out] pVal: Address of the VARIANT_BOOL used to return whether rows can be added or not. Remarks If VARIANT_FALSE is returned, then the AddNew operation on this table is undefined.

6.18 get_CanFilterSort Checks if rows can be filtered or sorted. HRESULT get_CanFilterSort(VARIANT_BOOL *pVal); Parameters [out] pVal: Address of the VARIANT_BOOL used to return whether rows can be filtered or sorted. Remarks If VARIANT_FALSE is returned, then the Filter and Sort operations on this table are undefined.

6.19 get_Filter Returns the filter currently set on the table. HRESULT get_Filter(VARIANT *pvCriteria); Parameters [out] : pvCriteria: Address of the VARIANT used to return the filter previously set on the table. Remarks Please refer to the AtoRowFilter enumeration definition for the list of constants used to filter only modified, added, or deleted rows.

6.20 put_Filter Filters the table data according to a filter criteria. HRESULT put_Filter(const VARIANT vCriteria);

90


AT332_TAG_E0

Parameters [in] vCriteria: The VARIANT used to specify the filter criteria. When vCriteria is of type VT_I4, it is interpreted as an AtoRowFilter enumeration value. When vCriteria is of type VT_BSTR, it is interpreted as a filter string. Filter strings are what can be seen in the Atoll "Table" tab properties for record folders, when using advanced filtering. Please refer to the Atoll User Manual for more information about advanced filtering on data. Remarks Please refer to the AtoRowFilter enumeration definition for the list of constants used to filter only modified, added, or deleted rows. If the table is retrieved using GetRecords with aAll parameter set to False, setting this property is the same as setting the filter interactively in an Atoll session. To remove any previous filter, call this method either with atoRowFilterNone value or with an empty string. When the Atoll document is not connected to a database, atoRowFilterModifiedOrNew and atoRowFilterDeleted are not available.

6.21 get_Sort Returns the sort order currently set on the table. HRESULT get_Sort(VARIANT *pvCriteria); Parameters [in] vCriteria: The VARIANT, of type VT_BSTR, used to specify the sort order. It contains a list of comma separated database field names. Each field is optionally followed by the DESC keyword to indicate that the sort order associated with the field is "Descending". Remarks If the table is retrieved using GetRecords with aAll parameter set to False, setting this property is the same as setting the sort order interactively in an Atoll session. To remove any previous sort order, call this method with an empty string. Example Private Sub PrintTransmittersTable(transmRec, infoMsg) For nRow = 1 To transmRec.RowCount LogMessage infoMsg & ": " & transmRec.GetValue(nRow, "TX_ID") Next End Sub Sub Main Set t = ActiveDocument.GetRecords("transmitters", False) ‘ Sort ascending according to the "SITE_NAME" database field t.Sort = "SITE_NAME" PrintTransmitterTables t, "Sort = SITE_NAME" ‘ Sort descending according to the "SITE_NAME" database field t.Sort = "SITE_NAME DESC" PrintTransmittersTable t, "Sort = SITE_NAME DESC"

91



End Sub

6.22 put_Sort Sorts the table data. HRESULT put_Sort(const VARIANT vCriteria); Parameters [in] vCriteria: The VARIANT, of type VT_BSTR, used to specify the sort order. It contains a list of comma separated database field names. Each field is optionally followed by the DESC keyword to indicate that the sort order associated with the field is "Descending". Remarks If the table is retrieved using GetRecords with aAll parameter set to False, setting this property is the same as setting the sort order interactively in an Atoll session. To remove any previous sort order, call this method with an empty string. Example See "get_Sort" on page 91.

6.23 GetOriginalValue Returns an original field value. HRESULT GetOriginalValue(long iRow, const VARIANT iCol, VARIANT *pVal); Parameters [in] iRow: The long integer used to specify a row number. [in] iCol: The VARIANT used to specify a column name or a column number. [out] pVal: Address of VARIANT used to return the original column value. Remarks The original value, as opposed to the current value return by GetValue, is the value retrieved from the database when the Atoll document has been refreshed for the last time. If the row is unmodified, the original value is the same as the current value. If the row is deleted the current value is the null value and the original value is the value just before the row was deleted.

6.24 get_RowStatus Returns a row status. HRESULT get_RowStatus(long iRow, enum AtoRowStatus *pVal); Parameters [in] iRow: The long integer used to specify a row number. [out] pVal: Address of the AtoRowStatus enumeration value used to return the row status.

92


AT332_TAG_E0

Remarks When an Atoll document is open from a database, row statuses are set to atoRowStatusUnmodified and original values are set for all row columns. When the document is archived or refreshed from the database, row statuses are set to atoRowStatusUnmodified and all columns original values are set for rows that have been archived or refreshed. When a new row is created, the row status is set to atoRowStatusNew and the original value for all columns are set to the null value. When a row is modified, the row status is set to atoRowStatusModified. If you revert the row changes, the row status is set to atoRowStatusUnmodified. When a row is deleted, the row status is set to atoRowStatusDeleted, the row column values are set to the null value, and the original column values are the column values just before the row was deleted.

6.25 get_Columns Returns table columns definition. HRESULT get_Columns(ITabularData** ppVal); Parameters [out] ppVal: Address of the ITabularData interface pointer used to return a tabular data object holding the table columns definition:

Column Name

Type

Description

LEGEND

String

The display name of the column

NAME

String

The database name of the column

TYPE

Integer

The data type of the column. Valid values are: 0=Text 1=Short integer 2=Long integer 3=Single 4=Double 5=True/False 6=Date/Time 7=Currency;

SIZE

Integer

The size, in bytes, for a column of TYPE 0 (Text).

DEFAULT

Variant

The default value of the column. The type of the variant depends on the type of the column, as indicated by TYPE. May be Null.

FORMATTED_DEFAULT

String

The default value of the column, formatted as a string.

GROUP

String

The name of the database field group the column belongs to.

ISCUSTOMFIELD

Boolean

Whether the column is a user column (True), or not (False).

CHOICELIST_TYPE

Integer

Whether a column of TYPE 0(Text) content values are restricted to the values specified in CHOICELIST_VALUES.

CHOICELIST_VALUES

String

New-line separated string of valid values for a column of TYPE text.

6.26 GetValues Returns a sub-table of the Tabular Data Object. The sub-table is returned using a 2-dimension array of VARIANTs.

93



HRESULT GetValues(VARIANT rows, VARIANT columns, VARIANT *pValues); Parameters [in] rows: A reference to a VARIANT used to specify the rows to retrieve.

The type of the rows input VARIANT may be:

VT_EMPTY: An empty VARIANT is used to specify that all the table rows must be returned.

VT_ARRAY | VT_VARIANT: 1-dimension array of VARIANTs, with VARIANTs of type VT_I4 is used to specify one or several rows. A valid row number is any integer, such that 1 <= row number <= RowCount.

[in] columns: A reference to a VARIANT used to specify the columns to retrieve.

The type of the columns input VARIANT may be:

VT_EMPTY: An empty VARIANT is used to specify that all the table columns must be returned.

VT_ARRAY | VT_VARIANT: 1-dimension array of VARIANTs, with VARIANTs of type VT_I4 or VT_BSTR, is used to specify one or several columns either by their column numbers, or by their names. A valid column number is any integer such that 1 <= column number <= ColumnCount.

[out] pValues: Address of the VARIANT used to return the sub-table content, as specified by the rows and columns input parameters.

The returned variant is a 2-dimension array of variants, its type is VT_ARRAY|VT_VARIANT. The first dimension is used to specify TabularData object rows. The second dimension is used to specify TabularData object columns.

The number of rows returned is one plus the number of elements in the rows array. The first row (number 0) is used to return the column names, this is the sub table header. The data starts at row number 1.

For each row, an additional column (column number 0) is reserved for a future use. For each row, the data starts at column 1.

3 more additional columns are returned, in the latest columns of the sub table returned:

“TABULARDATA_POSITION”: For each row, this column is used to return its row number.

94


AT332_TAG_E0

“TABULARDATA_ERRORCODE”: For each row, this column is used to return an error code (VT_I4) in case an error has occurred retrieving values for that row, VT_EMPTY otherwise.

“TABULARDATA_ERRORMESSAGE”: For each row, this column is used to return an error message (VT_BSTR) in case an error has occurred retrieving values for that row, VT_EMPTY otherwise. Remarks: The method performs parameters validation first. If the validation fails, a VT_EMPTY variant is returned along with an HRESULT error code indicating the error. Once parameters validation has succeeded, the method returns a success error code, and the “TABULARDATA_ERRORCODE” column of the returned array of variants must be used to check for any errors, for any row in the returned table.

For each row, column values that could not be retrieved are returned as VT_EMPTY variants.

6.27 GetFormattedValues Returns a sub-table of the Tabular Data Object. The sub-table is returned using a 2-dimension array of VARIANTs. HRESULT GetFormattedValues(VARIANT rows, VARIANT columns, VARIANT *pValues); Remarks: This is essentially the same as the GetValues method but here column values are returned as VARIANTs of type VT_BSTR. Column values are formatted according to the rules used to display table views interactively.

6.28 SetValues Updates the table content with the given values. HRESULT SetValues(VARIANT values, VARIANT *statuses); Parameters [in] values: A VARIANT used to specify the rows, the columns, and the values to update. The values VARIANT must be a 2-dimension variant array of type VT_ARRAY|VT_VARIANT.

The first row is used to specify the columns to update.

The last column must be named “TABULARDATA_POSITION”, it is used to specify the row position (integers, VT_I4) to use in the table operation:

If the row position is a valid row number, such as 1 <= row position <= RowCount, then a table “Edit” operation will be performed. If -1 is used to specify the row position, then a table “AddNew” operation will be performed.

The rest of the variant array is used to specify the values to update.

Elements of the values array of type VT_EMPTY are ignored in the update process.

95



SetValues attempts to update all specified rows and returns an update status for each row in the statuses output VARIANT.

[out] statuses: An output VARIANT used to return an update status for each row to update, using a VARIANT of type VT_ARRAY|VT_VARIANT, a 2-dimension array of variants.

There are 3 columns in the statuses output array(dimension number 2):

"TABULARDATA_POSITION": For each row, this column is used to return its row number.

"TABULARDATA_ERRORCODE": For each row, this column is used to return an error code (VT_I4) in case an error has occurred retrieving values for that row, VT_EMPTY otherwise.

"TABULARDATA_ERRORMESSAGE": For each row, this column is used to return an error message (VT_BSTR) in case an error has occurred retrieving values for that row, VT_EMPTY otherwise. Remarks: The "TABULARDATA_ERRORCODE" column of the status variant array must be used to check for any errors, for any row in the returned table.

6.29 Hidden Columns In Radio Tabular Data Objects There are hidden columns in Radio Data Tables. These hidden columns can only be accessed using the API.

6.29.1 Table MWLINKS "_LINK_LENGTH" : link length

"_LINK_COLOR" : link color

6.29.2 Table MWOTLINKS "_LINK_COLOR" : link color

6.29.3 Transmitters Tables, All Technologies "_ANTENNA_SIGNATURE"

"_RADIO_TRANSMITTER"

"_TRANSMITTER_COLOR"

"_REPEATERS_EQUIVALENT_ULLOSS" Read-only column, used to access the noise rise due to repeaters

96

Chapter 7 Zones and Predictions Tabular Data Objects


98

Atoll 3.3.2 Task Automation Guide Chapter 7: Zones and Predictions Tabular Data Objects

AT332_TAG_E0

7 Zones and Predictions Tabular Data Objects 7.1 Zones Tabular Data Object Column Name

Type

Description

NAME

String

"ComputationZone" if this row is the computation zone. "FocusZone" if this rowis part of the focus zone. "FilterZone" if this row is part of the filtering zone. "PrintZone" if this row is part of the printing zone. "ExpBitmapZone" if this row is part of the coverage export zone. Atoll >= 2.8.1 "HotSpotZone" if this row is part of the hot spot zone.

POINTS

Array

An array of points as double values.

CONTOUR_NUM

Integer

The contour index.

POLYGON_NUM

Integer

The polygon index.

POLYGON_NAME

String

Atoll >= 2.8.1 The name of the polygon. For hot spot zones, it is the name of a specific hot spot zone. For other zones, it is the name the zone sub-folder, in the explorer window. This column is read-only.

Atoll Version  2.8.1

It is now possible to access hot spot zones. Their content is identified by the "NAME" column ("HotSpotZone"), then a specific hot spot zone is specified by the "POLYGON_NAME" column, which is used to indicate a specific hot spot zone in the hot spot zones folder. However, unlike other zones, hot spot zones access is read-only. It is not possible to edit a hot spot zone, to delete a hot spot zone, or to create a new hot spot zone. Example Reading the first contour of the focus zone: Public Sub ReadZone() Set doc = ActiveDocument Set zones = doc.GetRecords("Zones", True) row = zones.Find(1, "NAME", atoEQ, "FocusZone") pts = zones.GetValue(row, "POINTS") If (IsArray(pts)) Then For i = LBound(pts, 1) To UBound(pts, 1) ptx = pts(i,0) pty = pts(i,1) MsgBox "Pts(" + CStr(i) + ") = " + CStr(ptx) + ", " + CStr(pty) Next

99



Else MsgBox "Not an array" End If End Sub

7.2 Predictions Tabular Data Object The "PREDICTIONS" Tabular Data object is read-only except for the LOCKED field, which can be used to lock or unlock path loss matrices of a transmitter. Atoll Version  2.8.0

The field PATH_NAME is read-write. Its value can be set to Null , in which case path loss matrices for TX_ID are deleted. Column Name

Type

Description

TX_ID

String

Transmitter name.

LOCKED

Boolean

True if the path loss matrices are locked, otherwise False.

VALID

Boolean

True if the main and extended path loss matrices are valid, otherwise False.

INVALID_CAUSE

String

Cause of invalidity, when VALID returns False. Null value when VALID returns True.

SIZE

Integer

Size of the main matrix plus the size of the extended matrix, in bytes.

PATHNAME

String

Null value when there is no storage for the main matrix. "(Embedded in document)" if the storage is not external. Otherwise contains the main path loss matrix file path.

PATHLOSS

Object

The object implements the IGridData interface. This grid data contains the main path loss matrix data for transmitter TX_ID. Null value when there is no available result for the main matrix.

SIGNAL

Object

The object implements the IGridData interface. This grid data contains the main signal level matrix data for transmitter TX_ID. Null value when there is no available result for the main matrix.

LOWRES_PATHLOSS

Object

The object implements the IGridData interface. This grid data contains the extended path loss matrix data for transmitter TX_ID. Null value when there is no available result for the extended matrix.

LOWRES_SIGNAL

Object

The object implements the IGridData interface. This grid data contains the extended signal level matrix data for transmitter TX_ID. Null value when there is no available result for the extended matrix.

String

Atoll version  2.7.0 Null value when there is no storage for the extended matrix. "(Embedded in document)" if the storage is not external. Otherwise contains the extended path loss matrix file path.

LOWRES_PATHNAME


New columns are available These values are available even when VALID returns FALSE but they are not up to date when the resolution of path loss matrices, the calculation area, or the transmitter location has changed.

100


AT332_TAG_E0

Column Name

Type

Description

GRID_X

Double

X-coordinate of the top-left corner of the main path loss matrix upper-left pixel. Null value when there is no available result for the main matrix.

GRID_Y

Double

Y-coordinate of the top-left corner of the main path loss matrix upper-left pixel. Null value when there is no available result for the main matrix.

GRID_NX

Integer

Number of columns in the main path loss matrix. Null value when there is no available result for the main matrix.

GRID_NY

Integer

Number of rows in the main path loss matrix. Null value when there is no available result for the main matrix.

GRID_RESX

Double

Resolution of the main path loss matrix, in metre. Null value when there is no available result for the main matrix.

GRID_RESY

Double

Resolution of the main path loss matrix, in metre. Null value when there is no available result for the main matrix.

LOWRES_GRID_X

Double

X-coordinate of the top-left corner of the extended path loss matrix upperleft pixel. Null value when there is no available result for the extended matrix.

LOWRES_GRID_Y

Double

Y-coordinate of the top-left corner of the extended path loss matrix upperleft pixel. Null value when there is no available result for the extended matrix.

LOWRES_GRID_NX

Integer

Number of columns in the extended path loss matrix. Null value when there is no available result for the extended matrix.

LOWRES_GRID_NY

Integer

Number of rows in the extended path loss matrix. Null value when there is no available result for the extended matrix.

LOWRES_GRID_RESX

Double

Resolution of the extended path loss matrix, in metre. Null value when there is no available result for the extended matrix.

LOWRES_GRID_RESY

Double

Resolution of the extended path loss matrix, in metre. Null value when there is no available result for the extended matrix.

Column Name

Type

Description

TX_PATHLOSS

Object

The object implements the IGridData interface.

TX_SIGNAL

Object


TX_LOWRES_PATHLOSS

Object


TX_LOWRES_SIGNAL

Object



New columns are available:

TX_PATHLOSS, TX_SIGNAL , TX_LOWRES_PATHLOSS, TX_LOWRES_SIGNAL for the transmitter TX_ID do not take into account its repeaters or remote antennas. On the contrary, using PATHLOSS, SIGNAL, LOWRES_PATHLOSS, LOWRES_SIGNAL, contributions from repeaters or remote antennas are combined into one matrix. Please use TX_PATHLOSS, TX_SIGNAL , TX_LOWRES_PATHLOSS, TX_LOWRES_SIGNAL columns when you need to consider transmitter signal or path loss independently from its repeaters or remote antennas. Atoll Version  3.2.0

It is now possible to update path loss matrices with external results (.LOS files).

101



You can edit the PATH_NAME or LOWRES_PATHNAME columns, specifying valid .LOS absolute full path. In this case, when the row in the predictions table is updated, path loss matrices are updated with the content of files previously specified. Please note that fo this to work, you have to georeference your provided .LOS files, with a standard BIL header file (.hdr). Please note that even if your .LOS files need to be georeferenced just like they were .BIL files, .LOS files are written bottomup, not top-down.

TX_PATHLOSS

TX_SIGNAL

TX_LOWRES_PATHLOSS

TX_LOWRES_SIGNAL

102

Object

The object implements the IGridData interface. This grid data contains the main path loss matrix data for transmitter TX_ID. Null value when there is no available result for the main matrix. Values returned do not include contributions from repeaters or remote antennas of the transmitter TX_ID.

Object

The object implements the IGridData interface. This grid data contains the main signal level matrix data for transmitter TX_ID. Null value when there is no available result for the main matrix. Values returned do not include contributions from repeaters or remote antennas of the transmitter TX_ID.

Object

The object implements the IGridData interface. This grid data contains the extended path loss matrix data for transmitter TX_ID. Null value when there is no available result for the extended matrix. Values returned do not include contributions from repeaters or remote antennas of the transmitter TX_ID.

Object

The object implements the IGridData interface. This grid data contains the extended signal level matrix data for transmitter TX_ID. Null value when there is no available result for the extended matrix. Values returned do not include contributions from repeaters or remote antennas of the transmitter TX_ID.

Chapter 8 CoordSystem Object


104

Atoll 3.3.2 Task Automation Guide Chapter 8: CoordSystem Object

AT332_TAG_E0

8 CoordSystem Object This object contains the entire definition of a coordinate system. Several coordinate systems are used in Atoll documents; one for display, one for projected geographic files, and one for site coordinates. The last one can be related to the system used for display. This object is not defined in Atoll library but in the FSKGISLib library. It can convert points coordinates from one coordinate system to another. The CoordSystem object provides the following properties and methods: Name

Description

Code

Returns or sets the numeric code of the coordinates system.

ConvertCoordsTo

Converts the coordinates of a point expressed in the current system to another one.

Datum

Returns or sets the numeric value of the datum.

DatumName

Name of the datum.

Description

Description of the datum.

Ellipsoid

Returns or sets the numeric value of the ellipsoid.

EllipsoidName

Name of the ellipsoid.

Name

Returns or sets the name of the coordinates system.

Pick

Opens the coordinates system dialogue.

ProjMethod

Projection method used for the current coordinates system.

ProjParameter

Reads a parameter of the projection.

SetDatum

Changes the datum of the system.

SetProjection

Sets the projection parameters of the coordinate system.

Unit

Returns or sets the unit of the coordinate system.

Attributes

For details on coordinate systems, see the Technical Reference Guide.

8.1 How to Access a CoordSystem Object To get the coordinate system used for sites: Dim doc Dim coordSys Set doc = Atoll.ActiveDocument Set coordSys = doc.CoordSystemInternal

8.2 Code Returns or sets the numeric code of the coordinates system. HRESULT Code(long *pVal); HRESULT Code(long val);

105



Parameters pVal: Address of the Long read as the code of the system. val: Long value representing the code of the system to set. Classical system codes have values less than 32767. System codes greater or equal to 32768 correspond to user defined systems.

8.3 ConvertCoordsTo Converts the coordinates of a point expressed in the current system to another one. HRESULT ConvertCoordsTo( IDispCoordSystem *targetCS, VARIANT inPoint, VARIANT *outPoint ); Parameters [in] targetCS: An IDispCoordSystem interface pointer used to specify the coordinate system to which input coordinates must be converted. [in] inPoint: A VARIANT used used to specify the coordinates of an input point. The coordinates are expressed in the current coordinate system. The VARIANT must be a one dimension array of 2 floating point values (VT_ARRAY | VT_R8). Element at index 0 is used to specify the x coordinate, element at index 1 is used to specify the y coordinate. [out] outPoint: A pointer to a VARIANT used to return the coordinate of the inPoint input point expressed in the targetCS coordinate system. The type of the VARIANT returned is VT_ARRAT | VT_R8 : a one dimension array of 2 floating point values. Element at index 0 is used to specify the x coordinate, element at index 1 is used to specify the y coordinate. Example Public Sub ConvertSitesCoordinates Dim sites Dim x Dim y Dim oFrom Set oFrom = ActiveDocument.CoordSystemInternal Dim oTo Set oTo = ActiveDocument.CoordSystemDisplay Dim coords Set sites = ActiveDocument.GetRecords("Sites", True) Dim i For i = 1 To sites.RowCount x = sites.GetValue(i, "LONGITUDE") y = sites.GetValue(i, "LATITUDE") coords = oFrom.ConvertCoordsTo(oTo, Array(x, y))

106


AT332_TAG_E0

LogMessage sites.GetValue(i,"NAME")&":"&CStr(coords(0))&";"&CStr(coords(1)) Next End Sub

8.4 Datum Returns or sets the numeric value of the datum. HRESULT Datum(long *pVal); HRESULT Datum(long val); Parameters pVal: Address read as the datum code of the system. val: Value to be set as the datum code of the system.

8.5 DatumName Name of the datum. HRESULT DatumName(BSTR *pVal); Parameters pVAl: Pointer to the datum name.

8.6 Description Description of the datum. HRESULT Description(BSTR *pVal); Parameters pVal: Pointer to datum description.

8.7 Ellipsoid Returns or sets the numeric value of the ellipsoid. HRESULT Ellipsoid(long* pVal); HRESULT Ellipsoid(long Val); Parameters pVal: Address read as the ellipsoid code of the system. val: Value to be set as the ellipsoid code of the system.

8.8 EllipsoidName Name of the ellipsoid.

107



HRESULT EllipsoidName(BSTR* pVal); Parameters pVal: Pointer to the name of the ellipsoid.

8.9 Name Returns or sets the name of the coordinates system. HRESULT Name(BSTR *pVal); HRESULT Name(BSTR pVal); Parameters pVal: Address read as the name of the coordinates system. val: Value to be set as the name of the coordinates system.

8.10 Pick Opens the coordinates system dialogue. HRESULT Pick(OLE_HANDLE parentWindow, WORD types, VARIANT_BOOL *ret); Parameters parentWindow: OLE_HANDLE of the parent window for which the dialogue is required to be opened. types: Bitset of CoordSysType (see CoordSysTypes) corresponding to the types of systems the dialogue must filter before opening. ret: Pointer to a VARIANT_BOOL, set to VARIANT_TRUE if the user quits the dialogue with OK, otherwise VARIANT_FALSE. CoordSysTypes enum CoordSysType { fgUndefinedCoordSys = 1, fgGeographic2D

= 2,

fgProjected2D

= 4

} CoordSysType;

8.11 ProjMethod Projection method used for the current coordinates system. HRESULT ProjMethod(ProjectionMethod *pVal); Parameters pVal: Pointer to the read ProjectionMethod.

108


AT332_TAG_E0

8.12 ProjParameter Reads a parameter of the projection. HRESULT ProjParameter(ProjParameterIndices index, double *pVal); Parameters index: Index of the parameter to read. pVal: Address of the double containing the value of the parameter. Remarks Keep in mind that the real valid range of index parameters depends on the projection method.

8.13 SetDatum Changes the datum of the system. HRESULT SetDatum(long ellipsoidCode, VARIANT params); Parameters ellipsoidCode: Numeric code of the ellipsoid of the new datum. params: Parameters of the projection provided as an array of variants.

8.14 SetProjection Sets the projection parameters of the coordinate system. HRESULT SetProjection(ProjectionMethod method, VARIANT projectionParameters); Parameters [in] method: The ProjectionMethod enumeration value used to change the projection method of the coordinate system. [in] projectionParameters: A SAFEARRAY of VARIANTs of type VT_R8 used to specify the projection parameters of the coordinate system. The projection parameters must match with the method parameter. Each parameter is identified by its index in the array, starting from 0. Array indexes are the same as ProjParameterIndices enumeration values. Projection parameters values are the the same as values returned by the ProjParameter property.

8.15 Unit Returns or sets the unit of the coordinate system. HRESULT Unit(GeographicUnit *pVal); HRESULT Unit(GeographicUnit newVal); Parameters pVAl: Address of the current geographic unit of the system. newVal: New value for the geographic unit.

109


110


Chapter 9 ChildFolder Object


112

Atoll 3.3.2 Task Automation Guide Chapter 9: ChildFolder Object

AT332_TAG_E0

9 ChildFolder Object A ChildFolder object represents an item in the application explorer window. It can be a collection of sub-items. • The ChildFolder object provides the following properties and methods: Name

Description

Attributes

get_Application

Returns the Application object.


get_Parent

Returns the parent ChildFolder object.

Type: ChildFolder object Access: Read

get_Name

Returns the ChildFolder object display name.


put_Name

Sets the ChildFolder object display name.


get_Count

Returns the number of children of the ChildFolder object.


get_Item

Returns one of the children of the ChildFolder object.

Type: ChildFolder children collection Access: Read

get__NewEnum

Returns an object used to enumerate the children of the ChildFolder object.

get_Visible

Returns the visibility state of the ChildFolder object.


put_Visible

Sets the visibility state of the ChildFolder object.


get_Selected

Returns the selected state of the ChildFolder object.


put_Selected

Sets the selected state of the ChildFolder object.


Export

Exports a ChildFolder object to a file, in a given format.

CentreOnMap

Centres the application map window around the ChildFolder object.

Redraw

Redraws the ChildFolder object.

AddChild

Adds a new child to the current ChildFolder object.

Remove

Removes the ChildFolder object from its parent ChildFolder object.

get_position

Returns the ChildFolder object position relative to its parent ChildFolder object.


put_position

Sets the ChildFolder object position relative to its parent ChildFolder object.


get_Object

Access to some specific features on the ChildFolder object.

get_dispatch

Access to some specific features on the ChildFolder object.

get_ObjectKind

Returns a type identifier of the ChildFolder object.

GetProperty

Returns a ChildFolder object property.

SetProperty

Sets a ChildFolder object property.


113



Name

Description

GetPropertiesInfo

Returns names and types for all properties available on the ChildFolder object.

PropertyIsPropertyContainer

Returns true when a ChildFolder object property is a PropertyContainer object.

PropertyIsTabularData

Returns true when a ChildFolder object property a TabularData object.

LoadProperties

Sets properties from a property container to the ChildFolder object.

SaveProperties

Saves all the ChildFolder object properties to another property container.

RemoveItem

Removes one of the children of the ChildFolder object.

SetCustomIcon

Sets the path of an icon to use for a custom child folder.

Attributes

9.1 How to Access a ChildFolder Object A ChildFolder is first obtained through a root entry point from the document and is related to a tab of the Atoll Explorer window. Most ChildFolder objects may have children, can be selected, set visible, and renamed. Only coverage predictions may be exported. Dim folder Dim item Dim doc Dim dataRoot Const atoData = 0 Set doc = Atoll.ActiveDocument Set dataRoot = doc.GetRootFolder(atoData) For Each folder in dataRoot ‘ do some work with this folder, for instance: For Each item in folder ‘ do some work with this item Next Next

9.2 get_Application Returns the Atoll Application object. HRESULT get_Application(IApplication **ppVal);

114


AT332_TAG_E0

Parameters [out] ppVal: Address of the IApplication interface pointer used to return the Atoll Application object.

9.3 get_Parent Returns the parent Atoll ChildFolder object. HRESULT get_Parent(VARIANT *pVal); Parameters [out] pVal: Address of the VARIANT used to return the parent ChildFolder object. The type of the returned VARIANT is VT_DISPATCH. When the ChildFolder object is a root ChildFolder object, the IDispatch interface pointer of the Atoll Document is returned, otherwise the IDispatch interface pointer of the parent ChildFolder object is returned.

9.4 get_Name Returns the ChildFolder object display name. HRESULT get_Name(BSTR *pVal); Parameters [out] pVal: Address of the BSTR used to return the display name. Example Renaming the "Transmitters" folder. Dim folder Dim dataTab Dim folderName Const atoData = 0 Set dataTab = ActiveDocument.GetRootFolder(atoData) For Each folder In dataTab folderName = folder.Name If folderName = “Transmitters” Then folder.Name = “TransmittersTest” End if Next

9.5 put_Name Sets the ChildFolder object display name. HRESULT put_Name(const BSTR aNewVal);

115



Parameters [in] aNewVal: The BSTR used to specify the display name. Example See "get_Name" on page 115.

9.6 get_Count Returns the number of children of the ChildFolder object. HRESULT get_Count(long *pVal); Parameters [out] pVal: Address of the long integer used to return the number of children.

9.7 get_Item Returns one of the children of the ChildFolder object. HRESULT get_Item(const VARIANT iIdx, IChildFolder **pVal); Parameter [in] iIdx: A VARIANT of type VT_I4 or VT_BSTR identifying the returned ChildFolder object. If the type of the variant is VT_I4, it is interpreted as a zero-based index in the list of children. If the type of the variant is VT_BSTR, it is first interpreted as the display name of the child to search for, and if the display name is not found, it is then interpreted as a ChildFolder object kind, as returned by get_ObjectKind. [out] pVal: Address of the IChildFolder interface pointer used to return a ChildFolder object.

9.8 get__NewEnum Returns an object used to enumerate the children of the ChildFolder object. HRESULT get__NewEnum(LPUNKNOWN *ppUnk); Parameters [out] ppUnk: Address of the IUnknown interface pointer used to return the enumerator object. The IEnumVARIANT interface is implemented by the enumerator object. Example Const atoModule = 2 Set modules = app.ActiveDocument.GetRootFolder(atoModule) For Each module In modules ‘ do something with module Next

9.9 get_Visible Returns the visibility state of the ChildFolder object.

116


AT332_TAG_E0

HRESULT get_Visible(VARIANT_BOOL *pVal); Parameters [out] pVal: Address of the VARIANT_BOOL used to return the visibility state. The visibility state values are: VARIANT_TRUE : the ChildFolder object may be displayed on Atoll Map View windows. VARIANT_FALSE : the ChildFolder object won’t be displayed on Atoll Map View windows. Remarks The visibility state only makes sense for ChildFolder objects that may appear on Atoll Map View windows. get_Visible and put_Visible calls are ignored for objects that do not support it. No error is returned. Example dataFolder.Item("Predictions").Visible = True

9.10 put_Visible Sets the visibility state of the ChildFolder object. HRESULT put_Visible(VARIANT_BOOL aNewVal); Parameters [in] aNewVal: The VARIANT_BOOL used to specify the visibility state. The visibility state values are: VARIANT_TRUE : the ChildFolder object may be displayed on Atoll Map View windows. VARIANT_FALSE : the ChildFolder object won’t be displayed on Atoll Map View windows. Remarks The visibility state only makes sense for ChildFolder objects that may appear on Atoll Map View windows. get_Visible and put_Visible calls are ignored for objects that don’t support it. No error is returned. Example dataFolder.Item("Predictions").Visible = True

9.11 get_Selected Returns the selected state of the ChildFolder object. HRESULT get_Selected(VARIANT_BOOL *pVal); Parameters [out] pVal: Address of the VARIANT_BOOL used to return the selected state of the ChildFolder object. Remarks get_Selected and put_Selected calls are ignored for objects that don’t support it. No error is returned.

117



Example Public Sub SelectTx Set doc = ActiveDocument Const atoData = 0 Set dataFolder = doc.GetRootFolder(atoData) ’ Select the "Site0_0" transmitter For Each folder In dataFolder If folder.Name = "Transmitters" Then folder.Item("Site0_0").Selected = True End If Next End Sub

9.12 put_Selected Sets the selected state of the ChildFolder object. HRESULT put_Selected(VARIANT_BOOL aNewVal); Parameters [in] newVal: The VARIANT_BOOL used to specify the selected state. Remarks get_Selected and put_Selected calls are ignored for objects that don’t support it. No error is returned. Example See "get_Selected" on page 117.

9.13 Export Exports a ChildFolder object to a file, in a given format. This method can only be used for studies. HRESULT Export( const BSTR bstrFileName, IDispCoordSystem* proj, const BSTR bstrFormat ); Parameters [in] bstrFileName: A string containing an absolute file path. [in] proj: An IDispCoordSystem interface pointer used to define the coordinate system for the export. [in] bstrFormat: A string used to define the format of the file specified by bstrFileName.

118


AT332_TAG_E0

The syntax for the bstrFormat parameter is: PropertyName=Value;[PropertyName=Value;]format format: • • • • • • • • • • • •

Available values are: SHP AGD MIF TAB BMP TIF TXT ARCVIEWGRIDASCII PNG JP2 VMAPPER (for Vertical Mapper GRC or GRD file formats) Please read the application documentation to learn more about these file formats. The data exported is the geographic coverage prediction of a study when using SHP, AGD, MIF, TAB, BMP, ARCVIEWGRIDASCII, PNG, JP2, or TIF formats. However, if you specify TXT format, this method will export the study report in tabulated ASCII text format. This prediction study report is the same as the one available by right-clicking the study in the application and selecting Generate Report.

Available properties are: Property Name

Resolution

AreaType

Value

integer

0|1|2

Version

Description

 2.8.1

This is the export resolution, expressed in meter. If not specified, the resolution used to perform the export is the study resolution. It is only relevant when the export format is a vector format, as opposed to a raster format.

 2.8.1

Used to specify the zone to export. Available values are: 0 : The Entire Covered Area 1 : The Computation Zone 2 : The Geographic Export Zone If not specified, the entire covered area is considered to perform the export. It is only relevant for raster formats, as opposed to vector formats.

Atoll version >= 3.3.1 Property Name

Value

Description

FilteringPercentage

This is the filtering percentage value. integer, between It is only relevant when the export format is a vector format, 0 and 100 as opposed to a raster format.

SmoothingPercentage

This is the smoothing percentage value. integer, between It is only relevant when the export format is a vector format, 0 and 100 as opposed to a raster format.

SmoothingMaximumNumberOfPoints

DataType

integer

integer, 0 or 1

This is the maximum number of points for exported vector geometries. This option is mutually exclusive with the smoothing percentage option. It is only relevant when the export format is a vector format, as opposed to a raster format. 0 = coverage thresholds are exported, this is the defaut setting if not specified. 1 = numerical coverage results are exported. This option is only relevant when BIL or GRD formats are specified.

119



Return value S_OK: Export has completed successfully. S_FALSE: Export couldn’t be performed because of one of the following reasons: • • •

The folder specified in bstrFileName does not exist. The study visibility check box is cleared. The study has no coverage.

When S_FALSE is returned, no output file is created. Example Const SID_PREDICTIONS = "{DA676EF0-E300-4AFF-BBFA-EC55D3798E4F}" Public Sub ExportStudy Dim oStudy Dim oCS Set oCS = ActiveDocument.CoordSystemDisplay For Each oStudy In ActiveDocument.GetRootFolder(0).Item(SID_PREDICTIONS) oStudy.Export "c:\export.asc", oCS, "ARCVIEWGRIDASCII" oStudy.Export "c:\export.txt", oCS, "TXT" oStudy.Export "c:\export.bmp", oCS, "BMP" Next End Sub

9.14 CentreOnMap Centres the Atoll Map View window around the ChildFolder object. HRESULT CentreOnMap(); Remarks CentreOnMap only makes sense for ChildFolder objects that may appear on Atoll Map View windows. CentreOnMap calls will be ignored for objects that don’t support it. No error will be returned.

9.15 Redraw Redraws the ChildFolder object. HRESULT Redraw(); Remarks Redraw only makes sense for ChildFolder objects that may appear on Atoll Map View windows. Redraw calls will be ignored for objects that don’t support it. No error will be returned.

9.16 AddChild Adds a new child to the current Atoll child folder object.

120


AT332_TAG_E0

HRESULT AddChild(const VARIANT spec, long position, IChildFolder2** pVal) Parameters [in] spec: VARIANT used to define the child item to add. [in] position: The position used to define where to add the new child. [out] pVal: Address of a IChildFolder2 interface pointer used to return the new Atoll child folder object just added. Remark The type of the child added depends on the type of the spec input parameter. When spec if of type VT_UNKNOWN or VT_DISPATCH, and when it is an Atoll ChildFolder object, spec is interpreted as a source ChildFolder object. AddChild will add a link to the source ChildFolder object. The source Atoll ChildFolder cannot be a link itself. Links can only be created at the root level of the Atoll Explorer geo or data tabs. Links always are created at position 0. The source ChildFolder object and the current ChildFolder object must belong to different Atoll documents. When spec if of type VT_UNKNOWN or VT_DISPATCH, and when it is an Atoll PropertyContainer object, then a new ChildFolder is added with the content of the Atoll PropertyContainer object. The properties needed to actually be able to add a new ChildFolder object depend on the current ChildFolder object type, as returned by ObjectKind.

9.17 Remove Removes the ChildFolder object from its parent ChildFolder object. HRESULT Remove(); Remarks A ChildFolder object cannot be used anymore after it is removed. ChildFolder objects may be removed by Atoll, for instance when F5 is used interactively to refresh the screen. Once this method has returned the ChildFolder object has been destroyed and invoking any method on it will result in undefined behaviour. Atoll version >= 2.8.2: This method is deprecated. Please use RemoveItem instead.

9.18 get_position Returns the ChildFolder object position relative to its parent ChildFolder object. HRESULT get_position(long *pPos); Parameters [out] pPos: Address of the long integer used to return the ChildFolder object position. ChildFolder objects are ordered from position 0 (top) to to get_Count() - 1 (bottom).

9.19 put_position Sets the ChildFolder object position relative to its parent ChildFolder object. HRESULT put_position(long lPos); Parameters [in] lPos: A long integer used to specify the ChildFolder object position. • •

If lPos  0, the ChildFolder object is moved to the top. If lPos  get_Count() - 1, the ChildFolder object is moved to the bottom.

121



9.20 get_Object Access to some specific features on the ChildFolder object. HRESULT get_Object(IUnknown **ppObject); Parameters [out] ppObject: Address of the IUnknown interface pointer used to access some specific features. Remarks Due to the nature of the interface returned, get_Object cannot be used by macros and scripts. Macros or scripts must use get_dispatch instead.

9.21 get_dispatch Access to some specific features on the ChildFolder object. HRESULT get_dispatch(IDispatch **ppDispatch); Parameter [out] ppDispatch: Address of the IDispatch interface pointer used to access some specific features.

9.22 get_ObjectKind Returns a type identifier of the ChildFolder object. HRESULT get_ObjectKind(BSTR *pRetVal); Parameters [out] pRetVal: Address of the BSTR used to return the type identifier. Remarks To be able to identify the ChildFolder object type, and therefore to safely access specific features of the ChildFolder object, here is the list of the available type identifiers:

122

Version

SID

String Value

Specific Features

 2.4.0

SID_CLUTTER

{7CB51DE8-A961-11D2-8688-0060086457D1}

Tabular data clutter properties.

 2.4.0

SID_SIMULATIONS

{CDDF1E1D-1963-4D80-A057-D23A19570984}

Simulations folder.

 2.4.0

SID_SIMULATIONSGROUP

{AF5E2B98-1D54-48FA-89C5-8BFA2936ABF2}

"Groups of simulations" folder.

 2.4.0

SID_SIMULATION

{095C5D90-96F1-4BA8-85BB-B2F990AC2DD9}

"Simulation" items.

 2.5.1

SID_SITES

{90443F68-5B3B-4AFD-B7BB-B057095EBAAD}

Sites folder.

 2.5.1

SID_ANTENNAS

{5FBEB2AE-3BBB-4FBA-94D8-5D8EA5A32069}

Antennas folder.


AT332_TAG_E0

 2.5.1

SID_TRANSMITTERS

{F7E891E8-F7F5-4870-BF63-AF559AD50FD3}

Transmitters folder, in a single-RAT document.

 2.5.1

SID_PREDICTIONS

{DA676EF0-E300-4AFF-BBFA-EC55D3798E4F}

Predictions folder.

 2.5.1

SID_UMTS_PARAMETERS

{D4F57EE3-7785-4348-9BA6-28998AA6BD80}

UMTS Parameters folder.

 2.5.1

SID_CW_MEASUREMENTS

{41413C4A-C9DE-43DD-A917-612A0AF198FC}

CW Measurements folder.

 2.5.1

SID_MEASURE_TX

{2C102EE5-BFF4-4A5A-8130-02BD0E2F70D7}

CW Measurements transmitter.

 2.5.1

SID_MEASURE_ITEM

{36858A48-7A85-482E-9DA0-B9E935ADE84C}

CW Measurements.

 2.5.1

SID_TESTMOBILEDATA

{21C11380-D8CF-4902-B622-763522AD9FC4}

Drive Test Data folder.

 2.5.1

SID_NUM_MEASURE_ITEM

{916801F9-0539-448C-8C0C-491FAC6399ED}

Drive Test Data items.

 2.5.1

SID_PARAMETERS_FOLDER

{43B8845-5226-454F-908F-59A500DB4FD1}

Parameters folder.

 2.5.1

SID_HEXAGON_SCHEMA

{B167D45E-A0BC-4DC6-B9D7-6F7B131CADF1}

Hexagonal Design folder.

 2.6.0

SID_TRAFFICFOLDER

{B3B25A07-A994-4e8d-BBD1-51556D6C4245}

Traffic folder.

 2.7.0

SID_PROPAGATIONMODELS

{4A2D160B-7D11-4D07-92DF-A3CF6B68D402}

Propagation models folder.

 2.8.2

{16A53FB3-A961-4EEA-8C30-2387DBF1CC24}

Master link ChildFolder object.

 2.8.2

{232BDB73-A68F-41A6-A954-75112D907BBF}

Link ChildFolder object.

 3.1.0

{CC637062-7AFF-4516-BEFB-BCC954E905B1}

GSM Transmitters folder, in a multi-RAT document.

 3.1.0

{FD147AA0-B9A2-47AC-8CD5-51C77A708AF8}

LTE Transmitters folder, in a multi-RAT document.

 3.1.0

{090A23A1-EE08-420D-9739-651D1045EF16}

UMTS Transmitters folder, in a multi-RAT document.

 3.2.0

{65FF5F7D-DBF0-4B52-ABB8-66F3414FD4C3}

CDMA2000 Transmitters folder, in a multi-RAT document.

 3.2.1

StudyFolder

A sub-folder of the predictions folder.

 3.3.1

{92CB60E4-BBA1-4318-BB3C-A2E3975C2EC1}

GSM Drive Test Data folder, in a multi-RAT document.

 3.3.1

{C8542595-9E51-4B4C-950D-BCB0CBAA3153}

UMTS Drive Test Data folder, in a multi-RAT document.

 3.3.1

{00F8F1C0-FC4D-4A3E-B217-339B86d7EC3B}

1XRTT Drive Test Data folder, in a multi-RAT document.

 3.3.1

{368B28F9-8D8D-4C4A-A74B-D101A88C5B7D}

LTE Drive Test Data folder, in a multi-RAT document.

 3.3.1

{C06DBABF-26C3-40C1-8C19-A11DF7820ADA}

KPis folder.

 3.3.1

{6332BD99-A54A-4837-B4A6-1C3EE8A22A88}

UE Traces folder.

 3.3.1

{911FF0FF-242D-47CE-86E8-9618CD5F564C}

Weighting Maps folder.

123



9.23 GetProperty Returns a ChildFolder object property. HRESULT GetProperty(const BSTR bstrName, VARIANT *pValue); Parameters [in] bstrName: A property name. [out] pValue: Address of the VARIANT used to return the property. Remarks The type of the returned VARIANT can be any of the following: C++

VBScript

VT_BOOL

Boolean

VT_I4

Integer

VT_R4

Single

VT_R8

Double

VT_UNKNOWN

Object

VT_DISPATCH

Object, TabularData object, ChildFolder object, PropertyContainer object

VT_BSTR

String

VT_ARRAY | (any of the previous types)

Array, with array items of the previous types

The error E_INVALIDARG is returned when there is no property named bstrName for the ChildFolder object. The properties available for the ChildFolder object depend on the type of the ChildFolder object, as returned by get_ObjectKind.

9.24 SetProperty Sets a ChildFolder object property. HRESULT SetProperty(const BSTR bstrName, const VARIANT varValue); Parameters [in] bstrName: A property name. [in] varValue: The VARIANT used to specify the property value. Remarks The error E_INVALIDARG is returned when there is no property named bstrName for the ChildFolder object. The properties available for the ChildFolder object depend on the type of the ChildFolder object, as returned by get_ObjectKind.

9.25 GetPropertiesInfo Returns names and types for all properties available on the ChildFolder object. HRESULT GetPropertiesInfo(VARIANT *pValue);

124


AT332_TAG_E0

Parameters [out] pValue : Address of the VARIANT used to return the names and types for all properties in the property container.

9.26 PropertyIsPropertyContainer Returns true when a ChildFolder object property is a PropertyContainer object. HRESULT PropertyIsPropertyContainer(const BSTR bstrName, VARIANT_BOOL *pValue); Parameters [in] bstrName : The property name. [out] pValue: Address of the VARIANT_BOOL used to return whether the property is a PropertyContainer object or not.

9.27 PropertyIsTabularData Returns true when a ChildFolder object property is a TabularData object. HRESULT PropertyIsTabularData(const BSTR bstrName, VARIANT_BOOL *pValue); Parameters [in] bstrName : The property name. [out] pValue: Address of the VARIANT_BOOL used to return whether the ChildFolder property type is TabularData object.

9.28 LoadProperties Sets properties from a property container to the ChildFolder object. HRESULT LoadProperties(const VARIANT varSource); Parameters [in] varSource : VARIANT of type VT_DISPATCH, used to specify a property container for the properties to set.

9.29 SaveProperties Saves all the ChildFolder object properties to another property container. HRESULT SaveProperties( const VARIANT varDestination) ;

Parameters [in] varDestination : VARIANT of type VT_DISPATCH, used to specify a property container where all properties will be set.

9.30 RemoveItem Removes one of the children of the ChildFolder object. HRESULT RemoveItem( const VARIANT idx) ;

125



Parameters [in] idx : A VARIANT of type VT_I4 or VT_BSTR used to specify one of the children to remove. If the type of the variant is VT_I4, it is interpreted as a zero-based index in the list of children. If the type of the variant is VT_BSTR, it is first interpreted as the display name of the child to remove, and if the display name is not found, it is then interpreted as a ChildFolder object kind, as returned by get_ObjectKind. Remarks A ChildFolder object cannot be used anymore after it is removed. ChildFolder objects may be removed by the application, for instance when F5 is used interactively to refresh the screen. This method fails for ChildFolder objects that cannot be removed interactively, and an error is returned in that case.

9.31 SetCustomIcon Sets the path of an icon to use for a custom child folder. HRESULT SetCustomIcon(const BSTR bstrPath);

Parameters [in] bstrPath : The full path to the icon file (*.ico) to load.

9.32 OpenPropertySheet Displays the child folder property sheet dialogue. HRESULT OpenPropertySheet();

Parameters:

126

Chapter 10 PropertyContai ner Object


128

Atoll 3.3.2 Task Automation Guide Chapter 10: PropertyContainer Object

AT332_TAG_E0

10 PropertyContainer Object The PropertyContainer object is a generic container containing a set of named properties of arbitrary types. The PropertyContainer object provides the following properties and methods: Name

Description

Attributes

Get

Returns a named property.

Set

Sets a named property.

GetInfo

Returns names and types for all properties set to the property container.

IsPropertyContainer

Returns true when a named property is of a PropertyContainer object.


IsTabularData

Returns true when a named property is of a TabularData object.


Load

Adds properties from another property container to the property container.

Save

Saves all the properties to another property container.

RemoveAll

Removes all properties from the property container.

Remove

Removes a named property from the property container.

10.1 Get Returns a named property. HRESULT Get(const BSTR bstrName, VARIANT *pValue); Parameters [in] bstrName: A property name. [out] pValue: Address of the VARIANT used to return the property. Remarks The type of the returned VARIANT can be any of the following: C++

VBScript

VT_BOOL

Boolean

VT_I4

Integer

VT_R4

Single

VT_R8

Double

VT_UNKNOWN

Object

VT_DISPATCH

Object, TabularData Object, ChildFolder Object, PropertyContainer Object

VT_BSTR

String

VT_ARRAY | (any of the previous types)

Array, with array items of the previous types

129



The error E_INVALIDARG is returned when the property named bstrName has not been previously set to the property container.

10.2 Set Sets a named property. HRESULT Set(const BSTR bstrName, const VARIANT varValue); Parameters [in] bstrName: A property name. [in] varValue: The VARIANT used to specify the property value. Remarks If the property named bstrName has been previously set, its content is replaced by varValue, otherwise a new property named bstrName is added to the property container.

10.3 GetInfo Returns names and types for all properties set to the property container. HRESULT GetInfo(VARIANT *pValue); Parameters [out] pValue : Address of the VARIANT used to return the names and types for all properties in the property container.

10.4 IsPropertyContainer Returns true when a named property is a PropertyContainer object. HRESULT IsPropertyContainer(const BSTR bstrName, VARIANT_BOOL *pValue); Parameters [in] bstrName : The property name. [out] pValue: Address of the VARIANT_BOOL used to return whether the property is a PropertyContainer Object.

10.5 IsTabularData Returns true when a named property is a TabularData object. HRESULT IsTabularData(const BSTR bstrName, VARIANT_BOOL *pValue); Parameters [in] bstrName : The property name. [out] pValue: Address of the VARIANT_BOOL used to return whether the property is a Tabular Data Object.

10.6 Load Adds properties from another property container to the property container.

130


AT332_TAG_E0

HRESULT Load(const VARIANT varSource); Parameters [in] varSource : VARIANT of type VT_DISPATCH, used to specify a property container for the properties to add.

10.7 Save Saves all the properties to another property container. HRESULT Save(const VARIANT varDestination); Parameters [in] varDestination : VARIANT of type VT_DISPATCH, used to specify a property container where all properties will be set.

10.8 RemoveAll Removes all properties from the property container. HRESULT RemoveAll();

10.9 Remove Removes a named property from the property container. HRESULT Remove(const BSTR bstrName, VARIANT *pValue); Parameters [in] bstrName : The property name. [out] pValue: Address of the VARIANT used to return the original property value, before it is removed.

131


132


Chapter 11 ChildFolder Object Properties


134

Atoll 3.3.2 Task Automation Guide Chapter 11: ChildFolder Object Properties

AT332_TAG_E0

11 ChildFolder Object Properties ChildFolder object properties are named properties. The set of available properties for a given ChildFolder object depends on the ChildFolder object type, returned by get_ObjectKind. ChildFolder object property names usually resemble their GUI representations in the properties dialogues inside Atoll. ChildFolder object properties are divided into the following groups according to their use and application in Atoll: • • • • • • • • • • • • • •

"Common ChildFolder Object Properties" on page 136, "Predictions Folder Properties" on page 137, "Coverage Prediction Properties" on page 137, "GSM Simulation Group Properties" on page 146, "UMTS Simulation Group Properties" on page 147, "WiMAX and LTE Simulation Group Properties" on page 148, "3GPP Multi-RAT Simulation Group Properties" on page 149, "Standard Propagation Model Properties" on page 150, "CW Measurement Properties" on page 152, "Drive Test Data Properties" on page 153, "Custom ChildFolder Object Properties" on page 153, "Master Link Properties" on page 154, "Link Properties" on page 154, "Vector Layer Properties" on page 154.

11.1 How to Access ChildFolder Object Properties The following sample codes show how to read and write ChildFolder Object properties. Reading a ChildFolder Object Property item: A ChildFolder object. propertyname: The property name. propertyvalue: The property value. On Error Resume Next ’ If the property type is an Object (Atoll Tabular Data Object, Atoll Property ’ Container Object, ...), then replace the next line with ’ "Set propertyvalue = item.GetProperty(propertyname)" propertyvalue = item.GetProperty(propertyname) If Err Then MsgBox item.Name & "." & propertyname & "does not exist." Else MsgBox item.Name & "." & propertyname & " = " & CStr(propertyvalue) End If Writing a ChildFolder Object Property item: A ChildFolder object. propertyname: The property name. propertyvalue: The property value. On Error Resume Next

135



item.SetProperty propertyname, propertyvalue If Err Then MsgBox Err.Description End If

11.2 Common ChildFolder Object Properties Some ChildFolder object properties are common to all kinds of ChildFolder objects. These properties include the following.

136

Name

Description

Attributes

NAME

ChildFolder object name as it appears in the Explorer window.

Version  : 2.6.1 Type: String Access: Read/Write

VISIBLE

ChildFolder visibility state. This property is only relevant for geographic ChildFolder objects.

Version  : 2.6.1 Type: Boolean Access: Read/Write

SELECTED

ChildFolder selected state, either selected or not selected.


POSITION

ChildFolder position, relative to the parent ChildFolder object.

Version  : 2.6.1 Type: Integer Access: Read/Write

OBJECTKIND

ChildFolder type identifier. This is the same as the value returned by get_ObjectKind.

Version  : 2.7.0 Type: String Access: Read

ISGEOGRAPHIC

Returns true if the ChildFolder object can be visible in the Map window, false otherwise. When this property is false, the properties and methods specific to the Map view are neither relevant nor applicable.

Version  : 2.7.0 Type: Boolean Access: Read

VISIBILITYSCALEMIN

ChildFolder minimum visibility scale display property. This property is only relevant for geographic ChildFolder objects.


VISIBILITYSCALEMAX

ChildFolder maximum visibility scale display property. This property is only relevant for geographic ChildFolder objects.


ADDTOLEGEND

ChildFolder add to legend display property. This property is only relevant for geographic ChildFolder objects.


DOCUMENT

A Document object. The ChildFolder object is part of the Document object.

Version  : 2.8.2 Type: Object Access: Read

LEGEND

ChildFolder object name as it appears in the Legend window.


DISABLED

ChildFolder disabled state. A ChildFolder may be disabled when some license restriction applies to this ChildFolder object.



AT332_TAG_E0

11.3 Predictions Folder Properties Type returned by get_ObjectKind: {DA676EF0-E300-4AFF-BBFA-EC55D3798E4F} The following properties are accessible through the Predictions folder. Name

Description

Attributes

PRIVATESTORAGE

Path to the path loss matrices private storage folder, as it appears in the Predictions folder properties.


11.4 Coverage Prediction Properties The coverage prediction types returned by get_ObjectKind for the various coverage predictions are listed below: • • • •

"GSM GPRS EDGE Coverage Predictions" on page 137, "UMTS HSPA Coverage Predictions" on page 138, "WiMAX Coverage Predictions" on page 138, "LTE Coverage Predictions" on page 139.

Coverage prediction properties are of the following types: • • • • • •

"General Properties" on page 140, "Group, Filter, and Sort Properties" on page 141, "Non-Simulation-based Coverage Conditions" on page 141: Coverage conditions for predictions that cannot be based on simulations, "Simulation-based Coverage Conditions" on page 143: Coverage conditions for predictions that can be based on simulations, "Shadowing and Indoor Coverage Conditions" on page 144, "Display Properties" on page 144.

GSM GPRS EDGE Coverage Predictions Name

Type

Coverage by Transmitter

{9E42C87F-56D0-43CA-A313-78A7CA9A811B}

Coverage by Signal Level (DL)

{1FF20277-9A4C-486A-B0A4-90E7E8EC72E4}

Overlapping Zones

{1F0C294B-11A0-45C9-9B32-640FED79BCA6}

Coverage by C/I Level (DL)

{8A94CAE7-B4FF-4DC6-854A-BC90FE8F0073}

Interfered Zones

{EB45E33D-FB33-44F1-A63B-B4661ACE78B2}

Coverage by GPRS/EDGE Coding Scheme

{6B062215-EEC1-40E9-9A02-F909AFF6B5DB}

RLC/MAC Throughput/Timeslot

{02BE397A-1F4B-423E-AEC4-B8138974ADD8}

Application Throughput/Timeslot

{3F8F8CB3-A5DC-49F9-8F3D-0E7243AA0E6C}

Coverage by Signal Level (UL)

{CB8A7A12-089B-4681-956A-17119E17F02C}

Service Area Analysis (DL)

{28149E1A-72E0-4C4A-8E6D-69A7A96C7257}

Service Area Analysis (UL)

{C71C77D1-0FA5-4FE4-9D96-E567620373DC}

Effective Service Area Analysis (DL+UL)

{D57D42F7-3939-422A-8600-39BF8BBB4D1D}

Packet Quality and Throughput Analysis (DL)

{02BE397A-1F4B-423E-AEC4-B8138974ADD8}

Coverage by C/I Level (UL)

{549A79FF-D191-4486-B6D8-A1544633BC26}

Coverage by Aerial (DL)

{A06B88E7-AF24-4CA8-9258-9E65292E8FCF}

Circuit Quality Indicator Analysis

{67EC97E9-9F06-4B0F-90C0-E42A67FE560C}

Attributes

137



UMTS HSPA Coverage Predictions Name

Type


{A6FB7132-FB5E-42CC-A1C1-0BEA4AF09921}

Coverage by Signal Level

{E82C3B13-240E-4DD3-A553-583ADDF57713}

Overlapping Zones

{53B30925-B781-499D-90E4-3F9B8570871B}

Coverage by Total Noise Level (DL)

{1C9384EB-57CA-433F-BDB3-07E1BE317890}

Pilot Quality Analysis (Ec/Io)

{66287FC5-81FA-40B6-84E3-2C2C4E13D121}

Service Area Analysis (Eb/Nt) (DL)

{5C6427F7-D63A-4046-B8BD-1A5E9D165890}

Service Area Analysis (Eb/Nt) (UL)

{D75ADE37-FB8A-4693-A788-47109A913C29}

Effective Service Area Analysis (Eb/ Nt) (DL+UL)

{5F74AEFA-2958-42CC-8244-C12DC19B26C3}

Handoff Zones

{39A63BBA-02EC-43E7-8523-07E29B519181}

Pilot Pollution Analysis

{2199E577-F3F5-4FFD-BCAB-0D748CA7CCD3}

HSDPA Quality and Throughput Analysis

{BFDDFC83-D8EE-4225-840F-EF842DE19B74}

HSUPA Quality and Throughput Analysis

{E9ED15F1-EC14-4451-ADFA-1953A6FB2526}

Scrambling Code Collision Zones

{AC612067-A173-439E-BF7A-76B17933A30E}


{B550F943-733A-4ECB-9E8A-EABB79FE5CD2}

Total Noise Level Analysis (DL)

{1C9384EB-57CA-433F-BDB3-07E1BE317890}

Inter-technology Interference Level Analysis (DL)

{CE1C2AE8-0F0A-4E54-A69E-F4569A73A1DF}

Attributes

WiMAX Coverage Predictions

138

Name

Type

Attributes


{BE607087-CB08-453C-B2A0-B356CD38C3F5}

Version  : 2.7.1


{9C602E1C-E5E7-44CA-8E5B-878D74D07885}

Version  : 2.7.1

Overlapping Zones

{86560A81-DE60-41CC-9B9E-83BF33CEF491}

Version  : 2.7.1

Effective Signal Analysis (DL)

{6A657977-CF0E-415C-8486-C41664F7035E}

Version  : 2.7.1

Effective Signal Analysis (UL)

{3F803866-1041-4267-8D28-FCA43445A642}

Version  : 2.7.1

Coverage by C/(I+N) Level (DL)

{DCB4B756-4D02-42DB-B838-14A62F603922}

Version  : 2.7.1

Coverage by C/(I+N) Level (UL)

{4163305D-E203-4A78-99F6-E59EA537AB7E}

Version  : 2.7.1

Coverage by Bearer (DL)

{C5A270AA-15A1-443D-BBCB-77B1B99D447F}

Version  : 2.7.1

Coverage by Bearer (UL)

{A07FB550-64C7-4D2A-B634-79FC6A981828}

Version  : 2.7.1

Coverage by Throughput (DL)

{645C7166-CE00-4EFB-B9AF-A7F25A3BBBA6}

Version  : 2.7.1

Coverage by Throughput (UL)

{1A8B4ACB-8D51-49AA-AA67-3ADAB48F09B6}

Version  : 2.7.1


{4A9ED8C5-F2DE-432B-8507-C65A3DFE47E3}

Version  : 3.2.0


{C5A270AA-15A1-443D-BBCB-77B1B99D447F}


{A07FB550-64C7-4D2A-B634-79FC6A981828}


AT332_TAG_E0

Name

Type


{9C91F601-0B1D-4F60-A983-160A93349377}

Coverage by Quality Indicator (DL)

{B682A005-CCC2-4C7C-A9FA-D2FEBA633E15}

Coverage by Quality Indicator (UL)

{E648833C-48E1-49C0-A56F-6B94DBA9C358}

Cell Identifier Collision Zones (DL)

{408A1234-37D0-42A7-8CF1-6E3E5239D6AC}

Attributes

LTE Coverage Predictions Name

Type

Attributes


{BE607087-CB08-453C-B2A0-B356CD38C3F5}

Version  : 2.8.0


{9C602E1C-E5E7-44CA-8E5B-878D74D07885}

Version  : 2.8.0

Overlapping Zones

{86560A81-DE60-41CC-9B9E-83BF33CEF491}

Version  : 2.8.0


{6A657977-CF0E-415C-8486-C41664F7035E}

Version  : 2.8.0


{3F803866-1041-4267-8D28-FCA43445A642}

Version  : 2.8.0


{DCB4B756-4D02-42DB-B838-14A62F603922}

Version  : 2.8.0


{4163305D-E203-4A78-99F6-E59EA537AB7E}

Version  : 2.8.0

Coverage by Bearer (DL)

{C5A270AA-15A1-443D-BBCB-77B1B99D447F}

Version  : 2.8.0

Coverage by Bearer (UL)

{A07FB550-64C7-4D2A-B634-79FC6A981828}

Version  : 2.8.0



Version  : 2.8.0



Version  : 2.8.0



Version  : 2.8.0


{E648833C-48E1-49C0-A56F-6B94DBA9C358}

Version  : 2.8.0

Cell Identifier Collision Zones (DL)

{408A1234-37D0-42A7-8CF1-6E3E5239D6AC}


{9C91F601-0B1D-4F60-A983-160A93349377}


{A07FB550-64C7-4D2A-B634-79FC6A981828}


{C5A270AA-15A1-443D-BBCB-77B1B99D447F}


{4A9ED8C5-F2DE-432B-8507-C65A3DFE47E3}

3GPP Multi-RAT Predictions Name

Type


{1263E484-49FF-46AB-BEEF-A3D38381C1CF}


{7BF0DC41-ADE4-4ECC-9176-D4FBFB24BABD}

Attributes

CDMA Predictions Name

Type

Coverage by Transmitter (DL)



{B550F943-733A-4ECB-9E8A-EABB79FE5CD2}



Attributes

139



Name

Type

Overlapping Zones (DL)


Total Noise Level Analysis (DL)

{1C9384EB-57CA-433f-BDB3-07E1BE317890}

Inter-technology Interference Level Analysis (DL)

{CE1C2AE8-0F0A-4e54-A69E-F4569A73A1DF}

Pilot Quality Analysis (DL)

{66287FC5-81FA-40B6-84E3-2C2C4E13D121}

Service Area Analysis (Eb/Nt) (DL)

{5C6427F7-D63A-4046-B8BD-1A5E9D165890}

Service Area Analysis (Eb/Nt) (UL)

{D75ADE37-FB8A-4693-A788-47109A913C29}

Effective Service Area Analysis (Eb/Nt) (DL+UL)

{5F74AEFA-2958-42CC-8244-C12DC19B26C3}

Handoff Zones (DL)

{39A63BBA-02EC-43E7-8523-07E29B519181}

Pilot Pollution Analysis (DL)

{2199E577-F3F5-4FFD-BCAB-0D748CA7CCD3}

PN Offset Collision Zones (DL)

{AC612067-A173-439e-BF7A-76B17933A30E}

Attributes

Wi-Fi Predictions Name

Type

Coverage by Transmitter (DL)

{BE607087-CB08-453C-B2A0-B356CD38C3F5}


{9C602E1C-E5E7-44CA-8E5B-878D74D07885}

Overlapping Zones (DL)

{86560A81-DE60-41CC-9B9E-83BF33CEF491}


{6A657977-CF0E-415C-8486-C41664F7035E}


{3F803866-1041-4267-8D28-FCA43445A642}


{DCB4B756-4D02-42DB-B838-14A62F603922}


{4163305D-E203-4A78-99F6-E59EA537AB7E}


{C5A270AA-15A1-443D-BBCB-77B1B99D447F}


{A07FB550-64C7-4D2A-B634-79FC6A981828}


{9C91F601-0B1D-4F60-A983-160A93349377}








{E648833C-48E1-49C0-A56F-6B94DBA9C358}

Attributes

11.4.1 General Properties These properties are available for all kinds of coverage predictions.

140

Name

Description

Attributes

DESCRIPTION

Comments


RESOLUTION

Resolution of the prediction, in meters.



AT332_TAG_E0

Name

Description

Attributes

LOCKED

Returns true when the prediction is locked for calculations, false otherwise.


ISEMPTY

Returns true when the prediction coverage is empty, false otherwise.


ISPERTRANSMITTER

Returns true when the prediction is per transmitter, false otherwise. The return value depends on the display field of the prediction.


URL

An empty string when the coverage prediction does not have external numerical results, otherwise the absolute path to the disk folder containing numerical results.

Version  : 3.2.1 Type: String Access: Read

RECEIVERHEIGHT

The receiver height.

NETWORK

Radio technology.

Version  : 3.3.1 Type: Floating point value Access: Read Version  : 3.3.1 Type: String Access: Read

11.4.2 Group, Filter, and Sort Properties These properties are called RECORDSETCONDITIONS, which are available for all kinds of coverage predictions. Name

Attributes

RECORDSETCONDITIONS

Version  : 2.7.0 PropertyContainer object

The following RECORDSETCONDITIONS are available: Name

Description

Attributes

GROUPBY

"Group By" part of the recordset conditions, applied to the Transmitters table.


FILTER

"Filter" part of the recordset conditions, applied to the Transmitters table.


SORT

"Sort" part of the recordset conditions, applied to the Transmitters table.


11.4.3 Non-Simulation-based Coverage Conditions These properties are called COVERAGECONDITIONS. Name

Attributes

COVERAGECONDITIONS

Version  : 2.7.0 PropertyContainer object

141



These properties are available for the following coverage predictions: •

•

•

•

GSM GPRS EDGE: • Coverage by Transmitter • Coverage by Signal Level • Overlapping Zones • Coverage by C/I Level • Interfered Zones • Coverage by GPRS/EDGE Coding Scheme • RLC/MAC Throughput/Timeslot • Application Throughput/Timeslot UMTS HSPA: • Coverage by Transmitter • Coverage by Signal Level • Overlapping Zones WiMAX (Version  : 2.7.1): • Coverage by Transmitter • Coverage by Signal Level • Overlapping Zones LTE (Version  : 2.8.0): • Coverage by Transmitter • Coverage by Signal Level • Overlapping Zones

The following COVERAGECONDITIONS are available:

142

Name

Description

Attributes

FIELDTYPE

The field type to base the prediction with. The values are: 1=Path Loss (dB); 2=Total Losses (dB); 3=Signal Level (dBm); 4=Signal Level (dBµV); 5=Signal Level (dBµV/m);


SERVERTYPE

The way to choose transmitters among available (active, not filtered) ones for the current coverage prediction. The values are: 0=All; 1=Best Signal Level; 2=Second Best Signal Level; For GSM GPRS EDGE documents, the following values are also available: 3=Best Signal Level per HCS Layer; 4=Second Best Signal per HCS Layer; 5=Best Signal Level of the Highest Priority HCS Layer; 6=Best Idle Mode Reselection Criterion (C2);


SERVERMARGIN

The margin (in dB) from the best server signal level and signal level from other servers taking part into the current coverage (available only if the best signal level or highest priority option is selected) e.g.: If the two best server signal levels are within the margin, these are both considered in the coverage area.

Version  : 2.7.0 Type: Single Access: Read/Write

TRXTYPE

GSM GPRS EDGE: The TRX type to take into account for the current coverage prediction (BCCH, TCH, TCH_EGPRS, TCH_INNER). UMTS HSPA: The carrier number to take into account for the current coverage prediction (ALL=Best; 0=Carrier number 0; 1=Carrier number 1; 2=Carrier number 2;)

Version  : 2.7.0 Type: PropertyContainer object Access: Read/Write

USESUBCELLRECEPTIONTHRESHOLD

Whether to use the lower reception threshold defined for the transmitter subcell or not. When set to True, the FIELDMINIMUM property is ignored.


FIELDMINIMUM

The coverage prediction lower threshold associated with the FIELDTYPE property. When set to -32768, no minimum value will be considered.


FIELDMAXIMUM

The coverage prediction upper threshold associated with the FIELDTYPE property. When set to 32767, no maximum value will be considered.



AT332_TAG_E0

11.4.4 Simulation-based Coverage Conditions These properties are called SIMULATIONCONDITIONS. Name

Attributes

SIMULATIONCONDITIONS

Version  : 2.7.0 Type: PropertyContainer object

These properties are available for the following coverage predictions: •

•

•

UMTS HSPA: • Coverage by Total Noise Level (DL) • Pilot Quality Analysis (Ec/Io) • Service Area Analysis (Eb/Nt) (DL) • Service Area Analysis (Eb/Nt) (UL) • Effective Service Area Analysis (Eb/Nt) (DL+UL) • Handoff Zones • Pilot Pollution Analysis • HSDPA Quality and Throughput Analysis • HSUPA Quality and Throughput Analysis • Scrambling Code Collision Zones WiMAX: • Coverage by C/(I+N) Level (DL) • Coverage by C/(I+N) Level (UL) • Coverage by Bearer (DL) • Coverage by Bearer (UL) • Coverage by Throughput (DL) • Coverage by Throughput (UL) LTE (Version  : 2.8.0): • Coverage by C/(I+N) Level (DL) • Coverage by C/(I+N) Level (UL) • Coverage by Bearer (DL) • Coverage by Bearer (UL) • Coverage by Throughput (DL) • Coverage by Throughput (UL) • Coverage by Quality Indicator (DL) • Coverage by Quality Indicator (UL)

The following SIMULATIONCONDITIONS are available: Name

Description

Attributes

TERMINAL

The name of the terminal type used for the prediction.


MOBILITY

The name of the mobility type used for the prediction.


SERVICE

The name of the service used for the prediction.


SIMULATION

The name of the simulation used for the prediction. When set to an empty string, no simulation will be used to perform the prediction.


AVERAGESIMULATION

Whether the average simulation will be used to perform the prediction. This property is not relevant when the SIMULATION property is empty. This property is not available for WiMAX and LTE predictions.


143



Name

Description

Attributes

MINIMUMPROBABILITY

The minimum probability used to perform the prediction. This property is only relevant when the SIMULATION property is not empty and when the AVERAGESIMULATION property is set to False. This property is not available for WiMAX and LTE predictions.


CARRIER

The carrier number used to perform the prediction. This property is not available for WiMAX and LTE predictions.


DOWNGRADINGALLOWED

Whether downgrading will be considered to perform the prediction, or not. This property is not available for WiMAX and LTE predictions.


BEARER

The bearer used to perform the prediction. This property is only relevant for a HSDPA Prediction. This property is not available for WiMAX and LTE predictions.


11.4.5 Shadowing and Indoor Coverage Conditions These properties are called CLUTTERCONDITIONS. Name

Attributes

CLUTTERCONDITIONS


These properties are available for all kinds of coverage predictions: 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.


INDOORCOVERAGE

Whether to decrease the received signal level at the receiver of the indoor loss defined for the corresponding clutter class (clutter class properties)


EDGECOVERAGEPROBABILITY

A value between 0 and 100, expressing in percentage value the required coverage probability at the cell edge.


11.4.6 Display Properties Display properties for coverage predictions are accessed through a property named "DISPLAYPROPERTIES." The "DISPLAYPROPERTIES" property is a container object used to contain individual display properties. Name

Attributes

DISPLAYPROPERTIES


The properties available in the "DISPLAYPROPERTIES" property container are, for all kinds of coverage predictions: REPRESENTATION tabular data object The "REPRESENTATION" tabular data object contains attributes of intervals or values used to display the prediction on the map. This tabular data object can be edited to change, remove, or add display intervals or display values. The "REPRESENTATION" tabular data object is available as a "DISPLAYPROPERTIES" property named "REPRESENTATION"

144


AT332_TAG_E0

Name

Attributes

REPRESENTATION

Version  : 2.7.0 Type: TabularData object

The schema of the "REPRESENTATION" tabular data object is: Tabular Data Column Name

Description

Attributes

LINESTYLE

The style of the line used to display the interval or the value. The values are: 5=None; 0=Solid; 128=Solid Double Line; 1=Dash; 2=Dash Dot; 4=Dash Dot Dot;


LINEWIDTH

The width of the line used to display the interval or the value, expressed in tenth of a point. For instance, to have a line width of 0,5 pt, the LINEWIDTH property value must be set to 5.


FILLSTYLE

The graphical style used to fill the interior of the surface defined by the display interval or the display value. The values are: 0=None; 1=Full; 2=Horizontal; 3=Vertical; 4=Down Diagonal; 5=Up Diagonal; 6=Grid; 7=Treillis;


MAINCOLOR

The main color assigned to the display interval or the display value. The color format is RGB. See "Converting Integers to RGB and Vice-versa" on page 145.


SECONDARYCOLOR

The secondary color assigned to the display interval or the display value. The color format is RGB. See "Converting Integers to RGB and Vice-versa" on page 145.


SYMBOL

This property is not used to display a prediction interval or a prediction value.


SYMBOLSIZE

This property is not used to display a prediction interval or a prediction value.


VALUE

The text assigned to the display value. When the display type of the prediction is set to intervals, a Null value is returned.

Version  : 2.7.0 Type: String or Null Access: Read/Write

MINVALUE

The minimum value of the display interval. When the display type of the prediction is set to display unique or discrete values, a Null value is returned.

Version  : 2.7.0 Type: Double or Null Access: Read/Write

MAXVALUE

The maximum value of the display interval. When the display type of the prediction is set to display unique or discrete values, a Null value is returned.


Converting Integers to RGB and Vice-versa To convert Integer to RGB color components: Dim Red Dim Green Dim Blue Let Red = (color And &HFF)

145



Let Green = ((color \ 256) And &HFF) Let Blue = ((color \ 65536) And &HFF) To convert RGB colour components to Integer: Dim color Let color = (Red + Green * 256 + Blue * 65536) Other DISPLAYPROPERTIES properties DISPLAYPROPERTIES Property Name

Description

Attributes

TYPE

A value between 0 and 2 used to choose which value classes to display on the map for the current prediction: 0=Unique; 1=Discrete Values; 2=Value Intervals;


FIELD

The field title used to choose which coverage to display on the map. The field title must be compatible with the display type property.


TRANSPARENCY

A value between 0 and 100 used to adjust the level of transparency of the display interval or the display value.


11.5 GSM Simulation Group Properties The following properties are accessible for a GSM Monte Carlo simulation group. Name

Description

TRAFFICMAPS

The names of the traffic maps used by a simulation group.

NUMBEROFSIMULATIONS

The number of simulations in a simulation group.

EXECUTELATER

When set to true, the group of simulations will be run as part of the predictions calculation.

GLOBALSCALINGFACTOR

Global traffic densities weighting.

GENERATORINITIALISATION

The seed of the pseudo random number generator, used to obtain two identical user distributions.

MAXNUMBEROFITERATIONS

The maximum number of iterations if the convergence criteria cannot be reached.

Attributes Version  :3.2.1 Type: Array of Strings Access: Read/Write Version  :3.2.1 Type: Integer Access: Read/Write Version  :3.2.1 Type: Boolean Access: Read Version  :3.2.1

ULCONVERGENCETHRESHOLD (for Single-RATdocuments) GSMULCONVERGENCETHRESHOLD (for 3GPP Multi-RAT documents)

146

Type: Single Access: Read/Write Version  :3.2.1 Type: Integer Access: Read/Write Version  :3.2.1 Type: Integer Access: Read/Write Version  :3.2.1

The UL relative interference difference to reach between two iterative steps.

Type: Single Access: Read/Write


AT332_TAG_E0

Name DLCONVERGENCETHRESHOLD (for Single-RAT documents)

Description

Attributes Version  :3.2.1

The DL relative interference difference to reach between two iterative steps.


GSMDLCONVERGENCETHRESHOLD (for 3GPP Multi-RAT documents) ULCONVERGENCEINTERFERENCES

The UL noise rise relative interference to reach between two iterative steps.

DLCONVERGENCEPWRCTRLGAIN

The power control gain difference to reach DL between two iterative steps.

Version  :3.2.1 Type: Single Access: Read/Write Version  :3.2.1 Type: Single Access: Read/Write

11.6 UMTS Simulation Group Properties Type returned by get_ObjectKind: {AF5E2B98-1D54-48FA-89C5-8BFA2936ABF2} The following properties are accessible for a UMTS Monte Carlo simulation group. Name

Description

Attributes

TRAFFICMAPS


Type: Array of Strings Access: Read/Write

NUMBEROFSIMULATIONS



EXECUTELATER



INFORMATIONABOUTMOBILES

The type of outputs needed in the "Mobiles" tab of each simulation in the simulations group. Available values are: 0=Only the Average Simulation And Statistics; 1=No Information About Mobiles; 2=Standard Information About Mobiles; 3=Detailed Information About Mobiles;


BEARERRATEDOWNGRADING

When set to true, R99 bearer downgrading is allowed.


GLOBALSCALINGFACTOR









ULCONVERGENCETHRESHOLD

The UL relative interference difference to reach between two iterative steps.


DLCONVERGENCETHRESHOLD

The DL relative interference difference to reach between two iterative steps.


147



Name

Description

Attributes

CONSTRAINTNUMBEROFCES

When set to true, the maximum number of channel elements defined per site is respected.


CONSTRAINTNUMBEROFCODES

When set to true, OVSF codes availibility is checked.


CONSTRAINTULLOADFACTOR

When set to true, the maximum UL load factor is respected.


CONSTRAINTDLLOAD

When set to true, the maximum DL load is respected.


CONSTRAINTUSECELLMAXULLOADFA CTOR

When set to true, the maximum UL load factor is defined per cell.


CONSTRAINTUSECELLMAXDLLOAD

When set to true, the maximum DL load is defined per cell.


MAXULLOADFACTOR

Global UL load factor to impose to cells. Valid values are comprised between 0 (0%) and 1(100%).


MAXDLLOAD

Global DL load to impose to cells. Valid values are comprised between 0 (0%) and 1(100%).


IUBTHROUGHPUTS

Iub throughputs.


11.7 WiMAX and LTE Simulation Group Properties Type returned by get_ObjectKind: {AF5E2B98-1D54-48FA-89C5-8BFA2936ABF2} The following properties are accessible for a WiMAX or LTE Monte Carlo simulation group.

148

Name

Description

Attributes

TRAFFICMAPS


Version  : 2.8.1 Type: Array of Strings Access: Read/Write

SUBSCRIBERLISTS

The names of the subscriber lists used by a simulations group.

Version  : 2.8.1 Type: Array of Strings Access: Read/Write

NUMBEROFSIMULATIONS



EXECUTELATER



GLOBALSCALINGFACTOR




AT332_TAG_E0

Name

Description

Attributes







ULCONVERGENCETHRESHOLD

The UL relative traffic load difference to reach between two iterative steps.


DLCONVERGENCETHRESHOLD

The DL relative traffic load difference to reach between two iterative steps.


ULNOISERISECONVERGENCETHRESH OLD

The UL noise rise relative interference to reach between two iterative steps.


CONSTRAINTUSECELLMAXULTRAFFIC LOAD

When set to true, the maximum UL traffic load is defined per cell.


CONSTRAINTUSECELLMAXDLTRAFFIC LOAD

When set to true, the maximum DL traffic load is defined per cell.


MAXULTRAFFICLOAD

Global UL traffic load to impose to cells.


MAXDLTRAFFICLOAD

Global DL traffic load to impose to cells.


BACKHAULCAPACITY

NOISERISECONTROL

Backhaul Capacity

Noise Rise Control

Version  : 3.2.1 Type: Boolean Access: Read/Write Version  : 3.2.1 Type: Boolean Access: Read/Write

11.8 3GPP Multi-RAT Simulation Group Properties The following properties are accessible for a 3GPP Multi-RAT simulation group. In a 3GPP Multi-RAT document, you can access all the properties we have for all the technologies available in your document, except ULCONVERGENCETHRESHOLD and DLCONVERGENCETHRESHOLD which are prefixed with the technology name. Name

Description

Attributes

For GSM technology: The UL relative interference difference to reach between two iterative steps.

Version  :3.2.1

GSMULCONVERGENCETHRESHOLD

For GSM technology: The DL relative interference difference to reach between two iterative steps.

Version  :3.2.1

GSMDLCONVERGENCETHRESHOLD

Type: Single Access: Read/Write Type: Single Access: Read/Write

149



Name

Description

Attributes

For UMTS technology: UMTSULCONVERGENCETHRESHOLD The UL relative interference difference to reach between two iterative steps.

Version  :3.2.1

For UMTS technology: UMTSDLCONVERGENCETHRESHOLD The DL relative interference difference to reach between two iterative steps.

Version  :3.2.1

Type: Single Access: Read/Write Type: Single Access: Read/Write

Name

Description For LTE technology: The UL relative interference difference to reach between two iterative steps.

Version  :3.2.1

LTEULCONVERGENCETHRESHOLD

For LTE technology: The DL relative interference difference to reach between two iterative steps.

Version  :3.2.1

LTEDLCONVERGENCETHRESHOLD

Attributes Type: Single Access: Read/Write Type: Single Access: Read/Write

11.9 Standard Propagation Model Properties The Type returned by get_ObjectKind for the Propagation Models folder: {4A2D160B-7D11-4D07-92DF-A3CF6B68D402} get_ObjectKind is available for the Propagation Models folder for version  2.7.0. The Type returned by get_ObjectKind for the Standard Propagation Model: Atoll.StdPropagModel.1 get_ObjectKind is available for the Standard Propagation Model for version  2.7.0. The Standard Propagation Model properties are called MODELPROPERTIES. Name

Attributes

MODELPROPERTIES

The property container holding the propagation model parameters Version  : 2.7.0 Type: PropertyContainer object

The following MODELPROPERTIES are available for the Standard Propagation Model: Name

Description

Attributes

EFFECTIVEANTENNAHEIGHTMETHOD


EFFECTIVEANTENNAHEIGHTDISTANCEMIN

Version  : 2.7.0 Type: Double Access: Read/Write

EFFECTIVEANTENNAHEIGHTDISTANCEMAX


DIFFRACTIONMETHOD


CLUTTERLOSSES

150

Loss for each clutter class defined in the Atoll document. When there are no clutter classes, the Null value is returned, otherwise the size of the returned array is the number of clutter classes defined in the Atoll document.

Version  : 2.7.0 Type: Array of Single Access: Read/Write


AT332_TAG_E0

Name

Description

Attributes

CLUTTERCLEARANCES

Clearance for each clutter class defined in the Atoll document. When there are no clutter classes, the Null value is returned, otherwise the size of the returned array is the number of clutter classes defined in the Atoll document.


CLUTTERWEIGHTINGFUNCTION


CLUTTERMAXIMUMDISTANCE


K1


K2


K3


K4


K5


K6


KCLUTTER


NEARTRANSMITTERMAXIMUMDISTANCE


PROFILES


GRIDCALCULATION


CONSIDERCLUTTERHEIGHTSINDIFFRACTION


HILLYTERRAINCORRECTION


CLUTTERRECEIVERHEIGHTS

Height of the receiver for each clutter class defined in the Version  : 2.7.0 Atoll document. When there are no clutter classes, the Null Type: Array of Single value is returned, otherwise the size of the returned array is Access: Read/Write the number of clutter classes defined in the Atoll document.

151


Name


Description

Attributes

LIMITATIONTOFREESPACELOSS


RECEIVERONTOPOFCLUTTER

Version  : 2.7.0 Type: Integer Access: Read/Write Version  : 3.1.1 Type: Integer Access: Read/Write

LINEOFSIGHTONLY

11.10 CW Measurement Properties The Type returned by get_ObjectKind for the CW Measurements folder: SID_CW_MEASUREMENTS The following properties are accessible for the CW Measurements folder: Name

Description

Attributes

VECTORDATAFILTER

Advanced vector table filter, as it appears in CW Measurements folders properties.


The Type returned by get_ObjectKind for a CW Measurements subfolder: MeasureTx The following properties are accessible for a CW Measurements subfolder: Name

Description

Attributes

VECTORDATAFILTER

Advanced vector table filter, as it appears in CW Measurements subfolder properties.


The Type returned by get_ObjectKind for a CW Measurements item: MeasureItem The following properties are accessible for a CW Measurements item: Name

Description

Attributes

VECTORDATAFILTER

Advanced vector table filter, as it appears in CW Measurements item properties.


PREDICTIONMODEL

Name of a propagation model.

Type: String Access: Read/Write Type: String Access: Read/Write

HEADER TRANSMITTERNAME


TRANSMITTERFREQUENCY


RECEIVERHEIGHT


RECEIVERGAIN


RECEIVERLOSSES


VECTORDATA

152

Name of a transmitter.

Table content of the measurement path.

Type: TabularData object


AT332_TAG_E0

Name

Description

Attributes

TECHNOLOGYNAME

Technology name : "UMTS", "LTE", or "GSM"


11.11 Drive Test Data Properties The Type returned by get_ObjectKind for a Drive Test Data item: NumMeasureItem The following properties are accessible for a Drive Test Data item: Name

Description

Attributes

HEADER


RECEIVERHEIGHT


RECEIVERGAIN


RECEIVERLOSSES


VECTORDATA

Table content of the measurement path.

Type: TabularData object

11.12 Custom ChildFolder Object Properties The Type returned by get_ObjectKind for a custom ChildFolder object is the version dependent PROGID of the custom ChildFolder object. get_ObjectKind is accessible for the custom ChildFolder objects for version  2.7.0. The following properties are accessible for a custom ChildFolder object. Name

Description

Attributes

MODELPROPERTIES

The property container holding the custom ChildFolder object properties. The MODELPROPERTIES PropertyContainer object will contain properties exposed by the custom ChildFolder object .

Version  : 2.7.0 Type: PropertyContainer object Access: Read/Write

CANRENAME

Returns true when the custom ChildFolder object can be renamed. When false is returned, the "Rename" context menu option for the ChildFolder object is unavailable.


CANDELETE

Returns true when the custom ChildFolder object can be deleted. When false is returned, the "Delete" context menu option for the ChildFolder object is unavailable.


TRANSPARENCY

The global transparency between 0 and 100 associated with the custom ChildFolder object.


COMMENT

The comment string associated with the custom ChildFolder object.


153



11.13 Master Link Properties Master Link ChildFolder objects are located as top level items in either the Data tab or the Geo tab of the document explorer window. They are used to specify links from one ChildFolder object to another ChildFolder object (the target ChildFolder object), located in another Document object (the target Document object). The Type returned by get_ObjectKind for Master Link ChildFolder objects is : {16A53FB3-A961-4EEA-8C30-2387DBF1CC24} The following properties are accessible for Master Link ChildFolder objects. Name

Description

Attributes

TARGET

The target ChildFolder object. The Null value is returned when the target Document object is not opened in the current session.

Type: Object, or Null value. Access: Read

TARGETDOCUMENTFULLNAME

The full path to the target document .ATL file. An error is returned when the target file cannot be located.


11.14 Link Properties Link ChildFolder objects are children of Master Link ChildFolder objects. The Type returned by get_ObjectKind for Link ChildFolder objects is :

{232BDB73-A68F-41A6-A954-75112D907BBF} The following properties are accessible for Link ChildFolder objects. Name

Description

Attributes

TARGET

The target ChildFolder object. The Null value is returned when the target Document object is not opened in the current session.

Type: Object, or Null value. Access: Read

11.15 Vector Layer Properties The following properties are accessible for Vector Layer ChildFolder objects. Name

VECTORDATA

Description

The vector table of the vector layer.

DISPLAYPROPERTIES

The vector layer display properties.

COORDSYSTEMINTERNAL

The vector layer internal coordinate system to use to interpret vector geometries.

Attributes Version  : 3.2.1 Type: TabularData object Version  : 2.7.0 Type: PropertyContainer object Version  : 3.3.2 Type: Coordinate System object

11.15.1 Display Properties Display properties for vector layers are accessed through a property named "DISPLAYPROPERTIES." The "DISPLAYPROPERTIES "property is a container object used to contain individual display properties. The properties available in the "DISPLAYPROPERTIES" property container are, for all kinds of vector layers:

154


AT332_TAG_E0

REPRESENTATION tabular data object The "REPRESENTATION" tabular data object contains attributes of intervals or values used to display the vector layer on the map. This tabular data object can be edited to change, remove, or add display intervals or display values. The "REPRESENTATION" tabular data object is available as a "DISPLAYPROPERTIES" property named "REPRESENTATION"

DISPLAYPROPERTIES Property Name

Attributes

REPRESENTATION

Version  : 3.2.1 Type: TabularData object

The schema of the "REPRESENTATION" tabular data object is: Tabular Data Column Name

Description

Attributes

LINESTYLE

The style of the line used to display the interval or the value. The values are: 5=None; 0=Solid; 128=Solid Double Line; 1=Dash; 2=Dash Dot; 4=Dash Dot Dot;


LINEWIDTH

The width of the line used to display the interval or the value, expressed in tenth of a point. For instance, to have a line width of 0,5 pt, the LINEWIDTH property value must be set to 5.


FILLSTYLE

The graphical style used to fill the interior of the surface defined by the display interval or the display value. The values are: 0=None; 1=Full; 2=Horizontal; 3=Vertical; 4=Down Diagonal; 5=Up Diagonal; 6=Grid; 7=Treillis;


MAINCOLOR

The main color assigned to the display interval or the display value. The color format is RGB. See "Converting Integers to RGB and Vice-versa" on page 145.


SECONDARYCOLOR

The secondary color assigned to the display interval or the display value. The color format is RGB. See "Converting Integers to RGB and Vice-versa" on page 145.


SYMBOL

This property is not used to display a vector layer interval or a vector layer value.


SYMBOLSIZE

This property is not used to display a vector layer interval or a vector layer value.


VALUE

The text assigned to the display value. When the display type of the vector layer is set to intervals, a Null value is returned.

Version  : 3.2.1 Type: String or Null Access: Read/Write

MINVALUE

The minimum value of the display interval. When the display type of the vector layer is set to display unique or discrete values, a Null value is returned.


MAXVALUE

The maximum value of the display interval. When the display type of the vector layer is set to display unique or discrete values, a Null value is returned.


Converting Integers to RGB and Vice-versa To convert Integer to RGB color components: Dim Red

155



Dim Green Dim Blue Let Red = (color And &HFF) Let Green = ((color \ 256) And &HFF) Let Blue = ((color \ 65536) And &HFF) To convert RGB colour components to Integer: Dim color Let color = (Red + Green * 256 + Blue * 65536) Other DISPLAYPROPERTIES properties DISPLAYPROPERTIES Property Name

Description

Attributes

TYPE

A value between 0 and 2 used to choose which value classes to display on the map for the current vector layer: 0=Unique; 1=Discrete Values; 2=Value Intervals;


FIELD

The field title used to choose which coverage to display on the map. The field title must be compatible with the display type property.


TRANSPARENCY

A value between 0 and 100 used to adjust the level of transparency of the display interval or the display value.


11.16 Aster Propagation Model Properties An instance of the Aster Propagation Model is a ChildFolder object located in the Propagation Models folder of the document.

The Type returned by get_ObjectKind for the Propagation Models folder: {4A2D160B-7D11-4D07-92DF-A3CF6B68D402}

The Type returned by get_ObjectKind for Aster Propagation Model ChildFolder objects: AsterModel.Model.1

The Aster Propagation Model parameters are exposed using a property container object. This property container object is returned by the "MODELPROPERTIES" property of the ChildFolder object associated with the propagation model.

156

Name

Attributes

MODELPROPERTIES

The property container holding the Aster propagation model parameters Version  : 3.1.1 Type: PropertyContainer object


AT332_TAG_E0

The content of the MODELPROPERTIES property container reflects the content of Aster configuration files.. Aster configuration files are initialization files (.ini) where each parameter is identified by a section name and a key name: [Section name] Keyname=Value For each parameter in an Aster configuration file, there is a corresponding property in the MODELPROPERTIES property container. The type of all properties is String (VBScript) or VT_BSTR (C++). Properties are named after the parameter section name and the parameter key name. The section name is put inside square brackets.

Property Name: [SectionName]Keyname Property Type: C++ : VT_BSTR VBScript : String

11.17 KPI Item Properties TABLENAME

PARENTTABLENAME

TXTABLENAME

Version  : 3.3.1 C++ Type: VT_BSTR Version  : 3.3.1 C++ Type: VT_BSTR Version  : 3.3.1 C++ Type: VT_BSTR

157


158


Chapter 12 ChildFolder Feature Objects


160

Atoll 3.3.2 Task Automation Guide Chapter 12: ChildFolder Feature Objects

AT332_TAG_E0

12 ChildFolder Feature Objects Feature objects offer features closely tied to some Atoll document folders. The following ChildFolder Feature objects are available through the Dispatch property of ChildFolder objects of Atoll document folders: • • • • • •

"Clutter Feature Object" on page 161, "Traffic Feature Object" on page 164, "UMTS Traffic Scenario Provider Object" on page 167, "Environment Based Traffic Map Feature Object" on page 169, "Simulation Feature Object" on page 171, "Simulation Group Feature Object" on page 174.

12.1 Clutter Feature Object The Clutter Feature object gives access to clutter classes properties. It is available for all Atoll documents. It is associated with the Clutter Classes folder of an Atoll document. The Clutter Feature object provides the following properties and methods: Name

Description

get_Source

Returns the Clutter Classes ChildFolder object.

get_ClassAttributes

Returns a TabularData object holding the clutter class attributes.

get_DefaultAttributes

Returns a TabularData object holding the clutter class default values.

Attributes

12.1.1 How to Access the Clutter Feature Object The ObjectKind property for the Clutter Classes folder is: {7CB51DE8-A961-11D2-8688-0060086457D1} Sample code to access the Clutter Feature object: ’ Returns the clutter feature object of the ’doc’ Atoll document object Public Function ClutterFeatureObject(doc) Const OBJECTKIND_CLUTTER = "{7CB51DE8-A961-11D2-8688-0060086457d1}" Const atoGeo = 1 Dim oClutterClasses Set oClutterClasses = doc.GetRootFolder(atoGeo).Item(OBJECTKIND_CLUTTER) Set ClutterFeatureObject = oClutterClasses.Dispatch End Function

12.1.2 get_Source Returns the Clutter Classes ChildFolder object. HRESULT get_Source(IDispatch **ppSource); Parameters [out] ppSource: Address of the IDispatch interface pointer used to return the Clutter Classes ChildFolder object.

161



12.1.3 get_ClassAttributes Returns a TabularData object holding the clutter class attributes. HRESULT get_ClassAttributes(ITabularData **ppTable); Parameters [out] ppTable: Address of the ITabularData interface pointer used to return the clutter class attributes. The content of the TabularData object returned is the same as the content of the "Description" property page for the Clutter Classes folder of an Atoll document, it is dependent on the type of the project template used by the Atoll document. Remarks The number of rows in the tabular data object returned depends on the state of the "Use only default values" checkbox. When the "Use only default values" checkbox is checked, the number of rows returned is always 1, the tabular data object returned is the same as the one returned by get_DefaultAttributes. Version:  3.1.0 The schema of the tabular data object returned by get_ClassAttributes does not depend on the state of the "Use only default value" checkbox. Whether the project is configured to use only default clutter class values or not, get_ClassAttributes returns values used in calculations, in a consistent manner: The number of rows or columns are the same in both cases. Columns data types are the same in both cases. To determine whether the "Use only default values" checkbox is checked or not, one can test the value returned by get_CanEdit on the tabular data object returned by get _ClassAttributes. When using only default values, the tabular data object returned is read-only, and get_CanEdit output value is VARIANT_FALSE.

12.1.4 get_DefaultAttributes Returns a TabularData object holding the clutter class default values. HRESULT get_DefaultAttributes(ITabularData **ppTable); Parameters [out] ppTable: Address of the ITabularData interface pointer used to return the clutter class default values. The content of the TabularData object returned is the same as the content of the "Default Values" property page for the Clutter Classes folder of an Atoll document, it is dependent on the type of the project template used by the Atoll document.

12.1.5 Accessing Clutter Class Attributes Sample macro to output the various clutter class attributes to the Atoll event viewer: Private Function ClutterFeatureObject(doc) Const OBJECTKIND_CLUTTER = "{7CB51DE8-A961-11D2-8688-0060086457d1}" Const atoGeo = 1 Dim oClutterClasses Set oClutterClasses = doc.GetRootFolder(atoGeo).Item(OBJECTKIND_CLUTTER) Set ClutterFeatureObject = oClutterClasses.Dispatch End Function Private Sub DumpTable(t)

162


AT332_TAG_E0

Dim c Dim r Dim values() For r = 0 To t.RowCount Redim values(t.ColumnCount) For c = 0 To t.ColumnCount values(c) = t.GetValue(r, c) If IsNull(values(c)) Then values(c) = "(Null)" End If If IsEmpty(values(c)) Then values(c) = "(Empty)" End If If IsArray(values(c)) Then values(c) = "(Array)" End If Next LogMessage Join(values, ";") Next End Sub Public Sub DumpClutterAttributes Dim f Set f = ClutterFeatureObject(ActiveDocument) Dim classattrs Dim defaultattrs Set classattrs = f.ClassAttributes LogMessage "Clutter Class Attributes..." DumpTable(classattrs) LogMessage "End Class Attributes." Set defaultattrs = f.DefaultAttributes LogMessage "Clutter Class Default Attributes..." DumpTable(defaultattrs) LogMessage "End Clutter Class Default Attributes."

163



End Sub

12.2 Traffic Feature Object The Traffic Feature object gives access to features associated with the traffic folder, such as the export of the cumulated traffic. It is available for all Atoll documents except Microwave Links documents. It is associated with the Traffic folder of an Atoll document. The Traffic Feature object provides the following properties and methods: Name

Description

get_Source

Returns the Traffic ChildFolder object.

get_ScenarioProvider

Creates a new Traffic Scenario Provider object instance.

ExportCumulatedTraffic

Exports the cumulated traffic.

HasTrafficForService

Determines if a traffic map contains traffic information for a given service.

Attributes

12.2.1 How to Access the Traffic Feature Object The ObjectKind property for the Traffic folder is: {B3B25A07-A994-4E8D-BBD1-51556D6C4245} Sample code to access the Traffic Feature Object: ' Returns the traffic feature object of the ’doc’ Atoll document object Public Function TrafficFeatureObject(doc) Const OBJECTKIND_TRAFFIC = "{B3B25A07-A994-4E8D-BBD1-51556D6C4245}" Const atoGeo = 1 Dim oTraffic Set oTraffic = doc.GetRootFolder(atoGeo).Item(OBJECTKIND_TRAFFIC) Set TrafficFeatureObject = oTraffic.Dispatch End Function

12.2.2 get_Source Returns the Traffic ChildFolder object. HRESULT get_Source(IDispatch **ppSource); Parameters [out] ppSource: Address of the IDispatch interface pointer used to return the Traffic ChildFolder object.

12.2.3 get_ScenarioProvider Creates a new Traffic Scenario Provider object instance. See "UMTS Traffic Scenario Provider Object" on page 167 for more information on the UMTS Traffic Scenario Provider object. HRESULT get_ScenarioProvider(ITrafficScenarioProvider **ppProvider);

164


AT332_TAG_E0

Parameters [out] ppProvider: Address of the ITrafficScenarioProvider interface pointer used to return a new Traffic Scenario Provider object instance. Remarks An error is returned when this method is called for an Atoll document not based on the UMTS HSPA template.

12.2.4 ExportCumulatedTraffic Exports the cumulated traffic. typedef enum _AtoRegion { atoEntireProjectArea = 0, atoComputationZone = 1 } _AtoRegion; typedef _AtoRegion AtoRegion; typedef enum _AtoDirection { atoUplinkDownlink = 0, atoUplink = 1, atoDownlink = 2, } _AtoDirection; typedef _AtoDirection AtoDirection; HRESULT ExportCumulatedTraffic( BSTR bstrFileName, enum _AtoRegion atoRegion, BSTR bstrTerminal, BSTR bstrMobility, BSTR bstrService, VARIANT vTrafficMaps, long lResolution, enum _AtoDirection atoDirection ); Parameters [in] bstrFileName: A BSTR used to specify the absolute file path used to export the cumulated traffic. The BIL file format is used to export the cumulated traffic. [in] atoRegion:

165



An AtoRegion enumeration value used to specify the area used to export the cumulated traffic: atoEntireProjectArea : The entire project area atoComputationZone : The computation zone [in] bstrTerminal: A BSTR used to specify the terminal name used to export the cumulated traffic. If "(ALL)" is specified, then all terminals are used to export the cumulated traffic. [in] bstrMobility: A BSTR used to specify the mobility name used to export the cumulated traffic. If "(ALL)" is specified, then all mobilitiesare used to export the cumulated traffic. [in] bstrService: A BSTR used to specify the service name used to export the cumulated traffic. If "(ALLCS)" is specified, then all circuit services are used to export the cumulated traffic. If "(ALLPS)" is specified, then all packet services are used to export the cumulated traffic. [in] vTrafficMaps: A VARIANT used to specify the traffic maps used to export the cumulated traffic. The type of the VARIANT must be VT_ARRAY | VT_VARIANT with VARIANTs of type VT_BSTR. The VARIANT array contains the names of the traffic maps. [in] lResolution: A long used to specify the resolution in meter used to export the cumulated traffic. [in] atoDirection: An AtoDirection enumeration value used to specify the kind of traffic used to export the cumulated traffic.

12.2.5 HasTrafficForService Determines if a traffic map contains traffic information for a given service. HRESULT HasTrafficForService( BSTR bstrServiceName, enum _AtoDirection atoDirection, IChildFolder* pTrafficMap, VARIANT_BOOL* pHasTraffic ); Parameters [in] bstrServiceName: A BSTR used to specify the a service name. [in] atoDirection: An AtoDirection enumeration value used to specify the kind of traffic to look for: atoUplinkDownlink (= 0) : Uplink and downlink traffic atoUplink (= 1) : Uplink traffic atoDownlink(=2) : Downlink traffic [in] pTrafficMap: A IChildFolder interface pointer used to specify the traffic map ChildFolder object. The traffic map is searched for traffic information related to the bstrServiceName service. This parameter may be NULL. In this case, all traffic maps in the traffic map folder are searched.

166


AT332_TAG_E0

[out] pHasTraffic: A pointer to a VARIANT_BOOL value used to return whether the traffic map specified by pTrafficMap has some traffic information for the service specified by bstrServiceName.

Remark When HasTrafficForService returns VARIANT_FALSE, the traffic map is guaranteed not to contain traffic information for the When HasTrafficForService returns VARIANT_TRUE, the traffic map still may not contain traffic information for the given service.

12.3 UMTS Traffic Scenario Provider Object The traffic scenario provider allows developing external UMTS simulation modules. Raw mobile data is generated by Atoll and provided to the external UMTS simulator through this object. The Traffic Scenario Provider object provides the following properties and methods: Name

Description

GetMeanSize

Returns the average count of mobiles.

Create

Creates raw mobile data.

Attributes

12.3.1 GetMeanSize Returns the average count of mobiles. HRESULT GetMeanSize( const VARIANT aSelectedMapsNames, double dScale, const VARIANT aReserved, ULONG *pMobilesCount ); Parameters [in] aSelectedMapsNames: A VARIANT value used to specify the names of the traffic environment maps. The type of the VARIANT must be VT_ARRAY | VT_UI1, it contains the names of the traffic environment maps, separated by the ASCII character code 0. [in] dScale: A double value used to specify the scaling factor used in the determination of the mobiles count. [in] aReserved: A VARIANT value reserved for future use. The VARIANT type must be VT_EMPTY. [out] pMobilesCount: Address of the ULONG integer used to return the average count of mobiles.

12.3.2 Create Creates raw mobile data. The mobiles data is returned as a TabularData object containing the position of the mobiles and other information related to the state of mobiles.

167



HRESULT Create( const VARIANT aSelectedMapsNames, double dScale, enum AtoTrafficScenarioLaw aLaw, const VARIANT aRreserved, ITabularData **ppMobiles ); Parameters [in] aSelectedMapsNames: A VARIANT value used to specify the names of the traffic maps. The type of the VARIANT must be VT_ARRAY | VT_UI1, it contains the names of the traffic maps, separated by the ASCII character code 0. [in] dScale: A double value used to specify the scaling factor used in the determination of the mobiles count. The scaling factor is relative to the average size of mobiles, as returned by GetMeanSize. [in] aLaw: The AtoTrafficScenarioLaw enumeration value used to specify the law of probability used to get a random count of mobiles. [in] aReserved: A VARIANT value used to specify additional parameters. Atoll version < 2.7.0: The VARIANT type must be VT_EMPTY. Atoll version >= 2.7.0: When the VARIANT type is VT_DISPATCH, it is interpreted as a PropertyContainer object, implementing the IPropertyContainer2 interface. The property container object may contain the properties: • • •

Name: RANDOMSEED Type: VT_I4 Description: An integer value used to specify the random seed of the pseudorandom number generator used to determine the average count of mobiles, and the mobiles positions.

[out] ppMobiles: Address of the ITabularData interface pointer used to return the position of the mobiles and other information related to the state of mobiles. The tabular data schema is:

168

Column Name

Value

Type

Description

X

X coordinate

Long

Expressed in the document projection coordinate system

Y

Y coordinate

Long

Expressed in the document projection coordinate system

SERVICE

Service name

String

From the UMTSServices table

TERMINAL

Terminal name

String

From the UMTSTerminals table

MOBILITY

Mobility type

String

From the UMTSMobility table

CLUTTER

Clutter code

Short

From the IClutter interface

ACTIVITY

Mobile activity

String

"Active DL", "UL", "UL+DL"


AT332_TAG_E0

12.4 Environment Based Traffic Map Feature Object User profile environment based traffic map feature objects give access to user profile environment based traffic maps attributes. They are available for all Atoll documents except Microwave Links documents. They are associated with user profile environment base traffic maps contained in the Traffic folder of an Atoll document. The User Profile Environment Based Traffic Map Feature object provides the following properties and methods: Name

Description

get_Source

Return the Traffic Map ChildFolder object associated with the Traffic Map per Environment Feature object.

get_ClassAttributes

Returns a TabularData object holding the traffic map environment attributes.

get_DefaultAttributes

Not implemented

12.4.1 How to Access Environment Based Traffic Map Feature Objects The ObjectKind property for User Profile Environment Based Traffic Maps is:

{E8784A75-AE03-4F4F-B923-6E8BF20725C5} The User Profile Environment Based Traffic Map Feature object for a user profile environment based traffic map is returned by the Dispatch property of the user profile environment based traffic map ChildFolder object.

12.4.2 get_Source Return the User Profile Environment Base Traffic Map ChildFolder object associated with the User Profile Environment Based Traffic Map Feature Object. HRESULT get_Source(IDispatch **ppSource); Parameters [out] ppSource: Address of the IDispatch interface pointer used to return the User Profile Environment Based Traffic Map ChildFolder Object.

12.4.3 get_ClassAttributes Returns a TabularData object holding the user profile environment based traffic map attributes. HRESULT get_ClassAttributes(ITabularData **ppTable); Parameters [out] ppTable: Address of the ITabularData interface pointer used to return the user profile environment based traffic map attributes. The content of the TabularData object is the same as the one shown on the "Description" property page of user profile environment based traffic maps property sheet.

12.4.4 get_DefaultAttributes HRESULT get_DefaultAttributes(ITabularData **ppTable); Remarks This method is not implemented. Please don’t use this method.

169



12.4.5 Accessing Environment Based Traffic Maps Attributes Private Function TrafficMapPerEnvironmentFeatureObjects(doc) Const SID_TRAFFICFOLDER = "{B3B25A07-A994-4E8D-BBD1-51556D6C4245}" Const OKIND_MAP_PER_ENVIRONMENT = "{E8784A75-AE03-4F4F-B923-6E8BF20725C5}" Const atoGeo = 1 Dim maps() Dim oTrafficFolder On Error Resume Next Set oTrafficFolder = doc.GetRootFolder(atoGeo).Item(SID_TRAFFICFOLDER) If Err Then On Error Goto 0 Else On Error Goto 0 Dim i Dim n n = 0 For i = 0 To oTrafficFolder.Count - 1 Dim map Set map = oTrafficFolder.Item(i) If map.ObjectKind = OKIND_MAP_PER_ENVIRONMENT Then Redim Preserve maps(n) Set maps(n) = map.Dispatch n = n + 1 End If Next End If TrafficMapPerEnvironmentFeatureObjects = maps End Function Private Sub DumpTable(t) Dim c Dim r Dim values()

170


AT332_TAG_E0

For r = 0 To t.RowCount Redim values(t.ColumnCount) For c = 0 To t.ColumnCount values(c) = t.GetValue(r, c) If IsNull(values(c)) Then values(c) = "(Null)" End If If IsEmpty(values(c)) Then values(c) = "(Empty)" End If If IsArray(values(c)) Then values(c) = "(Array)" End If Next LogMessage Join(values, ";") Next End Sub Public Sub DumpTrafficMapPerEnvironmentAttributes Dim maps maps = TrafficMapPerEnvironmentFeatureObjects(ActiveDocument) Dim oFeature For Each oFeature In maps LogMessage "Traffic Map Per Environment [" & oFeature.Source.Name & "]..." Dim attrs Set attrs = oFeature.ClassAttributes DumpTable(attrs) LogMessage "End Traffic Map Per Environment." Next End Sub

12.5 Simulation Feature Object Simulation Feature objects give access to simulation results. They are associated with Simulation ChildFolder objects.

171



Simulation Feature objects are available in Atoll documents based on the templates: • • • • •

UMTS HSPA LTE CDMA 2000 1xRTT 1xEV-DO WiMAX 802.16e TD-SCDMA

• • The Simulation Feature object provides the following properties and methods: Name

Description

get_Source

Returns the associated Simulation ChildFolder object.

get_Statistics

Returns a TabularData object holding the results as presented in the "Statistics" property page of the simulation property sheet.

get_Cells

Returns a TabularData object holding the results as presented in the "Cells" property page of the simulation property sheet.

get_Sites

Returns a TabularData object holding the results as presented in the "Sites" property page of the simulation property sheet.

get_Mobiles

Returns a TabularData object holding the results as presented in the "Mobiles" property page of the simulation property sheet.

get_Results

Returns a TabularData object holding the required results, depending on the parameter passed to this method.

Attributes

12.5.1 How to Access Simulation Feature Objects The ObjectKind property for the Simulation ChildFolder objects is: {095C5D90-96F1-4BA8-85BB-B2F990AC2DD9} Simulation ChildFolder objects are child of Simulation Groups ChildFolder objects. Simulation Feature objects are available through the Dispatch property of Simulation ChildFolder objects: Dim oSimulation Dim oSimulationChildFolder Set oSimulation = oSimulationChildFolder.Dispatch

12.5.2 get_Source Returns the associated Simulation ChildFolder object. HRESULT get_Source(IDispatch **ppSource); Parameters [out] ppSource: Address of the IDispatch interface pointer used to return the associated Simulation ChildFolder object. Remarks For a Simulation Feature object returned by a Simulation Group Feature object method, there is no associated ChildFolder object, and the behaviour of this method is undefined.

12.5.3 get_Statistics Returns a TabularData object holding the results as presented in the "Statistics" property page of the simulation property sheet.

172


AT332_TAG_E0

HRESULT get_Statistics(ITabularData **ppTable); Remarks This method is not implemented, except for UMTS simulations. Please don’t use this method unless you’re working with a UMTS simulation.

12.5.4 get_Cells Returns a TabularData object holding the results as presented in the "Cells" property page of the simulation property sheet. HRESULT get_Cells(ITabularData **ppResults); Parameters [out] ppResults: Address of the ITabularData interface pointer used to return the "Cells" simulation results.

12.5.5 get_Sites Returns a TabularData object holding the results as presented in the "Sites" property page of the simulation property sheet. HRESULT get_Sites(ITabularData **ppResults); Parameters [out] ppResults: Address of the ITabularData interface pointer used to return the "Sites" simulation results.

12.5.6 get_Mobiles Returns a TabularData object holding the results as presented in the "Mobiles" property page of the simulation property sheet. HRESULT get_Mobiles(ITabularData **ppResults); Parameters [out] ppResults: Address of the ITabularData interface pointer used to return the "Mobiles" simulation results. Remarks The content of the TabularData object returned depends on the "Information to retain" setting of the simulation. In particular, when the information to retain is "No Information About Mobiles", the number of mobiles returned in the TabularData object is 0. All mobiles are returned, the focus zone is not taken into account.

12.5.7 get_Results Returns a TabularData object holding the required results. HRESULT get_Results(enum AtoSimulationResultsType aType, ITabularData **ppResults); Parameters [in] aType : An AtoSimulationResultsType enumeration value, used to specify the simulation results to return. Enumeration values are:

173



atoSimulationResultsStatistics

0

atoSimulationResultsCells

1

atoSimulationResultsSites

2

atoSimulationResultsMobiles

3

atoSimulationResultsGsmSubCells

100

atoSimulationResultsGsmTRXs

101

Returns a TabularData object holding the results as presented "Statistics" property page of the simulation property sheet. Returns a TabularData object holding the results as presented "Cells" property page of the simulation property sheet. Returns a TabularData object holding the results as presented "Sites" property page of the simulation property sheet. Returns a TabularData object holding the results as presented "Mobiles" property page of the simulation property sheet. Returns a TabularData object holding the results as presented "SubCells" property page of the simulation property sheet. Returns a TabularData object holding the results as presented "TRXs" property page of the GSM simulation property sheet.

in the in the in the in the in the in the

Atoll version >= 3.3.1

atoSimulationResultsMobilesOnFocusZone

4

Returns a TabularData object holding the results as presented in the "Mobiles" property page of the simulation property sheet. Here the mobiles returned are restricted to the ones contained in the document focus zone.

[out] ppResults: Address of the ITabularData interface pointer used to return the simulation results.

12.6 Simulation Group Feature Object Simulation Group Feature objects give access to group of simulations properties. An Atoll document can contain zero, one, or more group of simulations. In turn, simulation groups can contain zero or more simulations. They are located in the "Simulations" folder of the Atoll document. Simulation Group Feature objects are associated with group of simulations ChildFolder objects of an Atoll document. Simulation Group Feature objects are available in Atoll documents based on the templates: • • • • •

UMTS HSPA LTE CDMA 2000 1xRTT 1xEV-DO WiMAX 802.16e TD-SCDMA

The Simulation Group Feature object provides the following properties and methods: Name

Description

get_Source

Returns the associated Simulation Group ChildFolder object.

get_Statistics

Returns a TabularData object holding the statistics of the simulation group.

get_MeanSimulation

Returns a Simulation Feature object giving access to the average simulation properties.

get_StdDevSimulation

Returns a Simulation Feature object used to access the standard deviation simulation properties.

12.6.1 How to Access Simulation Group Feature Objects The ObjectKind property for Group of Simulations folder is: {AF5E2B98-1D54-48FA-89C5-8BFA2936ABF2} Sample code to access Simulation Group Feature objects: ’ Returns ’True’ if there is at least one group of simulations in ’doc’,

174

Attributes


AT332_TAG_E0

’ ’False’ otherwise ’ Params: ’

[in] doc : Atoll document object

’

[out] array: Array of simulation group feature objects

Private Function SimulationGroupFeatureObjects(doc, ByRef array) Const OBJECTKIND_SIMULATIONS = "{CDDF1E1D-1963-4D80-A057-D23A19570984}" Const OBJECTKIND_SIMULATIONGROUP 8BFA2936ABF2}"

=

"{AF5E2B98-1D54-48FA-89C5-

Const atoData = 0 Dim oSimulations ’ oSimulations is the "Simulations" ChildFolder object On Error Resume Next Set oSimulations = doc.GetRootFolder(atoData).Item(OBJECTKIND_SIMULATIONS) If Err Then ’ There is no "Simulations" folder On Error Goto 0 SimulationGroupFeatureObjects = False Exit Function End If On Error Goto 0 If oSimulations.Count = 0 Then SimulationGroupFeatureObjects = False Exit Function End If Redim array(oSimulations.Count - 1) Dim oSimulationGroup Dim n n = 0 ’ "Simulation Group" ChildFolder objects are located ’ in the "Simulations" folder For Each oSimulationGroup In oSimulations If oSimulationGroup.ObjectKind = OBJECTKIND_SIMULATIONGROUP Then Set array(n) = oSimulationGroup.Dispatch n = n + 1

175



End If Next SimulationGroupFeatureObjects = True End Function

12.6.2 get_Source Returns the associated Simulation Group ChildFolder object. HRESULT get_Source(IDispatch **ppSource); Parameters [out] ppSource: Address of the IDispatch interface pointer used to return the associated Simulation Group ChildFolder object.

12.6.3 get_Statistics Returns a TabularData object holding the statistics of the simulation group. HRESULT get_Statistics(ITabularData **ppTable); Remarks This method is not implemented. Please don’t use this method.

12.6.4 get_MeanSimulation Returns a Simulation Feature object giving access to the average simulation properties. HRESULT get_MeanSimulation(ISimulation **ppMeanValues); Parameters [out] ppMeanValues: Address of the ISimulation interface pointer used to return the Simulation Feature object corresponding to the average simulation. Remarks The returned Simulation Feature object is not associated with a particular ChildFolder object in the Atoll document. An error is returned when no simulation in the simulation group has converged. The average simulation is not available when no simulation in the simulation group has converged. An error is returned when the simulation group has not been calculated yet, for instance when the simulation group has been created with the check box "Execute Later" set.

12.6.5 get_StdDevSimulation Returns a Simulation Feature object used to access the standard deviation simulation properties. HRESULT get_StdDevSimulation(ISimulation **ppStdDevValues); [out] ppStdDevValues: Address of the ISimulation interface pointer used to return the Simulation Feature object corresponding to the standard deviation simulation. Remarks The returned Simulation Feature object is not associated with a particular ChildFolder object in the Atoll document.

176


AT332_TAG_E0

An error is returned when no simulation in the simulation group has converged. The standard deviation simulation is not available when no simulation in the simulation group has converged. An error is returned when the simulation group has not been calculated yet, for instance when the simulation group has been created with the check box "Execute Later" set. An error is returned when the Atoll document is based on the LTE, WiMAX 802.16e templates. The standard deviation simulation is not available for LTE and WiMAX.

12.6.6 Accessing Mobiles, Cells, Sites, for Simulations and Simulation Groups Here is a sample macro used to display the various available results for simulation groups and simulations in the Atoll event viewer, for the active document: ’ Returns ’True’ if there is at least one group of simulation in ’doc’, ’ ’False’ ’ otherwise ' Params: '

[in] doc : Atoll document object

'

[out] array: Array of simulation group feature objects

Private Function SimulationGroupFeatureObjects(doc, ByRef array) Const OBJECTKIND_SIMULATIONS = "{CDDF1E1D-1963-4D80-A057-D23A19570984}" Const OBJECTKIND_SIMULATIONGROUP 8BFA2936ABF2}"

=

"{AF5E2B98-1D54-48FA-89C5-

Const atoData = 0 Dim oSimulations ' oSimulations is the "Simulations" ChildFolder object On Error Resume Next Set oSimulations = doc.GetRootFolder(atoData).Item(OBJECTKIND_SIMULATIONS) If Err Then ' There is no "Simulations" folder On Error Goto 0 SimulationGroupFeatureObjects = False Exit Function End If On Error Goto 0 If oSimulations.Count = 0 Then SimulationGroupFeatureObjects = False Exit Function End If Redim array(oSimulations.Count - 1)

177



Dim oSimulationGroup Dim n n = 0 ’ "Simulation Group" ChildFolder objects are located ’ in the "Simulations" folder For Each oSimulationGroup In oSimulations If oSimulationGroup.ObjectKind = OBJECTKIND_SIMULATIONGROUP Then Set array(n) = oSimulationGroup.Dispatch n = n + 1 End If Next SimulationGroupFeatureObjects = True End Function ’ Returns 'True' if there is at least one simulation in 'oSimulationGroup', ’ ’False’ otherwise ’ Params: ’

[in] oSimulationGroup : Group of simulations ChildFolder object

’

[out] array: Array of simulation feature objects

Private Function SimulationFeatureObjects(oSimulationGroup, ByRef array) If oSimulationGroup.Count = 0 Then SimulationFeatureObjects = False Exit Function End If Redim array(oSimulationGroup.Count - 1) Dim oSimulation Dim n n = 0 For Each oSimulation In oSimulationGroup Const OBJECTKIND_SIMULATION = "{095C5D90-96F1-4BA8-85BB-B2F990AC2DD9}" If oSimulation.ObjectKind = OBJECTKIND_SIMULATION Then Set array(n) = oSimulation.Dispatch n = n + 1 End If

178


AT332_TAG_E0

Next SimulationFeatureObjects = True End Function Private Sub DumpTable(t) Dim c Dim r Dim values() For r = 0 To t.RowCount Redim values(t.ColumnCount) For c = 0 To t.ColumnCount values(c) = t.GetValue(r, c) If IsNull(values(c)) Then values(c) = "(Null)" End If If IsEmpty(values(c)) Then values(c) = "(Empty)" End If If IsArray(values(c)) Then values(c) = "(Array)" End If Next LogMessage Join(values, ";") Next End Sub Private Sub DumpSimulation(oSimulation, name) LogMessage name LogMessage "Cells..." DumpTable(oSimulation.Cells) LogMessage "End Cells." LogMessage "Sites..." DumpTable(oSimulation.Sites) LogMessage "End Sites." LogMessage "Mobiles..."

179



DumpTable(oSimulation.Mobiles) LogMessage "End Mobiles." LogMessage "End " & name & "." End Sub Public Sub DumpSimulationGroupAttributes Dim f() Dim arraySimulations() If (SimulationGroupFeatureObjects(ActiveDocument, f) = False) Then LogMessage "No Group of Simulations found in the document." Exit Sub End If Dim oFeature For Each oFeature In f LogMessage "Group of Simulations [" & oFeature.Source.Name & "]..." Dim average Dim stddev On Error Resume Next Set average = oFeature.MeanSimulation If Err Then ’ The average simulation is not available when ’ no simulation has converged in the group. LogMessage "The average simulation is not available." On Error Goto 0 Else On Error Goto 0 DumpSimulation average, "Average Simulation" On Error Resume Next Set stddev = oFeature.StdDevSimulation If Err Then ' The standard deviation simulation is not available ’ for LTE and WiMAX projects. On Error Goto 0 Else

180


AT332_TAG_E0

On Error Goto 0 DumpSimulation stddev, "Stddev Simulation" End If End If ' Dump all simulation in the group of simulations Dim oSimulationGroup Set oSimulationGroup = oFeature.Source If (SimulationFeatureObjects(oSimulationGroup, False) Then

arraySimulations)

=

LogMessage "There are no simulations in this group of simulations." Else Dim oSimulation For Each oSimulation In arraySimulations DumpSimulation oSimulation, oSimulation.Source.Name Next End If LogMessage "End Group of Simulations." Next End Sub

12.7 3GPP Multi-RAT Simulation Group Feature Object Multi-RAT Simulation Group Feature objects are available in Atolldocuments based on the templates: •

3GPP Multi-RAT

3GPP Multi-RAT Simulation Group Feature objects are similar to Simulation Group Feature objects available in single-RAT documents, except some methods in 3GPP Multi-RAT Simulation Group Feature objects require the name of the technology to be specified.Multi-RAT Simulation Group Feature objects provide the following properties and methods: Name

Description

get_Source

Returns the associated 3GPP Simulation Group ChildFolder object.

get_Statistics

Returns a TabularData object holding the statistics of the simulation group for the specified technology.

get_MeanSimulation

Returns a Simulation Feature object giving access to the average simulation properties for the specified technology.

get_StdDevSimulation

Returns a Simulation Feature object used to access the standard deviation simulation properties for the specified technology.

12.7.1 get_Source Returns the associated 3GPP Multi-RAT Simulation Group ChildFolder object.

181



HRESULT get_Source(IDispatch **ppSource); Parameters [out] ppSource: Address of the IDispatch interface pointer used to return the associated 3GGP Multi-RAT Simulation Group ChildFolder object.

12.7.2 get_Statistics Returns a TabularData object holding the statistics of the simulation group for the specified technology. HRESULT get_Statistics(const BSTR bstrTechno, ITabularData **ppTable); Remarks This method is not implemented. Please don’t use this method.

12.7.3 get_MeanSimulation Returns a Simulation Feature object giving access to the average simulation properties for the specified technology. HRESULT get_MeanSimulation( const BSTR bstrTechno, ISimulation **ppMeanValues ); Parameters [in] bstrTechno: A string used to specify the requested technology. Available values are "GSM”, “UMTS”, or “LTE”. [out] ppMeanValues: Address of the ISimulation interface pointer used to return the Simulation Feature object corresponding to the average simulation. Remarks The returned Simulation Feature object is not associated with a particular ChildFolder object in the Atoll document. An error is returned when no simulation in the simulation group has converged. The average simulation is not available when no simulation in the simulation group has converged. An error is returned when the simulation group has not been calculated yet, for instance when the 3GPP simulation group has been created with the check box "Execute Later" set.

12.7.4 get_StdDevSimulation Returns a Simulation Feature object used to access the standard deviation simulation properties for the specified technology. HRESULT get_StdDevSimulation( const BSTR bstrTechno, ISimulation **ppStdDevValues ); [in] bstrTechno: A string used to specify the requested technology. Available values are "GSM”, “UMTS”, or “LTE”. [out] ppStdDevValues: Address of the ISimulation interface pointer used to return the Simulation Feature object corresponding to the standard deviation simulation. Remarks The returned Simulation Feature object is not associated with a particular ChildFolder object in the Atoll document. An error is returned when no simulation in the simulation group has converged. The standard deviation simulation is not available when no simulation in the simulation group has converged.

182


AT332_TAG_E0

An error is returned when the simulation group has not been calculated yet, for instance when the simulation group has been created with the check box "Execute Later" set. An error is returned when the Atoll document is based on the LTE, WiMAX 802.16e templates. The standard deviation simulation is not available for LTE and WiMAX.

12.8 GSM Interference Matrix Feature Object GSM Interference Matrix Feature objects give access to GSM interference matrices. A document can contain zero, one, or more interference matrices. They are located in the "Interference matrices" folder of the document. GSM Interference Matrix Feature objects are available in documents based on the GSM GPRS EDGE template. GSM Interference Matrix Feature objects provide the following properties and methods: Name

Description

Attributes

get_Source

Returns the "Interference Matrices" ChildFolder object.

Type: ChildFolder object Access:Read

Load

Loads an interference matrix.

CompleteScopeInfo

Completes scope information.

get_Scope

Returns the scope of the interference matrix.

Type: Tabular Data object Access:Read

get_Active

Returns the interference matrix active state.

Type: Boolean Access:Read/Write

put_Active

Sets the interference matrix active state.


get_Type

Returns the type of the interference matrix.

Type: Integer Access:Read/Write

put_Type

Sets the type of the interference matrix.


get_BasedOnTraffic


put_BasedOnTraffic


get_Resolution

Returns the resolution of the interference matrix calculation.


put_Resolution

Sets the resolution of the interference matrix calculation.


get_StdDev

Returns the interference matrix standard deviation.

Type: Single Access:Read/Write

put_StdDev

Sets the interference matrix standard deviation.

Type: Single Access:Read/Write

get_InfoQuantityIndicator

Returns the interference matrix information quantity indicator.


put_InfoQuantityIndicator

Sets the interference matrix information quantity indicator.


get_CdfTab

Returns the interference matrix CDF tabular data.

Type: Tabular Data object Access:Read

183



12.8.1 How to Access GSM Interference Matrix Feature Objects The ObjectKind property for an Interference Matrix ChildFolder objects is: {5144E1F9-E539-4F8C-BC0C-49A11C6389E8} Interference Matrix ChildFolder objects are children of the folder named "Interference Matrices". GSM Interference Matrix Feature objects are available through the Dispatch property of Interference Matrix ChildFolder objects: Dim oInterferenceMatrix Dim oInterferenceMatricesChildFolder Set oInterferenceMatricesChildFolder = oDocument.GetRootFolder(atoData).Item("Interference Matrices") Set oInterferenceMatrix = oInterferenceMatricesChildFolder.Dispatch

12.8.2 get_Source Returns the "Interference Matrices" ChildFolder object. HRESULT get_Source(IDispatch **ppSource); Parameters [out] ppSource: Address of the IDispatch interface pointer used to return the "Interference Matrices" ChildFolder object.

12.8.3 Load Loads an interference matrix. HRESULT Load();

Remarks This method must be called before any access to an interference matrix.

12.8.4 CompleteScopeInfo Completes scope information. HRESULT CompleteScopeInfo(); Remarks This method must be called after transmitters are added to the scope.

12.8.5 get_Scope Returns the scope of the interference matrix. HRESULT get_Scope(ITabularData **ppTable);

Parameters [out] ppTable : The address of the ITabularData interface pointer used to return the scope of the interference matrix.

184


AT332_TAG_E0

Remarks The scope of an interference matrix is a Tabular Data object containing a mapping from the row identifier for a transmitter to the following information: The coverage percentage as victim, and as interferer. The default values are 100. The BSIC and BCCH when the interference matrix information was collected. The default values are -1.

12.8.6 put_Active Sets the active state. HRESULT put_Active( VARIANT_BOOL isActiveVal); Parameters [in] isActiveVal : The VARIANT_BOOL value used to specify the active state of the interference matrix. Remarks An active interference matrix is used by the automatic frequency planning process when the interference matrix scope intersects the automatic frequency planning scope.

12.8.7 get_Active Returns the active state. HRESULT get_Active(VARIANT_BOOL *pIsActiveVal);

Parameters [out] pIsActiveVal : Address of the VARIANT_BOOL used to return the active state of the interference matrix. Remarks An active interference matrix is used by the automatic frequency planning process when the interference matrix scope intersects the automatic frequency planning scope.

12.8.8 get_Type Returrns the interference matrix type. HRESULT get_Type(IM_TYPE *pImTypeVal);

Parameters [out] pImTypeVal : Address of the enumeration value used to return the interference matrix type. Remarks: Available enumeration values used to specify an interference matrix type are: 1 : PROPAG_IM For interference matrices based on propagation data. Their reliability depends on the accuracy and correctness of network and geogrpahical data. 2 : OMC_RESELCTION_IM For interference matrices based on reselection statistics from the OMC. Their reliability is usually low due to the difference between the locations where mobiles are switched on and where they are actually used to access the network. 3 : OMC_SIMPLE_HO_IM Their reliability is usually low due to the fact that interference is measured only among existing neighbours, which might not be correctly assigned. This type of interference matrix is highly correlated with the neighbour relations. It can be used to remove excessive neighbour constraints. However, it cannot be used to complete any missing neighbour information. Another

185



reason for low reliability is that interference information is collected from handover regions only, instead of from the service area. 4 : OMC_NEI_EXT_HO_IM Interference matrices based on RXLEV statistics from the OMC (neighbours, as well as temporary neighbours). They can be a very good source of interference information if they are statistically stable because they are not sensitive to data errors. On the other hand, they have many disadvantages, such as: Transmitters with the same BSIC and BCCH cannot be differentiated. Transmitters having the same BCCH will never have an interference entry. Information is lost when more than 6 interferers exist at any location. If many interferers share the same BCCH, they increase each other’s interference levels. HCS layers can cause problems because there are more servers at any point, macro layer servers are stronger, or a correction margin might be introduced for some equipment. This type of interference matrix can be created using an extended neighbours list. 5 : TEST_MOBILE_DATA_IM Interference matrices based on test mobile data. Reliability can be low because usually the test mobile data sampling zone and the traffic model are not related. Secondly, the measurements are carried out for existing neighbours only. 6 : CW_IM Interference matrices based on CW measurements. Their reliability can be low because the measurements usually do not reflect the traffic model. However, this source of information can be very reliable for a subset of transmitters that were properly scanned. Carrying out CW measurements is expensive which means that the collected information is often partial or out of date. 7 : SCAN_DATA_IM Interference matrices based on scan data drive tests. They are highly reliable and an excellent source of information, but are not useful in a radio planning tool because no information is available to map transmitters to the received signals at any pixel. 8 : UPPER_BOUND_ENTRY_COLLECTION Upper bound interference matrix. The source of this type of interference matrix is not defined. It can be based on user experience. The information contained in this interference matrix is used as an upper limit, i.e., if this interference matrix indicates a certain level of interference, it should not be exceeded because other interference matrices show higher interference. If an upper bound interference matrix does not contain information about an entry, it is ignored. 9 : LOWER_BOUND_ENTRY_COLLECTION Lower bound interference matrix. The source of this type of interference matrix is not defined. It can be based on user experience. The information contained in this interference matrix is used as a lower limit. This type of interference matrix can be very useful because you can edit entries in this interference matrix, and be certain that the interference will be at least as high as the value you entered. This approach can be used when user experience shows a certain level of interference which the radio network planning tool is unable to calculate.

12.8.9 put_Type Sets the interference matrix type. HRESULT put_Type(IM_TYPE imTypeVal);

Parameters [in] imTypeVal : The enumeration value used to specify the interference matrix type.

12.8.10 get_BasedOnTraffic Returns based on traffic.

186


AT332_TAG_E0

HRESULT get_BasedOnTraffic(VARIANT_BOOL *pbBasedOntraf) ;

Parameters [out] pbBasedOntraf: The address of the VARIANT_BOOL value used to return based on traffic. Remark This method only makes sense for interference matrices of type PROPAG_IM. In that case, the return value indicates whether the interference matrix takes into account non uniform traffic distributions within each cell.

12.8.11 put_BasedOnTraffic Sets based on traffic. HRESULT put_BasedOnTraffic(VARIANT_BOOL bBasedOntraf) ;

Parameters [in] bBasedOntraf : The VARIANT_BOOL value used to specify based on traffic.

12.8.12 get_Resolution Returns the resolution of the interference matrix calculation. HRESULT get_Resolution(long *piResolutionParamVal);

Parameters [out] piResolutionParamVal : The address of the long integer used to return the resolution of the interference matrix calculation. Remarks For interference matrices of type PROPAG_IM, the return value is the resolution of the interference matrix calculation. For interference matrices of type TEST_MOBILE_DATA_IM, CW_IM, or SCAN_DATA_IM, the return value is the number of measurements per calculation point in the interference matrix.

12.8.13 put_Resolution Sets the resolution of the interference matrix calculation. HRESULT put_Resolution(long iResolutionParamVal) ;

Parameters [in] :iResolutionParamVal : The long integer used to specify the resolution of the interference matrix calculation.

12.8.14 get_StdDev Returns the interference matrix standard deviation. HRESULT get_StdDev(float *pfStdDevParamVal);

Parameters [out] pfStdDevParamVal: Address of the single precision floating point value used to return the interference matrix standard deviation.

187



Remarks For interference matrices of type PROPAG_IM, the return value is the standard deviation of the propagation model used in the interference matrix calculation. For interference matrices of type TEST_MOBILE_DATA_IM, CW_IM, or SCAN_DATA_IM, the return value is the standard deviation of the measurement equipment.

12.8.15 put_StdDev Sets the interference matrix standard deviation. HRESULT put_StdDev(float fStdDevParamVal);

Parameters [in] fStdDevParamVal: The single precision floating point value used to specify the interference matrix standard deviation.

12.8.16 get_InfoQuantityIndicator Returns the information quantity indicator. HRESULT get_InfoQuantityIndicator(long *piInfoQuantIndic);

Parameters [out] pilInfoQuantIndic: Address of the long integer used to return the information quantity indicator. Remarks For interference matrices of type PROPAG_IM, the return value is an information about the interference matrix calculation parameters. For interference matrices of type TEST_MOBILE_DATA_IM, CW_IM, or SCAN_DATA_IM, the return value is the number of calculation points per victim. For interference matrices of type OMC_RESELCTION_IM, OMC_SIMPLE_HO_IM, or OMC_NEI_EXT_HO_IM, the return value is the number of days since the OMC statistics were collected.

12.8.17 put_InfoQuantityIndicator Sets the information quantity indicator. HRESULT put_InfoQuantityIndicator(long iInfoQuantIndic) ;

Parameters [in] ilInfoQuantIndic : The long integer used to specify the information quantity indicator.

12.8.18 get_CdfTab Returns the interference matrix CDF tabular data. HRESULT get_CdfTab(ITabularData **ppTable) ;

Parameters [out] ppTable : Address of the ITabularData interface pointer used to return the inteference matrix tabular data. Remarks The structure of the Tabular Data object returned is: Column 1 : Row identifier of the victim transmitter

188


AT332_TAG_E0

Column 2 : Row identifier of the interferer transmitter Column 3 : A maximum loss value Column 4 : A safe array of type VT_ARRAY|VT_R4, VT_ARRAY|VT_R8, or VT_VARIANT having 1 dimension and containing the C/I values of the CDF. Column 5 : A safe array of type VT_ARRAY|VT_R4, or VT_ARRAY|VT_R8, or VT_VARIANT having 1 dimension and containing the probability values of the CDF.

Performance considerations:

When deleting elements, try to always delete the last element first. When editing an existing element, do not change columns 1, 2, or 3.

189


190


Chapter 13 Document Commands


192

Atoll 3.3.2 Task Automation Guide Chapter 13: Document Commands

AT332_TAG_E0

13 Document Commands The Atoll API enables executing commands on Atoll documents. Commands are invoked by their names, which must be known in advance. The following commands are available for all Atoll documents: Name

Description

Attributes

IMPORTXML

This command performs the same task as the Atoll "File > Data Exchange > XML File Import..." main menu command.

Version:  2.7.1

EXPORTXML

This command performs the same task as the Atoll "File > Data Exchange > XML File Export..." main menu command.

Version:  2.7.0

APPENDTABLECOLUMN

This command adds a new column to a database table. This command is only available for Atoll documents that are not connected to databases.

Version:  2.8.0

The following commands are available for radio network technology documents: Name

Description

Attributes

CALCULATEPOINTS

This command returns signal levels in dBm for a given set of points and a set of transmitters.

Version:  2.6.0

IMPORTTESTMOBILEDATA

This command imports a set of drive test data files into an Atoll document.

Version:  2.6.1

RUNNEIGHBOURALLOCATION

Performs neighbour allocation on a GSM network.

Version:  2.6.1

RUNINTERTECHNOLOGYNEIGHBOU RALLOCATION

Performs inter technology neighbour allocation on a GSM or UMTS network.

Version:  2.6.1

RUNINTRACARRIERNEIGHBOURALL OCATION

Performs intra carrier neighbour allocation on a UMTS network.

Version:  2.6.1

RUNINTERCARRIERNEIGHBOURALL OCATION

Performs inter carrier neighbour allocation on a UMTS network.

Version:  2.6.1

CLONESTUDY

This command clones a coverage prediction.

Version:  2.7.0

DUPLICATESTUDY

This command duplicates a coverage prediction.

Version:  2.7.0

COMPARESTUDY

This command compares two coverage predictions.

Version:  2.7.0

CALCULATEEQUIPMENTLOSSES

This command calculates equipment losses and noise figure for all transmitters in the document transmitters folder.

Version:  2.7.0

CALCULATEREPEATERS

This command calculates propagation losses, azimuth, mechanical tilt, or gains for all repeaters in the document transmitters folder.

Version:  2.7.0

CALCULATEREMOTEANTENNAS

This command calculates propagation losses, azimuth, mechanical tilt, or gains for all remote antennas in the document transmitters folder.

Version:  2.7.0

EXPORTACTIVESETANALYSIS

This command exports the active set analysis to text files.

Version:  2.7.0

CALCULATEPOINTSECI0

This command returns Ec/I0 values in dB for a given set of points and a set of transmitters.

Version:  2.7.0

193



Name

Description

Attributes

RUNALLCARRIERSALLOCATION

Performs all carriers allocation on a TD-SCDMA network.

Version:  2.8.1

RUNMASTERCARRIERALLOCATION

Performs master carrier allocation on a TD-SCDMA network.

Version:  2.8.1

MWRun

This command runs Microwave analysis for a given set of links.

Version:  2.6.1

EXPORTMAPWINDOW

Exports a region of the map window as an image

Version:  3.1.0

IMPORTPLANETDATAFILE

Imports a planet data file

Version:  3.1.0

EXPORTMWLINKANALYSISPROFILE PICTURE

Exports a microwave link analysis profile picture to a Windows bitmap file.

Version:  3.1.0

MWCalculateProfiles

Calculates Microwave profile files.

Version:  3.3.0

Input Parameters Commands may have input parameters. The types and names of input parameters are unique and are specific to each command. PropertyContainer objects are used to hold input parameters. Results Commands may return results. Results are specific to each command. The results of a command are returned using a PropertyContainer object. Each result has a unique name and an associated type.

13.1 How to Invoke a Document Command The steps to invoke a command are the same for all commands. Sample script invoking an Atoll document command: Public Function ExecuteCommand(oDocument, strCommand, oParameters) Set ExecuteCommand = oDocument.InvokeCommand(strCommand, oParameters) End Function oDocument is an Atoll Document Object. It can be the active document, or any document in the Documents collection. strCommand is a string holding the Atoll command name. oParameters is an Atoll PropertyContainer object used to hold the parameters specific to strCommandName. It can be a PropertyContainer object holding the default parameters obtained with the GetCommandDefaults method available on the IDocument4 interface. The ExecuteCommand function returns the command results as a PropertyContainer object.

13.2 IMPORTXML This command performs the same task as the Atoll "File > Data Exchange > XML File Import..." main menu command. Version  2.7.1

194


AT332_TAG_E0

Input Parameters Name

Description

Attributes

PATH

The PATH input parameter is used to specify the source folder containing XML files to import.

Version:  2.7.1 Type: String

Default Parameters None. GetCommandDefaults on IDocument4 interface for the command IMPORTXML returns an empty PropertyContainer object. Results None. The data in the Atoll document are updated with the content of XML files.

13.3 EXPORTXML This command performs the same task as the Atoll "File > Data Exchange > XML File Export..." main menu command. Version  2.7.1


Description

Attributes

PATH

The PATH input parameter is used to specify the destination folder where XML files will be exported.


Default Parameters None. GetCommandDefaults for the command EXPORTXML returns an empty PropertyContainer object. Results None. The data in the Atoll document are exported to a set of XML files.

13.4 APPENDTABLECOLUMN This command adds a new column to a database table. This command is only available for Atoll documents that are not connected to databases. Version  2.8.0


Description

Attributes

TABLE

The TABLE input parameter is used to specify a table name. The new column will be added to the table named TABLE.


NAME

The NAME input parameter is used to specify the database name of the new column to add to the TABLE table. The value is case insensitive and must not include spacesand dot characters.


LEGEND

The LEGEND input parameter is used to specify the display name of the new column to add to the TABLE table. The value is case sensitive and spaces characters are allowed.


195



Name

Description

Attributes

TYPE

The TYPE input parameter is used to specify the data type of the new column to add to the table. Valid values are: 0=Text; 1=Short integer; 2=Long integer; 3=Single; 4=Double; 5=True/False; 6=Date/Time; 7=Currency;

Version:  2.8.0 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.


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:  2.8.0 Type: Null, String, Integer, Boolean, Single, Double, Currency, or Date

GROUP

The GROUP input parameter is used to specify the name of the group the new column belongs to.


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:  2.8.0 Type: Array of Strings

Default Parameters The TABLE, NAME, LEGEND, and TYPE input parameters have no default values, they must be specified. Default values for other input parameters are returned by GetCommandDefaultsfor the command APPENDTABLECOLUMN: Input Parameter Name

Default Value

LEGEND

Empty.

SIZE

10 bytes.

DEFAULT

Null

GROUP

Empty.

CHOICELIST

Empty.

Results None. Upon successful completion the new column is added to the table.

13.5 CALCULATEPOINTS This command returns signal levels in dBm for a given set of points and a set of transmitters. Path loss matrices, whether they are valid or not, are not used. Therefore the CalculatePoints command is not dependent on the path loss matrices resolution. Signal levels are calculated using the propagation model of each transmitter. Version  2.6.0

Input Parameters

196

Name

Description

Attributes

POINTS

The POINTS input parameter is used to define a set of points.

Version:  2.6.1 Type: Array of Integers


AT332_TAG_E0

Name

Description

Attributes

TRANSMITTERS

The TRANSMITTERS input parameter is used to define a set of transmitters.


The TECHNOLOGY input parameter is used to specify the technology of transmitters specified by the TRANSMITTERS input parameter. Available values are: "GSM" "UMTS" "LTE" "CDMA2000"


TECHNOLOGY

This parameter is ignored for single-RAT documents. The POINTS array must have 2 dimensions, 0 and 1. The size of dimension 0 is the number of points. The size of dimension 1 is 2, index 0 and 1 for dimension 1 are the X and Y coordinates, respectively. The coordinates of points are expressed in the projection coordinate system of the Atoll document. The TRANSMITTERS array must have 1 dimension. The size of the array is the number of transmitters. Array values are transmitters IDs, as they appear in the TX_ID field of the Transmitters table Default Parameters None. GetCommandDefaults for the command CALCULATEPOINTS returns an empty PropertyContainer object. Results Name

Description

Attributes

SIGNALS

The SIGNALS result is used to return signals levels.

Version:  2.6.1 Type: TabularData object

The SIGNALS TabularData object has one record for each transmitter belonging to the TRANSMITTERS input parameter. The row number n gives the signal received on the point number n. The SIGNALS TabularData object has the following structure: Column Name

Description

Attributes

TX_ID

A string holding a transmitter identifier.

Type: String

Pn

The signal level received on point number n from the transmitter identified by the field TX_ID. When the signal level is less than -200 dBm, the type of the variant returned for the field Pn is VT_NULL.

Type: Single or Null

13.6 IMPORTTESTMOBILEDATA This command imports a set of drive test data files into an Atoll document. Version  2.6.1


Description

Attributes

NAME

Name of the Atoll Explorer item where the drive test data is imported.


RECEIVERHEIGHT

Receiver height.

Version:  2.6.1 Type: Double

RECEIVERGAIN

Receiver gain.


197



Name

Description

Attributes

RECEIVERLOSSES

Receiver losses.


MEASUREMENTUNIT

Measurement unit. Valid values are: 0=dBm; 1=dBµV; 2=dBµV/m


MEASUREMENTCSCODE

Code of the coordinate system used for measurement points in the drive test data to import. The code for a coordinate system is reported in the Atoll properties dialogue of the coordinate system.


CONFIGURATIONNAME

Atoll configuration name, as reported in the Atoll drive test data import dialogue. Before importing drive test data, a drive test data configuration has to be defined in Atoll. CONFIGURATIONNAME is the name given to the drive test data configuration.


FILES

The FILES input parameter is used to define the set of files to import. Each file must be specified using its absolute path.

Version:  2.6.1 Type: Array of Strings Version:  3.2.0

CONFIGURATIONFILE

The CONFIGURATIONFILE input parameter is used to specify the full path to the initialization file (.ini) containing the CONFIGURATIONNAME. This parameter is optional. When it is not specified the configuration file used is the one used in the project.

Type: String

Default Parameters None. GetCommandDefaults for the command IMPORTTESTMOBILEDATA returns an empty PropertyContainer object. Results None.

13.7 RUNNEIGHBOURALLOCATION Performs neighbour allocation on a GSM network. Version  2.6.1


Description

Attributes

TRANSMITTERFOLDER

A sub-folder of the transmitters folder, or the transmitters folder itself.

Version:  2.6.1 Type: ChildFolder object

Default Parameters None. GetCommandDefaults for the command RUNNEIGHBOURALLOCATION returns an empty PropertyContainer object. The neighbour allocation parameters used to compute neighbours are the ones set into the Atoll document. The neigbour allocation parameters can be set by importing a user configuration file containing neighbour allocation parameters. Use the Atoll Document object SetConfig method to import the neighbour allocation parameters. Results

198

Name

Description

Attributes

NEIGHBOURS

The NEIGHBOURS result is used to return neighbour relations.



AT332_TAG_E0

The NEIGHBOURS TabularData object has one record for each neighbour relation between two transmitters belonging to TRANSMITTERFOLDER. Name

Description

Attributes

Transmitter

Type: String

Number

Type: Integer

Maximum number

Type: Integer

Neighbour

Type: String

Importance (%)

Type: Single

Cause

Type: String

Coverage (%)

Type: Single

Coverage (km²)

Type: Single

13.8 RUNINTERTECHNOLOGYNEIGHBOURALLOCATION Performs inter technology neighbour allocation. Version  2.6.1


Description

Attributes

TRANSMITTERFOLDER

A sub-folder of a transmitters folder, or a transmitters folder itself.


NeighbourTechnologyName

A string used to specify the technology of allocated neighbours. Available values are: "GSM", "UMTS", "LTE"


Default Parameters None. GetCommandDefaults for the command RUNINTERTECHNOLOGYNEIGHBOURALLOCATION returns an empty PropertyContainer object. The neighbour allocation parameters used to calculate neighbours are the ones set in the Atoll document. The neigbour allocation parameters can be set by importing a user configuration file containing neighbour allocation parameters. Use the Atoll Document object SetConfig method to import the neighbour allocation parameters. Results Name

Description

Attributes

NEIGHBOURS



The NEIGHBOURS TabularData object has one record for each neighbour relation between two transmitters belonging to TRANSMITTERFOLDER. Name

Description

Attributes

Transmitter

Type: String

Number

Type: Integer

199



Name

Description

Attributes

Maximum number

Type: Integer

Neighbour

Type: String

Cause

Type: String

Coverage (%)

Type: Single

Coverage (km²)

Type: Single

Distance (m)

Type: Single

13.9 RUNINTRACARRIERNEIGHBOURALLOCATION Performs intra carrier neighbour allocation on a UMTS network. Version  2.6.1


Description

Attributes

TRANSMITTERFOLDER



Default Parameters None. GetCommandDefaults for the command RUNINTRACARRIERNEIGHBOURALLOCATION returns an empty PropertyContainer object. The neighbour allocation parameters used to calculate neighbours are the ones set in the Atoll document. The neigbour allocation parameters can be set by importing a user configuration file containing neighbour allocation parameters. Use the Atoll Document object SetConfig method to import the neighbour allocation parameters. Results Name

Description

Attributes

NEIGHBOURS



The NEIGHBOURS TabularData object has one record for each neighbour relation between two transmitters belonging to TRANSMITTERFOLDER. Column Name

200

Description

Attributes

Cell

Type: String

Number

Type: Integer

Maximum number

Type: Integer

Neighbour

Type: String

Cause

Type: String

Coverage (%)

Type: Single

Coverage (km²)

Type: Single

Distance (m)

Type: Single


AT332_TAG_E0

13.10 RUNINTERCARRIERNEIGHBOURALLOCATION Performs inter carrier neighbour allocation on a UMTS network. Version  2.6.1


Description

Attributes

TRANSMITTERFOLDER



Default Parameters None. GetCommandDefaults for the command RUNINTERCARRIERNEIGHBOURALLOCATION returns an empty PropertyContainer object. The neighbour allocation parameters used to compute neighbours are the ones set into the Atoll document. The neigbour allocation parameters can be set by importing a user configuration file containing neighbour allocation parameters. Use the Atoll Document object SetConfig method to import the neighbour allocation parameters. Results Name

Description

Attributes

NEIGHBOURS



The NEIGHBOURS TabularData object has one record for each neighbour relation between two transmitters belonging to TRANSMITTERFOLDER. Column Name

Description

Attributes

Cell Cell

Type: String

Number

Type: Integer

Maximum number

Type: Integer

Neighbour

Type: String

Cause

Type: String

Coverage (%)

Type: Single

Coverage (km²)

Type: Single

Distance (m)

Type: Single

13.11 CLONESTUDY This command clones a coverage prediction. Version  2.7.0

201




Description

Attributes

STUDY

The STUDY input parameter holds the study to clone. The study to clone is a study object contained in the Predictions folder of the Atoll document.


NEWSTUDYNAME

The NEWSTUDYNAME input parameter is used to define the name of the new cloned study.


Default Parameters None. GetCommandDefaults for the command CLONESTUDY returns an empty PropertyContainer object. Results Name

Description

Attributes

NEWSTUDY

The NEWSTUDY result is used to return the new cloned study object.


13.12 DUPLICATESTUDY This command duplicates a coverage prediction. Version  2.7.0


Description

Attributes

STUDY

The STUDY input parameter holds the study to duplicate. The study to duplicate is a study object contained in the Predictions folder of the Atoll document.


NEWSTUDYNAME

The NEWSTUDYNAME input parameter is used to define the name of the new duplicated study.


NEWSTUDYPARENT

The NEWSTUDYPARENT input parameter is used to specify a sub folder of the Predictions folder. The new study will be created in the NEWSTUDYPARENT sub folder of the Predictions folder. This parameter is optional. If not specified the new study will be created at the root of the Predictions folder.


Default Parameters None. GetCommandDefaults for the command DUPLICATESTUDY returns an empty PropertyContainer object. Results Name

Description

Attributes

NEWSTUDY

The NEWSTUDY result is used to return the new duplicated study object.


13.13 COMPARESTUDY This command compares two coverage predictions.

202


AT332_TAG_E0

Version  2.7.0


Description

Attributes

STUDY1

The STUDY1 input parameter holds the first study involved in the comparison. It is a study object contained in the Predictions folder of the Atoll document.


STUDY2

The STUDY2 input parameter holds the second study involved in the comparison. It is a study object contained in the Predictions folder of the Atoll document.


NEWSTUDYNAME

The NEWSTUDYNAME input parameter is used to define the name of the comparison study.


Default Parameters None. GetCommandDefaults on IDocument4 interface for the command COMPARESTUDY returns an empty PropertyContainer object. Results Name

Description

Attributes

NEWSTUDY

The NEWSTUDY result is used to return the comparison study object.


13.14 CALCULATEEQUIPMENTLOSSES This command calculates equipment losses and noise figure for all transmitters in a document transmitters folder. Version  2.7.0


Description

Attributes

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.


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



Version  2.7.0


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.


GAINS

The GAINS input parameter is used to specify whether repeaters gains will be calculated.


TRANSMITTERFOLDER



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.


AZIMUTHSANDTILTS

The AZIMUTHSANDTILTS input parameter is used to specify whether remote antennas donor side azimuths and tilts will be calculated.



AT332_TAG_E0

Name

Description

Attributes

GAINS

The GAINS input parameter is used to specify whether remote antennas gains will be calculated.


TRANSMITTERFOLDER



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


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



The general parameters include: Name

Description

Attributes

RESOLUTION

The resolution in meter used to export the activeset analysis.


DEPTH

The maximum number of cells in the activeset analysis to export on a given point.


TEXTSEPARATOR

The ASCII code of the character used as the field delimiter in the exported text files.


EXPORTFULLPATH

The full path of the file where the activeset is exported.


Name

Description

Attributes

TERMINAL

The name of the terminal used to export the active set.


MOBILITY

The name of the mobility used to export the active set.


SERVICE

The name of the service used to export the active set.


CARRIER

The carrier number used to export the active set.


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.


INDOORCOVERAGE

Whether to decrease the received signal level at the receiver of the indoor loss defined for the corresponding clutter class (clutter class properties).


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.


Default Parameters

206

Property Name

Default Value


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.


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



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


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.


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)".


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


AT332_TAG_E0

Results Name

Description

Attributes

VALUES

The VALUES result is used to return Ec/I0 values.


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


Description

Attributes

TRANSMITTERFOLDER



CONFREQUENCYALLOCATION

A boolean value used to specify whether to perform Co-N frequency allocation (True) or Diff-N frequency allocation (False).


COMMITRESULTS

A boolean value used to specify whether the allocation results will be commited in the document (True), or not (False).


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.


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



13.20 RUNMASTERCARRIERALLOCATION Performs master carrier allocation on a TD-SCDMA network. Version  2.8.1


Description

Attributes

TRANSMITTERFOLDER



DELETEEXISTINGALLOCATION

A boolean value used to specify whether to delete the existing allocation (True), or not (False).


COMMITRESULTS

A boolean value used to specify whether the allocation results will be commited in the document (True), or not (False).


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.


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.



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.


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;


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;


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;


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;


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.


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


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


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.


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.


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.


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.


kMoy

Defines the value of the average earth curvature used in calculation.


kMin

Defines the value of the second earth curvature used to display the ellipsoid. (not used during link budgets nor interferences calculation).


UseAtpc

Option which defines if power must be reduced or not with the ATPC value.


211


212


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.


IgnoreXPD

Boolean which tells if the calculation of fading due to XPD must be taken into account or not in the total result.


IgnorePR

Boolean which tells if the calculation of fading due to enhancements must be taken into account or not in the total result.


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).


BER1

First value of BER which is used when OneBER = 1.


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.


Rec838

Defines which release of recommendation ITU-838 must be used: 0=Rec 838-1; 1=Rec 838-3;


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.


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).


InterferenceDistanceMax

Defines the maximum distance (in meters) to search potential interferers.


InterferenceDropMin

Defines the threshold of drop margin (in dB) under which an interference level is not added to the total result.


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.


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.


InterferenceCalcUplink

Defines if the uplink interference must be calculated and displayed or not in the final result.


InterferenceCalcDownlink

Defines if the downlink interference must be calculated and displayed or not in the final result.


InterferenceRainSurfCorrel ation

Value of the area (km2) which is used to calculate the correlation between two links.



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.


InterferenceUseAtpc

Option which defines if interferer power must be reduced or not with the ATPC value.


InterferenceWidth

Percent of the channels width which can interfere or be interfered.


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.;


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.


COCHANNELONLY

When COCHANNELONLY is set to True, INTERFERENCEWIDTH is ignored.


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


1


2


3

RainMod

1

RBER

1e-12

ALFA1

10

ALFA2

1

RefDelayM

6.3

RefDelayNM

6.3

EquipPercent

33

213



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.


BAND

Name (primary key) of the frequency band of the link.


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.


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)



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.


CHANNEL

The calculated channel number. If the link has manual frequency, channel number is "-1".


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.


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").


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").


HEIGHT_TX

Value of the height of transmitting antenna (in meters).


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).


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).


ANTGAIN_TX

Value of the gain of the transmitting antenna (in dB). This value is displayed in the antenna properties.


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").


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").


HEIGHT_RX

Value of the height of receiving antenna (in meters).


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).


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).


ANTGAIN_RX

Value of the gain of the receiving antenna (in dB). This value is displayed in the antenna properties.


EQ_TX

Name (primary key) of the transmitting equipment. (equipment A is the way is "AB", equipment B if the way if "BA").


POWER_NOM

Value of the nominal transmitted power, used if ATPC is not taken into account.


POWER_COORD

Value of the coordinate transmitted power, used if ATPC is taken into account.


215


216


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" …


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.


TX_LOSS

Value of the total losses on the transmitter side: Shared losses, Connection losses, Shielding factor, port losses (filter + attenuation), wave guide losses.


FSL

Value of the free space loss calculated between transmitter and receiver.


LA

Value of the attenuation due to dry air absorption.


LV

Value of the attenuation due to vapor absorption.


LD

Value of the total diffraction through the profile between the transmitter and the receiver.


LVEG

Value of the vegetation loss along the profile.


LBS

Value of the tropospheric loss along the profile.


LTOT

Value of the total propagation loss along the profile. (Remember that vegetation loss is never added).


EQ_RX

Name (primary key) of the receiving equipment. (equipment B is the way is "AB", equipment A if the way if "BA").


RX_LOSS

Value of the total losses on the receiver side: Shared losses, Connection losses, Shielding factor, port losses (filter + attenuation), wave guide losses.


RX_THRESOLD

Value of the receiver threshold (dBm) defined as the sensitivity of the receiver for the BER1 value.


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.)


XPD

Difference between the cross-polar value of the receiver antenna and its co-polar value (dB).


XPI

Difference between the cross-polar value of the transmitter antenna and its co-polar value (dB).


RX_LEVEL

Wanted signal level (dBm) Takes into account the transmitted power, transmitter and receiver losses, total propagation losses and decoupling.


FADE_MARGIN

Calculated fade margin (uniform margin) which takes into account the received signal level et the receiver threshold.


PNS

Percent of outage due to uniform fadings.



AT332_TAG_E0

Name

Description

Attributes

PS

Percent of outage due to selective fadings.


pXPD

Percent of outage due to cross-polar discrimination fadings.


PT

Percent of outage which determined the quality of the link (i.e during clear air conditions).


SESR

Probability of SESR outage.


BBER

Probability of BBER outage.


ESR

Probability of ESR outage.


PR

Percent of fadings due to enhancements.


P0

Percent of multipath occurrence.


PP

Percent of fadings due to rain for the worst month.


PPA

Percent of fadings due to rain for an average year.


PXPD

Percent of rain fadings due to cross-polar discrimination.


PPT

Total percent of unavailability for an average year.


PFAILURES

Percent of fadings due to equipment failures.


RAIN_SESR

Probability of rain SESR outage.


RAIN_BBER

Probability of rain BBER outage.


RAIN_ESR

Probability of Rain ESR outage.


PASSIVE_GAIN

Total gain (dB) of the passive repeaters.


AFF_RAIN

Total rain attenuation (dB) along the path.


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".


OBJ_M_Q

Quality objective during clear-air for the worst month. Value is formatted is unit (hour, mn, sec)


SEC_Y_Q

Total time of outage during clear-air for an average year month. Value is formatted is unit (hour, mn, sec)


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"


217



Name

Description

Attributes

OBJ_M_RAIN

Quality objective during rain condition for the worst month. Value is formatted is unit (hour, mn, sec)


SEC_Y_RAIN

Total time of outage during rain condition for an average year month. Value is formatted is unit (hour, mn, sec)


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";


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";


CFM

Value of the composite fade margin (dB) which takes into account all the margins; Corresponds to the SESR probability.


REQ_CFM_Q

Value of the composite fade margin (dB) calculated from the quality objectives set for the link.


REQ_TFM

Value of the uniform margin (dB) calculated from the quality objectives set for the link. Corresponds to the non-selective outage probability.


REQ_CFM_A

Value of the composite fade margin (dB) calculated from the availability set for the link.


TX_PORT

Transmission port.


RX_PORT

Reception port.


Name

Description

Attributes

LINKNAME

Name (primary key) of the link whose results are given.


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)


CHANNEL_IRX

Calculated interfered channel number. If the link has manual frequency, channel number is "-1".


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.


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.


FLAT_MARGIN

Value of the uniform margin (dB) calculated from the wanted signal level and the receiver threshold.


Analysis Results With Interference Calculation

218


AT332_TAG_E0

Name

Description

Attributes

I

Aggregation of all the interferences (dBm) received from other links and receiver thermal noise (FKTB).


MARGIN_REDUCT

Value of the differences between margin without interference and margin with interferences.


C_OVER_I

Value of C/I (dB) where C is the wanted signal level and I the total interference level.


IRAIN

Value of the total interference level during rain condition which can be different from the "general" interference level depending on correlation between links.


MARGIN_REDUCT_RAIN

Value of the differences between margin without rain interference and margin with interferences.


EFF_MARGIN

Value of the margin calculated from the receiver threshold and the received level when interference are taken into account.


BER

Value of the BER with which the current analysis is run.


QUALITY

Percent of outage which determined the quality of the link. (i.e during clear air conditions, and with interference).


AVAIL

Percent of fadings due to rain for the worst month, when interference are taken into account.


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"


OBJ_M_Q

Quality objective during clear-air for the worst month. Value is formatted is unit (hour, mn, sec)


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)


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"


OBJ_M_RAIN

Quality objective during rain condition for the worst month. Value is formatted is unit (hour, mn, sec)


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)


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";


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";


PORT_IRX

Interferenced Port


219



13.22 EXPORTMAPWINDOW Exports a region of the map window as an image. Version  3.1.0


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.


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.


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.


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.


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.


PATH

The absolute path of the file where the map window image is exported.


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


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.


SCALE

Scale of the map window used to export the map window image. Only used when the PIXELSIZE input parameter is set to 0.


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.


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.


INCLUDESCALE

Boolean value used to specify whether to include the scale in the exported image, or not.


Default Parameters None. GetCommandDefaults for the command EXPORTMAPWINDOW returns an empty PropertyContainer object.

220


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


Description

Attributes

PATH

The absolute path of the planet data file to import.


EMBED

Whether to embed data, or not.


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


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


Description

Attributes

LINKNAME

Name of the link.


LINKTYPE

Link type. Available values are: 0 : A -> B 1 : B ->A


PICTUREWIDTH

Picture width, in pixels.


221



Name

Description

Attributes

PICTUREHEIGHT

Picture height, in pixels.


FILEPATH

The absolute path of the Windows bitmap file where the link analysis picture is exported.


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


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"


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


13.26 SETPOWERMODE Sets the document power mode. This command is only available for UMTS or LTE technologies. Version  3.1.0

222


AT332_TAG_E0


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"


POWERMODE

The power mode. Available values are: 0 : default 1 : EIRP is calculated using the max power


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


Description

Attributes

CHILDFOLDER

The CHILDFOLDER input parameter is used to specify a vector data table. The ChildFolder object specified must support the VECTORDATA property.


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.


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.


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


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.


223



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.


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


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.


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.


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.


Default Parameters None.

224


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. .


13.29 CALCULATEPATHLOSS Performs pathloss matrix calculation on a transmitter folder. Version  3.2.0


Description

Attributes

TRANSMITTERFOLDER



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.


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).


FILTERED

When False, the calculation is made for all active transmitters in the transmitter folder. When True, only filtered transmitters are calculated


Default Parameters None. GetCommandDefaults for the command CALCULATEPATHLOSS returns an empty PropertyContainer object.

13.30 MWLinksCustomExport Performs microwave links custom export. Version  3.2.0


Description

Attributes

EXPORTPATH

Full path to the folder where link reports are exported.


TEMPLATEFILEPATH

Full path to the custom template used to perform the export.


LINKSFOLDER

The microwave links folder containing links to export to the EXPORTPATH folder, using the TEMPLATEFILEPATH custom template.


225



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.


INTERFERENCEDISTANCEMAX

Defines the maximum distance (in meters) to search for potential interferers. If not set, the default value is 50000.



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.


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


228


Chapter 14 Enumerations, Structures, and Interfaces


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



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


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



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


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

Atoll 3.3.2 Task Automation Guide

Recommend Documents