Beruflich Dokumente
Kultur Dokumente
TaskAutomationGuide
AT321_TAG_E1
AT321_TAG_E1
Atoll3.2.1TaskAutomationGuide
Release:AT321_TAG_E1(January2014)
Copyright19972014Forsk.AllRightsReserved.
Publishedby:
Forsk
7ruedesBriquetiers
31700Blagnac,France
Tel:+33562747210
Fax:+33562747211
Thesoftwaredescribedinthisdocumentisprovidedunderalicenceagreement.Thesoftwaremayonlybeusedorcopiedunderthetermsandconditionsofthelicenceagreement.
Nopartofthecontentsofthisdocumentmaybereproducedortransmittedinanyformorbyanymeanswithoutwrittenpermissionfromthepublisher.
Theproductorbrandnamesmentionedinthisdocumentaretrademarksorregisteredtrademarksoftheirrespectiveregisteringparties.
Thepublisherhastakencareinthepreparationofthisdocument,butmakesnoexpressedorimpliedwarrantyofanykindandassumesnoresponsibilityforerrorsoromissions.No
liabilityisassumedforincidentalorconsequentialdamagesinconnectionwithorarisingoutoftheuseoftheinformationcontainedherein.
2014 Forsk
Atoll3.2.1TaskAutomationGuide
TableofContents
AT321_TAG_E1
TableofContents
GettingStarted ................................................................................... 17
1.1
SupportedExtensions ................................................................................... 17
1.2
1.2.1
1.2.2
1.2.3
1.2.4
1.2.5
ScriptTutorial.......................................................................................... 17
WritingaVBScriptFile ................................................................................. 17
TestingtheScript..................................................................................... 18
SchedulingtheScript .................................................................................. 18
DebuggingtheScript.................................................................................. 21
ErrorManagement.................................................................................... 21
1.3
1.3.1
1.3.2
1.3.3
MacroTutorial ......................................................................................... 23
AddingMacrostoAtoll ................................................................................ 24
RunningaMacro ..................................................................................... 25
SavingaListofMacros ................................................................................ 25
1.4
WindowsScriptHost,32bitvs64bit...................................................................... 25
ObjectModel..................................................................................... 29
2.1
InterfacesImplementedbyObjects........................................................................ 29
2.2
2.2.1
2.2.2
PropertiesandMethodsProvidedbyObjects ............................................................... 30
Parameters.......................................................................................... 30
ErrorInformation ..................................................................................... 30
ApplicationObject ............................................................................... 33
3.1
HowtoAccesstheApplicationObject...................................................................... 34
3.2
get_Application........................................................................................ 34
3.3
get_Parent............................................................................................ 35
3.4
get_Active ............................................................................................ 35
3.5
put_Active ............................................................................................ 35
3.6
get_Documents........................................................................................ 35
3.7
get_Name............................................................................................. 36
3.8
get_FullName.......................................................................................... 36
3.9
get_Path .............................................................................................. 36
3.10
get_ActiveDocument.................................................................................... 36
3.11
get_WindowStatus ..................................................................................... 37
3.12
put_WindowStatus..................................................................................... 37
3.13
put_StatusBar ......................................................................................... 37
3.14
get_Visible............................................................................................ 38
3.15
put_Visible ............................................................................................ 38
3.16
get_Version ........................................................................................... 38
3.17
Quit .................................................................................................. 39
3.18
LogMessage........................................................................................... 39
3.19
CreatePropertyContainer................................................................................ 39
Atoll3.2.1TaskAutomationGuide
TableofContents
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
3.29.1
3.29.2
3.29.3
3.29.4
3.29.5
3.29.6
3.29.7
3.29.8
3.29.9
3.29.10
3.29.11
3.29.12
3.29.13
3.29.14
3.29.15
ApplicationEvents......................................................................................42
WillQuitApp..........................................................................................42
DocumentOpenComplete ..............................................................................43
WillCloseDocument ...................................................................................43
WillSaveDocument ....................................................................................43
DocumentSaveComplete...............................................................................43
DocumentNewComplete...............................................................................43
WillRefreshDocument .................................................................................44
RefreshDocumentComplete ............................................................................44
WillArchiveDocument..................................................................................44
ArchiveDocumentComplete.............................................................................44
WillRun .............................................................................................44
RunComplete.........................................................................................45
LicenceAcquireComplete...............................................................................45
LicenceReleaseComplete...............................................................................46
WillNewDocumentFromDatabase........................................................................47
DocumentsObject ...............................................................................51
4.1
HowtoAccessaDocumentsObject........................................................................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
Forsk2014
DocumentObject ................................................................................59
5.1
HowtoAccessaDocumentObject.........................................................................61
5.2
get_Application ........................................................................................61
5.3
get_Parent ............................................................................................61
5.4
get_FullName ..........................................................................................61
5.5
get_Name .............................................................................................62
5.6
get_Path..............................................................................................62
5.7
get_ReadOnly ..........................................................................................62
5.8
get_Saved .............................................................................................62
AT321_TAG_E1
Atoll3.2.1TaskAutomationGuide
TableofContents
5.9
get_CoordSystemProjection.............................................................................. 62
5.10
putref_CoordSystemProjection........................................................................... 63
5.11
get_CoordSystemDisplay ................................................................................ 63
5.12
putref_CoordSystemDisplay.............................................................................. 63
5.13
get_CoordSystemInternal ................................................................................ 63
5.14
get_TransmissionUnit ................................................................................... 64
5.15
put_TransmissionUnit ................................................................................... 64
5.16
get_ReceptionUnit ..................................................................................... 64
5.17
put_ReceptionUnit ..................................................................................... 64
5.18
get_DistanceUnit ....................................................................................... 64
5.19
put_DistanceUnit....................................................................................... 64
5.20
Close ................................................................................................. 65
5.21
FilePrint .............................................................................................. 65
5.22
Save.................................................................................................. 65
5.23
Refresh ............................................................................................... 65
5.24
Archive............................................................................................... 66
5.25
Run.................................................................................................. 66
5.26
SetConfig ............................................................................................. 66
5.27
Import................................................................................................ 67
5.28
GetRecords............................................................................................ 67
5.29
Redraw ............................................................................................... 68
5.30
CenterMapOn ......................................................................................... 68
5.31
GetRootFolder ......................................................................................... 68
5.32
RunPathloss........................................................................................... 69
5.33
GetService ............................................................................................ 69
5.34
ExportConfig .......................................................................................... 70
5.35
GetCommandDefaults................................................................................... 70
5.36
InvokeCommand....................................................................................... 71
5.37
get_RadiatedPowerUnit................................................................................. 71
5.38
put_RadiatedPowerUnit ................................................................................. 71
5.39
get_AntennaGainUnit ................................................................................... 71
5.40
put_AntennaGainUnit ................................................................................... 72
5.41
get_HeightOffsetUnit ................................................................................... 72
5.42
put_HeightOffsetUnit................................................................................... 72
5.43
get_DatabaseConnectionString........................................................................... 72
5.44
HasRunningTask........................................................................................ 72
5.45
RunEx ................................................................................................ 73
5.46
get_DatabaseSchemaString.............................................................................. 73
5.47
get_DisplayApplicationDialogues.......................................................................... 73
5.48
put_DisplayApplicationDialogues ......................................................................... 74
Atoll3.2.1TaskAutomationGuide
TableofContents
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
TabularDataObject ..............................................................................81
6.1
HowtoAccessaTabularDataObject.......................................................................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
ZonesandPredictionsTabularDataObjects ..............................................97
7.1
ZonesTabularDataObject ...............................................................................97
7.2
PredictionsTabularDataObject ..........................................................................98
8
8.1
Forsk2014
AT321_TAG_E1
Atoll3.2.1TaskAutomationGuide
TableofContents
8.2
Code................................................................................................ 103
8.3
ConvertCoordsTo...................................................................................... 104
8.4
Datum............................................................................................... 105
8.5
DatumName.......................................................................................... 105
8.6
8.7
8.8
8.9
8.10
Pick................................................................................................. 106
8.11
8.12
ProjParameter........................................................................................ 107
8.13
SetDatum............................................................................................ 107
8.14
SetProjection......................................................................................... 107
8.15
ChildFolderObject.............................................................................. 111
9.1
9.2
get_Application....................................................................................... 112
9.3
get_Parent........................................................................................... 113
9.4
get_Name............................................................................................ 113
9.5
9.6
get_Count............................................................................................ 114
9.7
9.8
9.9
get_Visible........................................................................................... 114
9.10
9.11
9.12
9.13
9.14
9.15
9.16
9.17
Remove.............................................................................................. 119
9.18
9.19
put_position.......................................................................................... 119
9.20
get_Object........................................................................................... 119
9.21
get_dispatch.......................................................................................... 119
9.22
9.23
9.24
Atoll3.2.1TaskAutomationGuide
TableofContents
Forsk2014
9.25
GetPropertiesInfo..................................................................................... 122
9.26
PropertyIsPropertyContainer........................................................................... 122
9.27
PropertyIsTabularData................................................................................. 122
9.28
9.29
SaveProperties....................................................................................... 123
9.30
9.31
10
10.1
Get................................................................................................. 127
10.2
Set................................................................................................. 128
10.3
10.4
IsPropertyContainer................................................................................... 128
10.5
IsTabularData........................................................................................ 128
10.6
Load................................................................................................ 128
10.7
10.8
RemoveAll........................................................................................... 129
10.9
11
11.1
11.2
11.3
PredictionsFolderProperties........................................................................... 134
11.4
11.4.1
11.4.2
11.4.3
11.4.4
11.4.5
11.4.6
11.5
GSMSimulationGroupProperties....................................................................... 142
11.6
UMTSSimulationGroupProperties...................................................................... 143
11.7
WiMAXandLTESimulationGroupProperties.............................................................. 144
11.8
3GPPMultiRATSimulationGroupProperties.............................................................. 145
11.9
PropagationModelProperties.......................................................................... 146
11.10
CWMeasurementProperties........................................................................... 148
11.11
11.12
CustomChildFolderObjectProperties.................................................................... 149
11.13
11.14
LinkProperties....................................................................................... 150
11.15
11.15.1
12
10
AT321_TAG_E1
Atoll3.2.1TaskAutomationGuide
TableofContents
12.1
12.1.1
12.1.2
12.1.3
12.1.4
12.1.5
12.2
12.2.1
12.2.2
12.2.3
12.2.4
12.2.5
12.3
12.3.1
12.3.2
12.4
12.4.1
12.4.2
12.4.3
12.4.4
12.4.5
EnvironmentBasedTrafficMapFeatureObject............................................................. 163
HowtoAccessEnvironmentBasedTrafficMapFeatureObjects ............................................. 163
get_Source ......................................................................................... 163
get_ClassAttributes .................................................................................. 163
get_DefaultAttributes ................................................................................ 163
AccessingEnvironmentBasedTrafficMapsAttributes ..................................................... 164
12.5
12.5.1
12.5.2
12.5.3
12.5.4
12.5.5
12.5.6
12.5.7
12.6
12.6.1
12.6.2
12.6.3
12.6.4
12.6.5
12.6.6
12.7
12.7.1
12.7.2
12.7.3
12.7.4
12.8
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
GSMInterferenceMatrixFeatureObject.................................................................. 177
HowtoAccessGSMInterferenceMatrixFeatureObjects ................................................... 177
get_Source ......................................................................................... 178
Load ............................................................................................... 178
CompleteScopeInfo.................................................................................. 178
get_Scope .......................................................................................... 178
put_Active.......................................................................................... 179
get_Active .......................................................................................... 179
get_Type ........................................................................................... 179
put_Type ........................................................................................... 180
get_BasedOnTraffic.................................................................................. 180
put_BasedOnTraffic .................................................................................. 181
get_Resolution...................................................................................... 181
put_Resolution ...................................................................................... 181
get_StdDev......................................................................................... 181
put_StdDev ......................................................................................... 182
get_InfoQuantityIndicator............................................................................. 182
put_InfoQuantityIndicator ............................................................................ 182
get_CdfTab......................................................................................... 182
13
Atoll3.2.1TaskAutomationGuide
TableofContents
Forsk2014
13.1
13.2
IMPORTXML......................................................................................... 188
13.3
13.4
APPENDTABLECOLUMN................................................................................ 189
13.5
CALCULATEPOINTS.................................................................................... 190
13.6
13.7
13.8
RUNINTERTECHNOLOGYNEIGHBOURALLOCATION.......................................................... 193
13.9
13.10
RUNINTERCARRIERNEIGHBOURALLOCATION.............................................................. 194
13.11
13.12
DUPLICATESTUDY..................................................................................... 195
13.13
13.14
13.15
13.16
CALCULATEREMOTEANTENNAS......................................................................... 198
13.17
13.18
13.19
13.20
RUNMASTERCARRIERALLOCATION....................................................................... 203
13.21
13.22
EXPORTMAPWINDOW................................................................................. 213
13.23
IMPORTPLANETDATAFILE.............................................................................. 214
13.24
EXPORTMWLINKANALYSISPROFILEPICTURE............................................................... 215
13.25
13.26
13.27
13.28
LOADSAVEPRINTSETUP................................................................................ 217
13.29
CALCULATEPATHLOSS................................................................................. 218
13.30
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
12
AT321_TAG_E1
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
Atoll3.2.1TaskAutomationGuide
TableofContents
AtoHeightOffsetUnit................................................................................ 225
AtoRootType...................................................................................... 225
AtoRowFilter...................................................................................... 225
AtoRowStatus..................................................................................... 225
AtoTemperatureUnit ............................................................................... 226
FSKGISLibTypeLibraryEnumerations ................................................................... 226
GeographicUnit .................................................................................... 226
ProjectionMethod.................................................................................. 226
ProjParameterIndices ............................................................................... 227
13
Atoll3.2.1TaskAutomationGuide
TableofContents
14
Forsk2014
Chapter1
GettingStarted
Atoll3.2.1TaskAutomationGuide
16
Forsk2014
Atoll3.2.1TaskAutomationGuide
Chapter1:GettingStarted
AT321_TAG_E1
1 GettingStarted
AtollprovidesasetofprogrammableextensionsenablinguserstoenhancethealreadyrichfunctionalitiesavailableinAtoll.
Ifyouplantowritescriptsormacros,youmustbefamiliarwithMicrosoftWindowsScriptTechnologies,especiallywiththe
VBScriptlanguage.
Youcanstartby:
Goingthroughthesection"SupportedExtensions"onpage 17tolearnwhichtypesofextensionscanbedeveloped.
Readingthefollowingtutorialsbeforestartingyourowndevelopment:
"ScriptTutorial"onpage 17,
"MacroTutorial"onpage 23,
1.1 SupportedExtensions
Thefollowingtypesofextensionsareavailable.
Scripts
AscriptisasequenceofVBScriptstatementsinatextfile,executablefromoutsideAtoll(WindowsScriptHost).Scripts
allowtaskautomationinAtollwhennointeractionwiththeuserisneeded.Scriptsdonotrequireanysetupandare
speciallyusefulforschedulingtasksinbatchmode.ScriptsuseCOMinterprocesscommunicationforcommunicating
withAtoll.
Samplecode:
Severalscriptsareavailablefordownloadatwww.forsk.com.
Macros
AmacroisasequenceofVBScriptstatementsinatextfile,executablefromwithinAtoll.Macrosallowtaskautoma
tioninAtoll.Macrosmayinteractwiththeuser,buttheinteractionislimitedbyVBScript.Macrosmustbeaddedto
Atollinordertobeavailableforexecution.TheycanbesavedinAtolluserconfigurationfiles.Macrocommandscan
beaddedtotoolbars.MacrosuseCOMinprocesscommunicationforcommunicatingwithAtoll.
Samplecode:
Severalmacrosareavailablefordownloadatwww.forsk.com.
1.2 ScriptTutorial
Throughthistutorial,youwilllearntoautomatesomesimpletasks,suchasarchivingdatatodatabases,runningcalculations,
andexecutingscriptsonascheduledtime.
1.2.1 WritingaVBScriptFile
Openatexteditor,andtypeinthefollowingcode:
Option Explicit
Dim var
Dim myapp
Dim doc
Sub Atoll_RunComplete(arg1, arg2)
var = 1
End Sub
Set myapp = CreateObject("Atoll.Application")
WScript.ConnectObject myapp, "Atoll_"
17
Atoll3.2.1TaskAutomationGuide
Chapter1:GettingStarted
Forsk2014
myapp.Visible = False
Set doc = myapp.Documents.OpenFromDatabase(
"Provider=SQLOLEDB.1;UserID=myNameName;Password=myPwd;InitialCatalog=myAtollDbName;Data Source=myServer;", "")
doc.Run True
var = 0
Do While var = 0
WScript.Sleep 1000
Loop
doc.Save("C:\mydoc.atl")
WScript.DisconnectObject myapp
doc = Null
Const atoSaveNo = 0
myapp.Documents.CloseAll atoSaveNo
myapp.Quit atoSaveNo
myapp = Null
WScript.Quit 0
Youmustreplacealltheparametersbeginningwith"my"withyourownvaluesintheaboveconnectionstring.Thisscript:
1. StartsaninvisibleAtollsession.
2. Opensanewdocumentfromanexistingdatabase.
3. Runsallthecalculationsinthisdocument.
4. Waitsfortheendofcalculations.
EventRunCompleteisthrownwhencalculationsaredone.Thesyntaxforcatchinganyeventistoconcatenatethe
nameoftheeventtothestring"Atoll_".Astheseparametershavenotbeenusedintheaboveexample,theyhave
beennamed"arg1"and"arg2".Moreover,weconnectanddisconnectthescriptusingtheappropriatemethodof
WScript.
5. Savesthedocument.
6. ExitstheAtollsession.
SaveyourscriptfileasaVBScriptfile,forexampleC:\Atollmacros\tutorial.vbs.
1.2.2 TestingtheScript
Totestthescript:
1. DoubleclicktheC:\Atollmacros\tutorial.vbsfileinWindowsExplorer.
2. CheckafewminuteslaterwhetherC:\TEMP\mydoc.atlhasbeencreatedornot.
1.2.3 SchedulingtheScript
YoucanschedulescriptsusingtheWindowsTaskScheduler.ThistutorialdescribesthestepsforWindows2000.Forother
operatingsystems,wheretheproceduremightdifferslightly,pleaserefertoWindowsHelp.
ToopentheWindowsTaskScheduler:
1. SelectStart>Settings>ControlPanel.TheControlPanelopens.
2. DoubleclicktheScheduledTasksicon.
18
Atoll3.2.1TaskAutomationGuide
Chapter1:GettingStarted
AT321_TAG_E1
3. DoubleclicktheAddScheduledTaskicon.TheScheduledTaksWizardopens.
4. ClickNext.
Figure 1.1:ScheduledTasksWizard
5. ClicktheBrowsebutton.
6. Selectcscript.exe.
7. ClickNext.
Figure 1.2:ScheduledTasksWizard
8. Changethenameofthetask,forexample"Atolltutorial".
9. Chooseyourpreferredperiodicity.
10. ClickNext.
Thefollowingwizardpagesenableyoutodefinemorepreciselywhenyourtaskshouldrunandwhichuserstartsit.
11. Inthelastpage,selecttheOpenadvancedpropertiesforthistaskwhenIclickFinishcheckbox.
12. ClickFinish.TheadvancedpropertiesAtollTutorialdialogueopens.
19
Atoll3.2.1TaskAutomationGuide
Chapter1:GettingStarted
Forsk2014
Figure 1.3:ScheduledTasksWizard
13. IntheAtollTutorialdialogue,addyourVBScriptfilenameintheRunfieldandappend"\\B"optiontospecifybatch
mode.Thissuppressesdialogueboxessuchasalertsandscripterrors.
Figure 1.4:AtollTutorial
14. Setaccountinformationifneeded.
15. ClickOK.YourtaskwillbedisplayedintheScheduledTaskswindow:
Figure 1.5:ScheduledTasks
Tomodifythetaskproperties:
1. RightclicktheAtollTutorialtask.Thecontextmenuopens.
2. SelectPropertiesfromthecontextmenu.
20
Atoll3.2.1TaskAutomationGuide
Chapter1:GettingStarted
AT321_TAG_E1
Tocontrolthecurrentstatusofthetask:
SelectView>Details.
Toopenthelogfile:
SelectAdvanced>ViewLog.
Totestthenewtask:
1. RightclicktheAtollTutorialtask.Thecontextmenuopens.
2. SelectRunfromthecontextmenu.
1.2.4 DebuggingtheScript
Todebugthescript,useacommandpromptconsoleandthewscript"//X"commandlineoption:
Myapp.Visible = True
1.2.5 ErrorManagement
Itisimportanttocheckforanyerrorthatmightoccurduringtheexecutionofthescript.MicrosoftVisualBasicscripting
languageprovides"OnErrorResumeNext"alongwiththe"Err"objecttomanageerrors.Hereisoursamplescriptwitherror
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
Atoll3.2.1TaskAutomationGuide
Chapter1:GettingStarted
Forsk2014
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;UserID=myName;Password=myPwd;InitialCatalog=myAtollDbName;DataSource=myServer;", "")
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
Atoll3.2.1TaskAutomationGuide
Chapter1:GettingStarted
AT321_TAG_E1
myapp.Quit atoSaveNo
myapp = Null
WScript.Quit 0
Errorcheckingisactivatedwith"OnErrorResumeNext".Whenanerroroccurs,thescriptcontinuesexecutionfromthenext
lineandthe"Err"objectissetaccordingly.YoucancheckforErr.Number,orforErr(becauseNumberisitsdefaultproperty)
tocatchanyerror.
1.3 MacroTutorial
MacrosarerunbyAtolluponbeinginvokedbytheuser.MacrosarewritteninVBScript,likescripts.Thedifferencebetween
scriptsandmacrosistheexecutioncontext.
WhenamacroislaunchedfromAtoll,aninstanceofanAtollApplicationobjectisautomaticallyaddedasascriptlevelvari
ableavailabletothemacrocode.Therefore,CreateObjectorGetObjecttoaccessanApplicationobjectmustnotbecalled.
Thefirstlineofyourmacrocanbedirectly:
mydoc = Atoll.ActiveDocument
ThescriptlevelvariablenamefortheAtollApplicationobjectis"Atoll"anditisoptional.So,theabovelineisequivalentto:
mydoc = ActiveDocument
Macroscanalsobeinvokedinresponsetoapplicationevents.
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
Atoll3.2.1TaskAutomationGuide
Chapter1:GettingStarted
Forsk2014
End If
End If
End Sub
Theaboveexampleshowsamacrousedtoautomaticallyarchiveadocumentonceithasbeensaved.
1.3.1 AddingMacrostoAtoll
YoucanaddamacrotoyourAtollsessionasfollows:
1. SelectTools>AddinsandMacros.TheAddinsandMacrosdialogueopens.
2. UnderMacros,clicktheAddbutton.
Browseforyourscriptfile.Youcancreateanewmacrofilebytypinganameforthenew(empty)macrofileinthefile
selectionbox.AtollwillinitializethisnewfilewithminimalVBScriptscript.Atollinterpretsyourfileandlistsallpublic
macrosfoundinthefileinanexplorer.
Ifyoucreateanemptymacrofile,itisinitialisedwiththefollowingcode:
Figure 1.6:AddingMacrosinAtoll
Toassociateaniconfiletoamacro:
1. UnderMacros,selectthemacrointhelistofmacros.
2. ClicktheIconbutton.
24
Atoll3.2.1TaskAutomationGuide
Chapter1:GettingStarted
AT321_TAG_E1
3. Selecttheiconfiletobeusedforthemacro.
AtoolbarbuttonisaddedforthemacroinAtoll,whichyoucanclicktorunthemacro.
For macros returning values, only functions, and not subroutines, may be defined. This is the case, for example, of all
"OnWill"callsasthereturnedvalue,thestatusvalue,allowstheusertobypassthestandardbehaviour.
Forfunctions,thenameofthereturnedvalueisthesameasthenameofthefunction:
1.3.2 RunningaMacro
Torunamacro:
SelectamacrointheAddinsandMacrosdialogueandclickRun,or
SelectamacrointheAddinsandMacrosdialogueanddoubleclickit,or
Clickthemacrosbuttoninthetoolbar.
Ifaproblemoccursduringthemacroexecution,anerrormessageisdisplayedinadialogueboxwiththelinenumberindi
cated.ThesamemessageisalsologgedintheAtollEventViewer.
1.3.3 SavingaListofMacros
OncemacroshavebeenaddedtoanAtollsession,theycanbesavedinaconfigurationfile.IfnodocumentisopeninAtoll,
youcanstillusetheTools>UserConfigurations>Savecommandforsavingthemacrosintheconfigurationfile.
Similartoallotherconfigurationfilecontents,iftheconfigurationfileisnamedAtoll.cfgandisstoredatthesamelocationas
Atoll.exe,Atollwillalwaysbestartedwiththelistofmacrossavedinthisconfigurationfile.Macroswillbeavailableevenif
noAtolldocumentisopen.Formoreinformationonconfigurationfiles,pleaserefertotheAdministratorManual.
1.4 WindowsScriptHost,32bitvs64bit
MicrosoftWindowsScriptHostisusedtorunscripts.
Ona64bitOS,thereisa32bitanda64bitversionofWindowsScriptHostavailable.BothcanbeusedtoscriptAtoll.The
AtollversionusedbyascriptdependsontheAtollversionsinstalled(32/64bit)andontheWindowsScriptHostversionused
torunthescript.
ThefollowingtableshowstheAtollversionlaunchedbyWindowsScriptHost:
Youneedtoexplicitlyuse32bitor64bitWindowsScriptHostonmachineswhereboth32bitAtolland64bitAtollare
installed.
25
Atoll3.2.1TaskAutomationGuide
Chapter1:GettingStarted
26
Forsk2014
Chapter2
ObjectModel
Atoll3.2.1TaskAutomationGuide
28
Forsk2014
Atoll3.2.1TaskAutomationGuide
Chapter2:ObjectModel
AT321_TAG_E1
2 ObjectModel
ThischapterdescribestheAtollobjectmodel.Figure 2.1onpage 29providesanoverviewoftheAtollobjectmodel.
Application
Documents
Document1
TabularData1
Document2
PropertyContainer1
TabularData1
PropertyContainer2
TabularData2
TabularData2
ChildFolder1
ChildFolder1
ChildFolder2
ChildFolder2
CoordSystem
CoordSystem
Figure 2.1:AtollObjectModel
Atollexposesanumberofobjectsofvarioustypes.TheseobjectsprovideaccesstoAtollcomponentsthroughpropertiesand
methods.Propertiesandmethodsusuallyhaveinputandoutputparameters.
TheobjectsexposedbyAtollare:
Name
Description
ApplicationObject
TheApplicationobjectprovidesanentrypointforclientstoretrieveand
navigatethroughtheAtollobjectmodel.
DocumentsObject
TheDocumentsobjectisusedtocreateanewdocumentortoiterate
throughopendocumentsinanAtollsession.
DocumentObject
TheDocumentobjectprovidesaccesstoATLdocumentsanddatabase
connections.
TabularDataObject
TheTabularDataobjectprovidesaccesstoAtolltableswhetheranAtoll
documentisconnectedtoadatabaseornot.Italsoprovidesaccesstoother
tableswhicharenotdatabasetables,suchasPREDICTIONSandZONES.
CoordSystemObject
Thisobjectcontainstheentiredefinitionofacoordinatesystem.
ChildFolderObject
AChildFolderobjectrepresentsanitemintheAtollExplorerwindow.
PropertyContainerObject
ThePropertyContainerobjectisagenericcontainercontainingasetof
namedpropertiesofarbitrarytypes
TransmitterObject
TheTransmitterobjectprovidesreadonlyaccesstoantennapatterns,
antennalosses,andsometransmitterproperties.
2.1 InterfacesImplementedbyObjects
AtollobjectsprovideaccesstoAtollcomponentsthroughpropertiesandmethods.
29
Atoll3.2.1TaskAutomationGuide
Chapter2:ObjectModel
Forsk2014
2.2 PropertiesandMethodsProvidedbyObjects
AccesstoAtollcomponentsisavailablethroughpropertiesandmethods.Propertiesandmethodsusuallyhaveinputand
outputparameters.
Forreadingandwritingaproperty,youwrite:
object.method
2.2.1 Parameters
Propertiesandmethodsmayhaveparameters.
InputParameters
Inputparametersaremarkedwith[in].Inputparametersarenotmutatedbymethodsorpropertysettersimplementation.
Inputparametersarespecifiedbyvalue.
OutputParameters
Output parameters are marked with [out]. Output parameters are specifiedby reference. Upon successfulcompletion of
methodsorpropertygetters,thereferencedvalueischanged.
Input/OutputDataTypes
BSTR
BSTRmaybeusedasamethodparameterdatatype.Itisusedtospecifyacharacterstring.InVBScript,itcorresponds
totheStringdatatype.
VARIANT
VARIANTmaybeusedasamethodparameterdatatype.Itisusedtospecifyvaluesofmanydifferenttypes,especially
arrays.ItcanbeusedbyVBScript.
2.2.2 ErrorInformation
Whenanerrorisreturnedbyapropertyormethod,anerrorinformationcontextiscreatedandanexceptionisthrown.Ifthe
scriptormacrodoesnotusetheOnErrorResumeNextstatement,itwillbeterminatedduetotheerror.
IfthescriptormacrousestheOnErrorResumeNextstatement,theerrorinformationisavailableaspropertiesofthescript
levelErrobject.Forexample,Err.Descriptionwhichprovidestheerrordescription:
In
Dim strDescription
If Err Then
strDescription = Err.Description
End If
PleaserefertotheVBScriptLanguageReferenceformoreinformationaboutVBScript,errorhandling,andtheErrscriptlevel
variable.
30
Chapter3
ApplicationObject
Atoll3.2.1TaskAutomationGuide
32
Forsk2014
Atoll3.2.1TaskAutomationGuide
Chapter3:ApplicationObject
AT321_TAG_E1
3 ApplicationObject
TheApplicationobjectprovidesanentrypointforclientstoretrieveandnavigatethroughtheAtollobjectmodel.
TheApplicationobjectprovidesthefollowingpropertiesandmethods:
Name
Description
Attributes
get_Application
ReturnstheAtollApplicationobject.
Type:Applicationobject
Access:Read
get_Parent
ReturnstheAtollApplicationobject.
Type:Applicationobject
Access:Read
get_Active
ReturnswhethertheAtollwindowisactive
ornot.
Type:Boolean
Access:Read/Write
put_Active
SetstheAtollwindowactive.
Type:Boolean
Access:Read/Write
get_Documents
ReturnstheDocumentsobject.
Type:Documentsobject
Access:Read
get_Name
Returnstheapplicationname.The
applicationnameisalways"Atoll".
Type:String
Access:Read
get_FullName
Returnsthefullpathoftheexecutable.
Type:String
Access:Read
get_Path
Returnsthepathoftheexecutable.
Type:String
Access:Read
get_ActiveDocument
Returnstheactivedocument.
Type:Documentobject
Access:Read
get_WindowStatus
ReturnsthewindowstatusoftheAtoll
application.
Type:Integer
Access:Read/Write
put_WindowStatus
SetsthewindowstatusoftheAtoll
application.
Type:Integer
Access:Read/Write
put_StatusBar
SetsthestatusbartextoftheAtoll
application.
Type:String
Access:Write
get_Visible
Returnstheapplicationvisiblestate.
Type:Boolean
Access:Read/Write
put_Visible
Setstheapplicationvisiblestate.
Type:Boolean
Access:Read/Write
get_Version
Returnstheapplicationversion.
Type:String
Access:Read
Quit
Quitstheapplication.
LogMessage
DisplaysamessageintheAtollevent
observerwindow.
CreatePropertyContainer
ReturnsanemptyPropertyContainerobject.
get_IniFileFullPath
ReturnsthefullpathtotheAtollinitialisation
file.
Type:String
Access:Read/Write
put_IniFileFullPath
SetsthefullpathtotheAtollinitialisation
file.
Type:String
Access:Read/Write
GetOption
ReturnsanoptionreadfromtheAtoll
initialisationfile.
SetOption
SetsanoptionintheAtollinitialisationfile.
33
Atoll3.2.1TaskAutomationGuide
Chapter3:ApplicationObject
Forsk2014
Name
Description
Sleep
Suspendstheapplicationapartment
execution.
Attributes
TheApplicationobjectfiresthefollowingevents:
Name
Description
WillQuitApp
EventfiredwhentheuserwantstoexitanAtollsession.
DocumentOpenComplete
Eventfiredwhenadocumenthasbeenopened
WillCloseDocument
Eventfiredwhentheuserwantstocloseadocument.
WillSaveDocument
Eventfiredwhentheuserwantstosaveadocument.
DocumentSaveComplete
Eventfiredjustafteradocumenthasbeensaved.
DocumentNewComplete
Eventfiredwhenanewdocumenthasbeencreated.
WillRefreshDocument
Eventfiredwhentheuserwantstorefreshadocumentfromdatabase.
RefreshDocumentComplete
Eventfiredwhenadocumenthasbeenrefreshedfromdatabase.
WillArchiveDocument
Eventfiredwhentheuserwantstoarchiveadocumenttothedatabase.
ArchiveDocumentComplete
Eventfiredwhenthedocumenthasbeenarchivedindatabase.
WillRun
Eventfiredwhentheuserwantstostartacalculation.
RunComplete
Eventfiredwhenthecalculationhasfinished.
LicenceAcquireComplete
ThisfeatureenablestheusertologAtolllicencetokenusagefromanaddin.
LicenceReleaseComplete
ThisfeatureenablestheusertologAtolllicencetokenusagefromanaddin.
3.1 HowtoAccesstheApplicationObject
Theapplicationobjectisthetoplevelobject.Subobjectsareobtainedthroughpropertiesoftheapplication.Togetanappli
cationobjectinVBScript,useoneofthefollowing:
Using GetObject("", "Atoll.Application") (note the difference in the first parameter) will
automaticallystartanewinstanceofAtollifnosessionisalreadyrunningandattachthe
macrotothisnewinstance.
EachcalltoGetObject("","Atoll.Application")willstartanewAtollinstance.Ifthisisnot
intended,useGetObject(,Atoll.Application),whichattachesthescripttothefirstAtoll
sessionstartedwhenseveralsessionsarerunning.
Inthecontextofmacros,aninstanceofthemainobjectApplicationisautomaticallyaddedasaglobalvariableofthemacro
code.Therefore,itmustnotcallCreateObjectorGetObjecttogetanApplicationobject.
TheglobalvariableoftypeApplicationobjectavailabletomacrosisnamed"Atoll".
3.2 get_Application
ReturnstheAtollApplicationobject.
34
Atoll3.2.1TaskAutomationGuide
Chapter3:ApplicationObject
AT321_TAG_E1
3.3 get_Parent
ReturnstheAtollApplicationobject.
3.4 get_Active
ReturnswhethertheAtollwindowisactiveornot.
3.5 put_Active
Setsthemainapplicationwindowactive.
VARIANT_TRUE:Activatesthemainwindowapplication.
Example
See"get_Active"onpage 35.
3.6 get_Documents
ReturnstheDocumentsobject.
35
Atoll3.2.1TaskAutomationGuide
Chapter3:ApplicationObject
3.7 get_Name
Returnstheapplicationname.Theapplicationnameisalways"Atoll".
3.8 get_FullName
Returnsthefullpathoftheexecutable.
3.9 get_Path
Returnsthepathoftheexecutable.
3.10 get_ActiveDocument
Returnstheactivedocument.
36
Forsk2014
Atoll3.2.1TaskAutomationGuide
Chapter3:ApplicationObject
AT321_TAG_E1
3.11 get_WindowStatus
ReturnsthewindowstatusoftheAtollapplication.
3.12 put_WindowStatus
SetsthewindowstatusoftheAtollapplication.
3.13 put_StatusBar
SetsthestatusbartextoftheAtollapplication.
37
Atoll3.2.1TaskAutomationGuide
Chapter3:ApplicationObject
Forsk2014
3.14 get_Visible
Returnstheapplicationvisiblestate.
3.15 put_Visible
Setstheapplicationvisiblestate.
VARIANT_TRUE:MakesAtollvisible.
VARIANT_FALSE:HidesAtoll.
Remarks
WhenAtollisnotvisible,adialoguethatwouldnormallyrequireuserinputisautomaticallyclosedasiftheuserhasclicked
itsdefaultbuttonwithoutchanginganyofthedialoguecontrols.
3.16 get_Version
Returnstheapplicationversion.
38
Atoll3.2.1TaskAutomationGuide
Chapter3:ApplicationObject
AT321_TAG_E1
Remarks
ThestringisformattedlikeintheAtollaboutdialogue,forexample,"2.6.1".
Atoll3.1.0andabove:
Theapplicationbuildnumberisincludedinthestring,forexample,"3.1.0(Build3730)"
3.17 Quit
Quitstheapplication.
atoSaveNo:Discardsdocumentchanges,thenclosestheapplication.
atoSaveYes:Savesdocumentchanges,thenclosestheapplication.
atoSavePrompt:Theuserispromptedtosavedocumentchanges,thentheapplicationisclosed.
[out]pStatus:TheAtoSaveStatusenumerationpointerusedtoreturnwhetherchangesweresuccessfullysavedornot.
ReturnsatoSaveCanceledwhentheuserwaspromptedandhaschosennottosavethechanges,otherwisereturns
atoSaveSucceeded.
3.18 LogMessage
DisplaysamessageintheAtolleventobserverwindow.
atoInfo:Aninformationmessageisdisplayed.
atoError:Anerrormessageisdisplayed.
atoWarning:Awarningmessageisdisplayed.
:
4.
5.
:
3.19 CreatePropertyContainer
ReturnsanemptyPropertyContainerobject.
39
Atoll3.2.1TaskAutomationGuide
Chapter3:ApplicationObject
Forsk2014
Remarks
TheVARIANTreturnedifoftypeVT_DISPATCH,anditimplementstheIPropertyContainerinterface.Theemptycontainer
returnedcanbeusedtoholddefaultparametersspecifictoanAtolldocumentcommandortoholdanAtollChildFolder
Objectproperties.
3.20 get_IniFileFullPath
ReturnsthefullpathtotheAtollInitialisationFile.
3.21 put_IniFileFullPath
SetsthefullpathtotheAtollInitialisationFile.
3.22 GetOption
ReturnsanoptionreadfromtheAtollInitialisationFile.
40
Atoll3.2.1TaskAutomationGuide
Chapter3:ApplicationObject
AT321_TAG_E1
Remarks
PleaserefertotheAtollAdministratorManualforthelistofavailablesectionsandoptions.
3.23 SetOption
SetsanoptionintheAtollInitialisationFile.
3.24 Sleep
Suspendstheapplicationapartmentexecution.
3.25 SetAddinInfoEx
Reservedforfutureuse.
HRESULT SetAddinInfoEx(
LONGLONG hInstance,
LPDISPATCH dispatch,
long idr,
long cookie
);
41
Atoll3.2.1TaskAutomationGuide
Chapter3:ApplicationObject
Forsk2014
Parameters
3.26 put_OLENotRespondingDialog
EnablesordisablesOLEnotrespondingdialog.
3.27 put_OLEBusyDialog
EnablesordisablesOLEbusydialog.
3.28 put_OLEMessagePendingDelay
SetstheOLEmessagependingdelay.
3.29 ApplicationEvents
Eventsrelatedtotheapplicationarefired:
Beforetheapplicationshutsdown,
Whenadocumenthasjustbeenopened,
Beforeadocumentisclosed,
Beforeadocumentissaved,
Whenadocumenthasbeensaved,
Whenanewdocumenthasjustbeencreated,
Beforeadocumentisrefreshedfromdatabase,
Whenadocumenthasbeenrefreshedfromdatabase,
Beforeadocumentisarchivedindatabase,
Whenadocumenthasbeenarchivedindatabase,
Whenacalculationisrequested,
Afteracalculationhascompleted,
Whenalicenceisacquired,
Whenalicenceisreleased,
Beforeanewdocumentiscreatedfromanexistingdatabase.
3.29.1 WillQuitApp
EventfiredwhentheuserwantstoexitanAtollsession.Itoccursjustbeforealladdinsaredisconnectedandafteralldocu
mentshavebeenclosed.
42
Atoll3.2.1TaskAutomationGuide
Chapter3:ApplicationObject
AT321_TAG_E1
3.29.2 DocumentOpenComplete
Eventfiredwhenadocumenthasbeenopened.
3.29.3 WillCloseDocument
Eventfiredwhentheuserwantstocloseadocument.Itoccursjustbeforethedocumentcloses,i.e.,afterallconfirmations
requestedbyAtollhavebeenanswered(stoprunningtasks,savechanges,etc...).
3.29.4 WillSaveDocument
Eventfiredwhentheuserwantstosaveadocument.Itoccursjustbeforethedocumentfileissavedbutafteravalidfilename
isset.
3.29.5 DocumentSaveComplete
Eventfiredjustafteradocumenthasbeensaved.
3.29.6 DocumentNewComplete
Eventfiredwhenanewdocumenthasbeencreated.
43
Atoll3.2.1TaskAutomationGuide
Chapter3:ApplicationObject
Forsk2014
3.29.7 WillRefreshDocument
Eventfiredwhentheuserwantstorefreshadocumentfromdatabase.Itoccursjustbeforetheconnectionwiththedatabase
ischecked.
3.29.8 RefreshDocumentComplete
Eventfiredwhenadocumenthasbeenrefreshedfromdatabase.
3.29.9 WillArchiveDocument
Eventfiredwhentheuserwantstoarchiveadocumenttothedatabase.Itoccursjustaftertheconnectionwiththedatabase
issetupandafterAtollhascheckedifanychangeshavetobearchived.Ifnothingrequiresarchiving,thiseventisnotfired.
3.29.10 ArchiveDocumentComplete
Eventfiredwhenthedocumenthasbeenarchivedindatabase.Itoccursjustbeforetheconnectionwiththedatabaseis
broken.
3.29.11 WillRun
Eventfiredwhentheuserwantstostartacalculation.IfallissettoVARIANT_TRUE,thiseventoccursaftertheuserhas
confirmedthatallpreviouscalculationsmustbedeleted.
44
Atoll3.2.1TaskAutomationGuide
Chapter3:ApplicationObject
AT321_TAG_E1
HRESULT WillRun(
IDocument* document,
VARIANT_BOOL all,
VARIANT_BOOL* evtStatus
);
Parameters
[in]document:TheIDocumentinterfacepointerofthedocumentonwhichcalculationisrequested.
[in]all:AVARIANT_BOOLvalueusedtospecifywhethertheuserhasrequested"CalculateAll(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)ornot(VARIANT_FALSE).
3.29.12 RunComplete
Eventfiredwhenthecalculationhasfinished.Itoccursafteralltaskshavecompleted.
3.29.13 LicenceAcquireComplete
ThisfeatureenablestheusertologAtolllicencetokenusagefromanaddin.Licencetokenconsumptionisavailableglobally
forallAtollinstancesrunningononelicenceserverusingadedicatedapplication(monitor.exe).
Externallicencetokensarenottrackedbythisevent.LicenceeventsfortheMeasurementsmodule(Measures)isavailable
forautoconnectedaddinsonly.
Firedwhenonelicencetokenisacquired.
HRESULT LicenceAcquireComplete(
IDocument *pDocument,
long lModuleID
);
Parameters
[in]pDocument:TheIDocumentinterfacepointerofthedocumentthatneededonelicencetoken.
[in]lModuleID:ThelongintegerusedtospecifytheIDofthelicencetokenthathasjustbeenacquired.
45
Atoll3.2.1TaskAutomationGuide
Chapter3:ApplicationObject
Forsk2014
Remarks
lModuleIDwillbeoneoftheseconstantvalues:
LICENCE_GSMTDMA
LICENCE_MW
LICENCE_MEASURES
LICENCE_AFP
LICENCE_PACK3G
LICENCE_UMTS
LICENCE_CDMA
LICENCE_TDSCDMA
LICENCE_WIMAX
LICENCE_LTE
ForLICENCE_MEASUREStoken,pDocumentwillbeNULL.
Moduleidentifiersusedwhenlicenceapplicationeventsarefired:
3.29.14 LicenceReleaseComplete
ThisfeatureenablestheusertologAtolllicencetokenusagefromanaddin.Licencetokenconsumptionisavailableglobally
forallAtollinstancesrunningononelicenceserverusingadedicatedapplication(monitor.exe).
Externallicencetokensarenottrackedbythisevent.LicenceeventsfortheMeasurements(Measures)modulewillbeavail
ableforautoconnectedaddinsonly.
Firedwhenonelicencetokenisreleased.
HRESULT LicenceReleaseComplete(
IDocument *pDocument,
long lModuleID
);
Parameters
[in]pDocument:TheIDocumentinterfacepointerofthedocumentthatjustreleasedthelicencetoken.
[in]lModuleID:ThelongintegerusedtospecifytheIDofthelicencetokenthathasjustbeenreleased.
Remarks
lModuleIDwillbeoneoftheseconstantvalues:
46
LICENCE_GSMTDMA
Atoll3.2.1TaskAutomationGuide
Chapter3:ApplicationObject
AT321_TAG_E1
LICENCE_MW
LICENCE_PACK3G
LICENCE_UMTS
LICENCE_CDMA
LICENCE_TDSCDMA
LICENCE_WIMAX
LICENCE_LTE
3.29.15 WillNewDocumentFromDatabase
3.2.0
Firedjustbeforeanewdocumentiscreatedfromanexistingdatabase.
HRESULT WillNewDocumentFromDatabase(
BSTR connexion,
BSTR schema,
VARIANT_BOOL *pEvtStatus
);
Parameters
[in]connexion:Thedatabaseconnexionstring.
[in]schema:Thedatabaseschema.
[out]evtStatus:AVARIANT_BOOLpointerusedtoreturnwhetherthecreationofthenewdocumentfromthedatabaseiden
tifiedbytheconnexionandschemaparametersisallowed(VARIANT_TRUE)ornot(VARIANT_FALSE).
47
Atoll3.2.1TaskAutomationGuide
Chapter3:ApplicationObject
48
Forsk2014
Chapter4
DocumentsObject
Atoll3.2.1TaskAutomationGuide
50
Forsk2014
Atoll3.2.1TaskAutomationGuide
Chapter4:DocumentsObject
AT321_TAG_E1
4 DocumentsObject
TheDocumentsobjectisusedtocreateanewdocumentortoiteratethroughopendocumentsinanAtollsession.
TheDocumentsobjectprovidesthefollowingpropertiesandmethods:
Name
Description
Attributes
get_Count
Returnsthenumberofcurrentlyopendocumentsinan
Atollsession.
Type:Integer
Access:Read
get_Item
ReturnsonedocumentcurrentlyopeninanAtollsession.
Type:Documents
object
Access:Read
get_Application
ReturnstheAtollapplicationobject.
Type:Application
object
Access:Read
get_Parent
ReturnstheAtollapplicationobject.
Type:Application
object
Access:Read
Open
Opensanexistingdocumentandaddsittothecollectionof
opendocuments.
Add
Createsanewdocumentandaddsittothecollectionof
opendocuments.
OpenFromDatabase
Createsanewdocumentfromadatabaseandaddsitto
thecollectionofopendocuments.
CloseAll
Closesallopendocuments.
SaveAll
Savesallopendocuments.
4.1 HowtoAccessaDocumentsObject
ToaccessaDocumentsobject:
Dim allDocs
Set allDocs = Atoll.Documents
The"ForEach"VBScriptstatementcanbeusedwiththeDocumentscollectionobject:
Dim allDocs
Dim doc
Set allDocs = Atoll.Documents
For Each doc In allDocs
do some work with doc
...
Next
51
Atoll3.2.1TaskAutomationGuide
Chapter4:DocumentsObject
Forsk2014
4.2 get_Count
ReturnsthenumberofcurrentlyopendocumentsinanAtollsession.
4.3 get_Item
ReturnsonedocumentcurrentlyopeninanAtollsession.
4.4 get_Application
ReturnstheAtollapplicationobject.
4.5 get_Parent
ReturnstheAtollapplicationobject.
HRESULT get_Parent(IApplication **ppVal);
Parameters
[out]ppVal:AddressoftheIApplicationinterfacepointerusedtoreturntheAtollapplicationobject.
4.6 Open
Opensanexistingdocumentandaddsittothecollectionofopendocuments.
52
Atoll3.2.1TaskAutomationGuide
Chapter4:DocumentsObject
AT321_TAG_E1
HRESULT Open(const
**pDoc);
BSTR
bstrPathName,
VARIANT_BOOL
aReadOnly,
IDocument
Parameters
[in]bstrPathName:Theabsolutepathofthedocumenttoopen.
[in]readOnly:VARIANT_TRUEmeansthedocumentwillbeopenedinreadonlymode.VARIANT_FALSEmeansthedocument
willbeopenedinreadwritemode.
[out]pDoc:AddressoftheIDocumentinterfacepointerusedtoreturntheopenDocumentobject.
Example
Dim doc
Set doc = app.Documents.Open(C:\Temp\myProject.atl)
4.7 Add
Createsanewdocumentandaddsittothecollectionofopendocuments.
4.8 OpenFromDatabase
Createsanewdocumentfromadatabaseandaddsittothecollectionofopendocuments.
Value
Version
Description
Project
string
2.6.0
Databaseschema
53
Atoll3.2.1TaskAutomationGuide
Chapter4:DocumentsObject
Forsk2014
KeepConnection
0|1
2.6.0
Whethertokeepconnectionwiththedatabaseornot
FieldGroups
groupname
[,groupname]
2.6.0
Commaseparatedvaluesoffieldgroups
SiteLists
sitelist[,sitelist]
2.6.0
Commaseparatedvaluesofsitelists
IntraTechnology
Neighbours
0|1
2.6.1
Whethertoloadthetable"NEIGHBOURS"ornot
InterTechnology
Neighbours
0|1
2.6.1
Whethertoloadthetable"NEIGHBOURSEXT"ornot
3.1.2
Commaseparatedvaluesofsystems.
Whencreatinganewdocumentfroma3GPPMultiRAT
database,itisusedtospecifytheradioaccesstechnologies
toload.
Availablevaluesforsystemsare:
GSM
UMTS
LTE
Whennopropertynamed"Systems"isspecifiedinthe
schemastring,allradiotechnologiesareloaded.
Systems
system,[system]
[out]pDoc:AddressoftheIDocumentinterfacepointerusedtoreturnthenewDocumentobject.
Remarks
Adialogueboxisdisplayedtoentertheschemapropertiesinthethesecases:
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.
Nodialogueboxisdisplayedwhenaprojectisspecified,andwhenthesitelistspropertyoftheschemaparameterissetto
"<ALL>".Inthiscase,allsitesareloadedfromthedatabase.
Example
CreatinganewdocumentfromaMSAccessdatabase:
CreatinganewdocumentfromanOracledatabase,withnodialoguebox:
Creatinganewdocumentfroma3GPPMultiRATOracledatabase,loadingLTEandUMTSinformationonly:
4.9 CloseAll
Closesallopendocuments.
54
Atoll3.2.1TaskAutomationGuide
Chapter4:DocumentsObject
AT321_TAG_E1
Parameters
[in]saveChanges:
atoSaveNo:Discardsdocumentchanges,thenclosesallopendocuments.
atoSaveYes:Savesdocumentchanges,thenclosesallopendocuments.
atoSavePrompt:Theuserispromptedtosavedocumentchanges,thenallopendocumentsareclosed.
[out]status:TheAtoSaveStatusenumerationpointerusedtoreturnwhetherchangesweresuccessfullysavedornot.
ReturnsatoSaveCanceledwhentheuserwaspromptedandhaschosennottosavethechanges,otherwisereturns
atoSaveSucceeded.
4.10 SaveAll
Savesallopendocuments.
HRESULT SaveAll();
55
Atoll3.2.1TaskAutomationGuide
Chapter4:DocumentsObject
56
Forsk2014
Chapter5
DocumentObject
Atoll3.2.1TaskAutomationGuide
58
Forsk2014
Atoll3.2.1TaskAutomationGuide
Chapter5:DocumentObject
AT321_TAG_E1
5 DocumentObject
TheDocumentobjectprovidesaccesstoATLdocumentsanddatabaseconnections.Adocumentcanbemanaged(open,save,
close,etc.)usingitspropertiesandmethods.Adocumentisalsothemainentrytomanageallthedataitcontains.
TheDocumentobjectprovidesthefollowingpropertiesandmethods:
Name
Description
Attributes
get_Application
ReturnstheAtollApplicationObject.
Type:Application
object
Access:Read
get_Parent
ReturnstheAtollDocumentscollection.
Type:Documents
object
Access:Read
get_FullName
Returnsthedocumentfullpath.
Type:String
Access:Read
get_Name
Returnsthedocumentfilenamewithouttheextension.
Type:String
Access:Read
get_Path
Returnsthedocumentpath.
Type:String
Access:Read
get_ReadOnly
Returnstrueifthedocumentisreadonly,falseotherwise.
Type:Boolean
Access:Read
get_Saved
Returnsfalseifthedocumentcontainsunsavedchanges,
trueotherwise.
Type:Boolean
Access:Read
get_CoordSystemProjection
Returnstheprojectioncoordinatesystemofadocument.
Type:CoordSystem
object
Access:Read/Write
putref_CoordSystemProjection
Setstheprojectioncoordinatesystemofadocument.
Type:CoordSystem
object
Access:Read/Write
get_CoordSystemDisplay
Returnsthedisplaycoordinatesystemofadocument.
Type:CoordSystem
object
Access:Read/Write
putref_CoordSystemDisplay
Setsthedisplaycoordinatesystemofadocument.
Type:CoordSystem
object
Access:Read/Write
get_CoordSystemInternal
Returnstheinternalcoordinatesystemofadocument.
Type:CoordSystem
object
Access:Read
get_TransmissionUnit
Returnsthetransmissionpowerunit.
Type:Integer
Access:Read/Write
put_TransmissionUnit
Setsthetransmissionpowerunit.
Type:Integer
Access:Read/Write
get_ReceptionUnit
Returnsthesignallevelreceptionunit.
Type:Integer
Access:Read/Write
put_ReceptionUnit
Setsthesignallevelreceptionunit.
Type:Integer
Access:Read/Write
get_DistanceUnit
Returnsthedisplaydistanceunit.
Type:Integer
Access:Read/Write
put_DistanceUnit
Setsthedisplaydistanceunit.
Type:Integer
Access:Read/Write
59
Atoll3.2.1TaskAutomationGuide
Chapter5:DocumentObject
60
Forsk2014
Name
Description
Attributes
Close
Closesadocument.
FilePrint
Sendsadocumenttoaprinter.
Save
Savesadocument.
Refresh
Refreshesthedocumentfromadatabase.
Archive
Archivesthedocumentinadatabase.
Run
Startscalculations.
SetConfig
Loadsaconfigurationfile.
Import
Loadsafilecontaininggeographicdata.
GetRecords
ReturnsaTabularDataobjectforarequestedcategoryof
records.
Redraw
Refreshesallitemsinthedocument.
CenterMapOn
Centresmaponaparameterpoint.
GetRootFolder
ReturnstherootChildFolderobjectusedtoenumerateall
ChildFolderobjectsbelongingtoonetaboftheAtoll
explorerwindow.
RunPathloss
Calculatesthepathlossmatriceswithnoneedforany
predefinedstudies.
GetService
ReturnsaDocumentServiceObject.
ExportConfig
Exportsasubsetofthecurrentdocumentconfigurationtoa
file.
GetCommandDefaults
Returnscurrentdefaultparametersspecifictoacommand.
InvokeCommand
Invokesacommand.
get_RadiatedPowerUnit
Returnsthecurrentradiatedpowerunit.
Type:Integer
Access:Read/Write
put_RadiatedPowerUnit
Setsthecurrentradiatedpowerunit.
Type:Integer
Access:Read/Write
get_AntennaGainUnit
Returnsthecurrentantennagainunit.
Type:Integer
Access:Read/Write
put_AntennaGainUnit
Setsthecurrentantennagainunit.
Type:Integer
Access:Read/Write
get_HeightOffsetUnit
Returnsthecurrentheightoffsetunit.
Type:Integer
Access:Read/Write
put_HeightOffsetUnit
Setsthecurrentheightoffsetunit.
Type:Integer
Access:Read/Write
get_DatabaseConnectionString
Returnsthedatabaseconnectionstring.
Type:String
Access:Read/Write
HasRunningTask
Returnstruewhenthereissomecalculationinprogress.
Type:Boolean
Access:Read
RunEx
Startscalculations.
get_DatabaseSchemaString
Returnsthedatabaseschemastring.
Type:String
Access:Read/Write
get_DisplayApplicationDialogues
ReturnstruewhensomemethodsonsomeAtollinterfaces
maydisplaysomedialogueboxes.
Type:Boolean
Access:Read/Write
Atoll3.2.1TaskAutomationGuide
Chapter5:DocumentObject
AT321_TAG_E1
Name
Description
Attributes
put_DisplayApplicationDialogues
ReturnstruewhensomemethodsonsomeAtollinterfaces
maydisplaysomedialogueboxes.
Type:Boolean
Access:Read/Write
PutDatabaseSchemaString
Setsthedatabaseschemastring.
Type:String
Access:Read/Write
PutDatabaseConnectionString
Setsthedatabaseconnectionstring.
Type:String
Access:Read/Write
ChangeDatabaseConnection
Changesthedatabaseconnectionstring.
Type:String
Access:Read/Write
5.1 HowtoAccessaDocumentObject
Toaccessadocument,youcaneither:
1. Requesttheactivedocumentfromtheapplication:
5.2 get_Application
ReturnstheAtollApplicationObject.
5.3 get_Parent
ReturnstheAtollDocumentscollection.
5.4 get_FullName
Returnsthedocumentfullpath.
61
Atoll3.2.1TaskAutomationGuide
Chapter5:DocumentObject
Forsk2014
Remarks
Withanewdocumentthathasneverbeensaved,oradocumentopenedfromadatabase,anemptystringisreturned.
5.5 get_Name
Returnsthedocumentfilenamewithouttheextension.
5.6 get_Path
Returnsthedocumentpath.
5.7 get_ReadOnly
Returnstrueifthedocumentisreadonly,falseotherwise.
5.8 get_Saved
Returnsfalseifthedocumentcontainsunsavedchanges,trueotherwise.
5.9 get_CoordSystemProjection
Returnstheprojectioncoordinatesystemofadocument.
62
Atoll3.2.1TaskAutomationGuide
Chapter5:DocumentObject
AT321_TAG_E1
5.10 putref_CoordSystemProjection
Setstheprojectioncoordinatesystemofadocument.
5.11 get_CoordSystemDisplay
Returnsthedisplaycoordinatesystemofadocument.
5.12 putref_CoordSystemDisplay
Setsthedisplaycoordinatesystemofadocument.
5.13 get_CoordSystemInternal
Returnstheinternalcoordinatesystemofadocument.
63
Atoll3.2.1TaskAutomationGuide
Chapter5:DocumentObject
5.14 get_TransmissionUnit
Returnsthetransmissionpowerunit.
5.15 put_TransmissionUnit
Setsthetransmissionpowerunit.
5.16 get_ReceptionUnit
Returnsthesignallevelreceptionunit.
5.17 put_ReceptionUnit
Setsthesignallevelreceptionunit.
5.18 get_DistanceUnit
Returnsthedisplaydistanceunit.
5.19 put_DistanceUnit
Setsthedisplaydistanceunit.
64
Forsk2014
Atoll3.2.1TaskAutomationGuide
Chapter5:DocumentObject
AT321_TAG_E1
5.20 Close
Closesadocument.
Value
Description
atoSaveNo
Documentisclosedwithoutbeingsaved.
atoSaveYes
Documentissavedbeforebeingclosed.
atoSavePrompt
Theuserispromptedwhetherthedocumentmustbesavedbefore
closed.
status:atoSucceededifsavewasforcedtoatoSaveYesoratoSaveNooriftheuserwaspromptedandhehasanswered[out]
pStatus:AddressoftheAtoSaveStatusenumerationvalue.Returnedvaluesare:
Constant
Value
Description
atoSaveSucceeded
Documenthasbeensuccessfullysaved.
atoSaveCanceled
Changesinthedocumenthasbeencancelledbytheuser.
5.21 FilePrint
Sendsadocumenttoaprinter.Thecurrentprintsettingsareused.
HRESULT FilePrint();
5.22 Save
Savesadocument.
5.23 Refresh
Refreshesthedocumentfromadatabase.Thedocumentmustbeconnectedtoadatabase.
65
Atoll3.2.1TaskAutomationGuide
Chapter5:DocumentObject
Forsk2014
5.24 Archive
Archivesthedocumentinadatabase.Thedocumentmustbeconnectedtoadatabase.
5.25 Run
Startscalculations.
5.26 SetConfig
Loadsaconfigurationfile.
66
Atoll3.2.1TaskAutomationGuide
Chapter5:DocumentObject
AT321_TAG_E1
5.27 Import
Loadsafilecontaininggeographicdata.
An.CFGfile.Alldatafromitsgeographicsectionareloaded.PleaseseetheAtollAdministratorManual.
AnyfileformatsupportedbyAtoll(.BIL,.TIF,etc).
Thegeographiccontentoftheimportedfile(.CFG,.GEO,.BIL,.TIF,etc.)isaddedtothecurrentconfigurationofthegeographic
datainthedocument.Theexistinggeographicconfigurationisnotremoved.
Ifyouwanttoreplacethegeographicconfigurationofadocument,youshouldusetheSetConfigfunctioninstead.
Youmustensurethatnoinputsarerequestedfromtheuserwhenimportingthefile(for
instancethefiletype,georeferencementparameters,etc.)whentheapplicationisnot
visible.
5.28 GetRecords
ReturnsanAtollTabularDataObjectforarequestedcategoryofrecords.
n
HRESULT GetRecords(
const BSTR bstrTableName,
VARIANT_BOOL aAll,
ITabularData *ppRecords
);
Parameters
[in]bstrTableName:ABSTRusedtospecifythenameofthetablefromwhichtherecordsarerequested.
[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_FALSEandwhenthereisanAtolldocumentfolderassociatedwithbstrTableName,thefiltersetonthedocument
folderisusedtofilterthereturnedrecords.Ifnoassociatedfolderexists,thisparameterisignored.
[out]ppRecords:AddressoftheITabularDatainterfacepointerusedtoreturntheAtollTabularDataObject.
Remarks
Thelistofavailabletablenamesdefined by Atollcanbe found inthetemplate (.MDB)file. Please see the Administrator
Manualfortheavailabletablenames.Someothertablenamesareavailable:
PREDICTIONS:togetpathlossmatricesandsignallevelmatrices.
ZONES:togeteitherthecalculationzoneorthefocuszone.
ChangesintroducedinAtollversion2.7.1andabove
1)Table"REPEATERS_VIEW"
WhenbstrTableNameisequaltoREPEATERS_VIEW,theTabularDataobjectreturnedisajoinonthe"TRANSMITTERS"and
the"REPEATERS"table.Thefieldsreturnedwillbethe"TRANSMITTERS"tablefieldsandthe"REPEATERS"tablefields,where
TRANSMITTERS.TX_ID=REPEATERS.TX_ID.Thenameofthefieldsofthe"REPEATERS"tableinthe"REPEATERS_VIEW"are
67
Atoll3.2.1TaskAutomationGuide
Chapter5:DocumentObject
Forsk2014
prefixedwith"TX_ID."whereasthenamesofthefieldscomingfromthe"TRANSMITTERS"tableareleftunchanged.When
aAll is VARIANT_FALSE, then the filter set on the Transmitters folder of the Atoll document is used to filter the
REPEATERS_VIEWtablerecords,otherwiseallrepeatersorremoteantennasarereturned.Aremoteantennaisarepeater
whiththefieldEQUIPMENT_NAMEsettoVT_NULL.
2)Table"REPEATERS"
WhenbstrTableNameisequaltoREPEATERS,andaAllisVARIANT_FALSE,thenthefiltersetontheTransmittersfolderof
theAtolldocumentisusedtofiltertheREPEATERStablerecords,otherwiseallrepeatersorremoteantennasarereturned.
AremoteantennaisarepeaterwhiththefieldEQUIPMENT_NAMEsettoVT_NULL.
ChangesintroducedinAtollversion3.1.1andabove
1)Table"MWLinks"
When bstrTableName is equal to MWLinks, the TabularData object returned has an additional column named
"_LINK_LENGTH",usedtoaccessthelengthofMicrowavelinksassingleprecisionfloatingpointvalues.
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
Refreshesallitemsinthedocument.
HRESULT Redraw();
Remarks
IthasthesameeffectastheiconRefresh(F5)inAtoll.
5.30 CenterMapOn
Centresmaponaparameterpoint.
5.31 GetRootFolder
ReturnstherootAtollChildFolderObjectusedtoenumerateallChildFolderobjectsbelongingtoonetaboftheAtollexplorer
window.
68
Atoll3.2.1TaskAutomationGuide
Chapter5:DocumentObject
AT321_TAG_E1
Parameters
[in]aType:TheAtoRootTypeenumerationvalueusedtospecifytheAtollexplorerwindowtab.ThereisonerootChildFolder
objectforeachtaboftheAtollexplorerwindow.
[out]ppItem:AddressoftheIChildFolderinterfacepointerusedtoreturntherootChildFolderobject.
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
Calculatesthepathlossmatriceswithnoneedforanypredefinedstudies.
'"Wait" Loop
Do While AtollDoc.HasRunningTask
WScript.Sleep 1000
Loop
5.33 GetService
ReturnsascriptableDocumentServiceObject.
69
Atoll3.2.1TaskAutomationGuide
Chapter5:DocumentObject
Forsk2014
Theavailablevaluesare:
"SIGNAL":AResultFileProviderobject,implementingtheIResultFileProviderinterface.
OndocumentsbasedontheGSMGPRSEDGEtemplate:
"AFP":AGSMFrequencyPlanAllocationobject,implementingtheIAfpLauncherinterface.
"AFP_IM":AGSMInterferenceMatricesobject,implementingtheIAfpImLauncherinterface.
[out]ppProvider:AddressoftheIDispatchinterfacepointerusedtoreturnthescriptableDocumentServiceObject.
5.34 ExportConfig
Exportsasubsetofthecurrentdocumentconfigurationtoafile.
"GEO":The"GeographicDataSet"configurationisexported.
"GEO+ZONES":The"GeographicDataSet"and"ComputationandFocusZones"configurationsareexported.
"FULL":Allavailableconfigurationsareexported.
Atoll2.7.1andabove:
bstrContentisparsedaccordingtotheformat"OPTION[+OPTION]".ThesetofspecifiedoptionsareexportedtobstrFile.Avail
ableoptionsare:
OPTIONname
Description
GEO
GeographicDataSet
ZONES
ComputationandFocusZones
STUDIES
PredictionList
OPTIONname
Description
FOLDERS
FolderConfiguration
MACROS
Macros
AFP
AFPConfiguration
ANP
AutomaticNeighbourAllocationParameters
MW
MicrowaveLinkParameters
PNO
AutomaticPNOffsetAllocationParameters
SCP
AutomaticScramblingCodeAllocationParameters
[in]bstrFile:ABSTRusedtospecifythenameoftheexportfile.
5.35 GetCommandDefaults
Returnscurrentdefaultparametersspecifictoacommand.
HRESULT GetCommandDefaults(
const BSTR bstrCommandName,
70
Atoll3.2.1TaskAutomationGuide
Chapter5:DocumentObject
AT321_TAG_E1
IPropertyContainer **ppParameters
);
Parameters
[in]bstrCommandName:ABSTRusedtospecifythecommand.
[out] ppParameters: Address of the IPropertyContainer interface pointer used to return the defaults parameters for the
bstrCommandNamecommand.
5.36 InvokeCommand
Invokesacommand.
HRESULT InvokeCommand(
const BSTR bstrCommandName,
IPropertyContainer *pParameters,
IPropertyContainer **ppResults
);
Parameters
[in]bstrCommandName:ABSTRusedtospecifythecommand.
[in]pParameters:TheIPropertyContainerinterfacepointerusedtospecifythePropertyContainerobjectholdingtheparam
etersneededtocarryoutthecommand.
IfsettoNULL,defaultparametersforthecommandwillbeused.
ppResults:Resultsofthecommandinvokation.
*ppResultswillbesettoNULLifthecommandhasnoresults.
5.37 get_RadiatedPowerUnit
Returnsthecurrentradiatedpowerunit.
5.38 put_RadiatedPowerUnit
Setsthecurrentradiatedpowerunit.
5.39 get_AntennaGainUnit
Returnsthecurrentantennagainunit.
71
Atoll3.2.1TaskAutomationGuide
Chapter5:DocumentObject
5.40 put_AntennaGainUnit
Setsthecurrentantennagainunit.
5.41 get_HeightOffsetUnit
Returnsthecurrentheightoffsetunit.
5.42 put_HeightOffsetUnit
Setsthecurrentheightoffsetunit.
5.43 get_DatabaseConnectionString
Returnsthedatabaseconnectionstring.
5.44 HasRunningTask
Returnstruewhenthereissomecalculationinprogress.
72
Forsk2014
Atoll3.2.1TaskAutomationGuide
Chapter5:DocumentObject
AT321_TAG_E1
Parameters
[out]pVal:AddressoftheVARIANT_BOOLusedtoreturnwhetherthereissomecalculationinprogressornot.
Remarks
Whensomecalculationisinprogress,itisimpossibletostartnewones.
5.45 RunEx
Startcalculations.
5.46 get_DatabaseSchemaString
Returnsthedatabaseschemastring.
5.47 get_DisplayApplicationDialogues
ReturnstruewhensomemethodsonsomeAtollinterfacesmaydisplaysomedialogueboxes.
73
Atoll3.2.1TaskAutomationGuide
Chapter5:DocumentObject
Forsk2014
5.48 put_DisplayApplicationDialogues
ReturnstruewhensomemethodsonsomeAtollinterfacesmaydisplaysomedialogueboxes.
5.49 PutDatabaseSchemaString
Setsthedatabaseschemastring.
5.50 PutDatabaseConnectionString
Setsthedatabaseconnectionstring.
5.51 ChangeDatabaseConnection
Changesthedatabaseconnectionstring.
74
Atoll3.2.1TaskAutomationGuide
Chapter5:DocumentObject
AT321_TAG_E1
Parameters
[in]aCnn:
TheBSTRusedtospecifythenewdatabaseconnectionstring.
[in]aReserved:
ABSTRreservedforafutureusage.
Remarks
Pleasedonotusethismethod.UsePutDatabaseConnectionStringinstead.
AtollVersion
2.8.1
5.52 get_TemperatureUnit
Returnsthedisplaytemperatureunit.
5.53 put_TemperatureUnit
Setsthedisplaytemperatureunit.
5.54 GetDocumentProperties
Returnsthedocumentproperties.
5.55 SetDocumentProperties
Setsthedocumentproperties.
75
Atoll3.2.1TaskAutomationGuide
Chapter5:DocumentObject
Forsk2014
Parameters
[in]pProperties:TheIPropertyContainerinterfacepointerusedtospecifythedocumentproperties.
Remarks
Availabledocumentpropertiesare:
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
Atoll3.2.1TaskAutomationGuide
Chapter5:DocumentObject
AT321_TAG_E1
USER_PROPERTY_NAME9
String
77
Atoll3.2.1TaskAutomationGuide
Chapter5:DocumentObject
78
Forsk2014
Chapter6
TabularDataObject
Atoll3.2.1TaskAutomationGuide
80
Forsk2014
Atoll3.2.1TaskAutomationGuide
Chapter6:TabularDataObject
AT321_TAG_E1
6 TabularDataObject
TheTabularDataobjectprovidesaccesstoAtolltableswhetheranAtolldocumentisconnectedtoadatabaseornot.Italso
providesaccesstoothertableswhicharenotdatabasetables,suchasPREDICTIONSandZONES,explainedin"Zonesand
PredictionsTabularDataObjects"onpage 97.
AccesstotabulardatainanAtolldocumentconnectedtoadatabase
For each database table, access is provided to differences between the content of the
databasewhenthedatatablehasbeenrefreshedforthelasttimeandthecurrenttable
contentstoredinanAtolldocument.ThesearethedifferenceslistedintheAtollDatabase
Archivedialogue,whichcanbesubmittedthroughanexternalprocessusingthisinterface.
Accessisgiventheoriginaldataasretrievedbythelatestrefreshoperationfromthedata
base.Accessisnotgiventothecurrentcontentofthedatabase.Therefore,itisnotpossi
bletoshoworsolveconflictsbetweenthedataintheAtolldocumentandthecurrent
contentofthedatabase.
Foragivendatabasetable,originaldatavaluesandrowstatusesarenotstoredinthedata
base.TheyarestoredintheAtolldocument.
TheTabularDataobjectprovidesthefollowingpropertiesandmethods:
Name
Description
Attributes
get_ColumnCount
ReturnsthenumberofcolumnsoftheTabularDataObject.
Type:Integer
Access:Read
get_RowCount
ReturnsthenumberofrowsoftheTabularDataObject
Type:Integer
Access:Read
Edit
Putsarowintoeditionmode.
AddNew
AddsanewemptyrowtotheTabularDataObject.Therow
addedisputintoeditionmode.
Update
Commitsarowchangesandputstherowfromeditionmode
tonormalmode.
Delete
Deletesarecord.
GetValue
Returnsavalueofacolumnforagivenrow.
SetValue
Setsthevalueofacolumnfortherowbeingeditedoradded.
GetPrimaryKey
Returnsthevalueoftheprimarykeyforagivenrownumber.
FindPrimaryKey
Searchestherowwhoseprimarykeyequalstheinputvalue
andreturnstherownumberoftherowfound.
Find
Searchesacolumnforavalue.
GetFormattedValue
Returnsacolumnvalueformattedasastring.
CancelUpdate
Cancelsapendingupdate.
get_ColumnNumber
Returnsacolumnnumber.
Type:Integer
Access:Read
get_CanEdit
Checksifrowscanbemodified.
Type:Boolean
Access:Read
get_CanAddNew
Checksifrowscanbeadded.
Type:Boolean
Access:Read
get_CanFilterSort
Checksifrowscanbefilteredorsorted.
Type:Boolean
Access:Read
get_Filter
Returnsthefiltercurrentlysetonthetable.
Type:String
Access:Read/Write
81
Atoll3.2.1TaskAutomationGuide
Chapter6:TabularDataObject
Forsk2014
Name
Description
Attributes
put_Filter
Filtersthetabledataaccordingtoafiltercriteria.
Type:String
Access:Read/Write
get_Sort
Returnsthesortordercurrentlysetonthetable.
Type:String
Access:Read/Write
put_Sort
Sortsthetabledata.
Type:String
Access:Read/Write
GetOriginalValue
Returnsanoriginalfieldvalue.
get_RowStatus
Returnsarowstatus.
Type:Integer
Access:Read
6.1 HowtoAccessaTabularDataObject
ATabularDataobjectisdefinedbyitsstructure(numberofcolumns,nameofcolumns)anditscontent(rows=records).
Column0androw0arespecial:
Row0holdsthefieldnames,i.e.,thetablestructuredescription.
Column0holdsauniqueidentifierforrecords,calledRECORD_ID.Thisidentifierisnotpersistentandmustnotbe
usedbetweentwosessionsofAtoll,neitherwhenrefreshingnorwhenarchiving.
Thus,inordertogetatabulardatastructure,youwrite:
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
Thefirstvalue(fori=0)isalways"RECORD_ID".Thesecond(fori=1)is"SITE_NAME"incaseofTRANSMITTERStable,andso
on.Thelastonecorrespondstoi=ColumnCount.
Toreadthecalculationradiiofallthetransmitters,youwrite:
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
Notethattheloopdoesnotstartwithi=0becauseGetValuewouldreturnthestring"CALC_RADIUS"andnotavalue.
Ifweknowthatcolumn"CALC_RADIUS"isnumber11,wecouldinsteadwrite:
82
Atoll3.2.1TaskAutomationGuide
Chapter6:TabularDataObject
AT321_TAG_E1
Predictionstabulardatagivesaccesstopathlossandsignallevelmatrices.
Zonestabulardatagivesaccesstocalculationandfocuszones.
Formoreinformation,see"ZonesandPredictionsTabularDataObjects"onpage 97.
6.2 get_ColumnCount
ReturnsthenumberofcolumnsoftheTabularDataObject.
6.3 get_RowCount
ReturnsthenumberofrowsoftheTabularDataObject
6.4 Edit
Putsarowintoeditionmode.
83
Atoll3.2.1TaskAutomationGuide
Chapter6:TabularDataObject
Forsk2014
DontforgettocallthismethodbeforeacalltoSetValueandtocallUpdatetocommitthe
changesintherow.
6.5 AddNew
AddsanewemptyrowtotheTabularDataObject.Therowaddedisputintoeditionmode.
HRESULT AddNew();
DontforgettocallthismethodbeforeacalltoSetValueandtocallUpdatetoactuallyadd
thenewrow.
6.6 Update
Commitsarowchangesandputstherowfromeditionmodetonormalmode.
6.7 Delete
Deletesarecord.
6.8 GetValue
Returnsavalueofacolumnforagivenrow.
84
Atoll3.2.1TaskAutomationGuide
Chapter6:TabularDataObject
AT321_TAG_E1
6.9 SetValue
Setsthevalueofacolumnfortherowbeingeditedoradded.
Dim transmitters
Dim doc
85
Atoll3.2.1TaskAutomationGuide
Chapter6:TabularDataObject
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,wecouldhaveused:
For i = 1 To transmitters.RowCount
txLosses = transmitters.GetValue(i, 12)
transmitters.Edit(i)
transmitters.SetValue(12, txLosses + 1)
transmitters.Update
Next
Updatingthemaincontourofthefocuszone:
86
Forsk2014
Atoll3.2.1TaskAutomationGuide
Chapter6:TabularDataObject
AT321_TAG_E1
zones.Edit row
zones.SetValue "POINTS", pts
zones.Update
End Sub
6.10 GetPrimaryKey
Returnsthevalueoftheprimarykeyforagivenrownumber.
6.11 FindPrimaryKey
Searchestherowwhoseprimarykeyequalstheinputvalueandreturnstherownumberoftherowfound.Ifnorowisfound,
returns1.
6.12 Find
Searchesacolumnforavalue.
HRESULT Find(
long iRowStart,
const VARIANT iCol,
87
Atoll3.2.1TaskAutomationGuide
Chapter6:TabularDataObject
Forsk2014
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
Returnsacolumnvalueformattedasastring.
88
Atoll3.2.1TaskAutomationGuide
Chapter6:TabularDataObject
AT321_TAG_E1
Parameters
[in]Row:Therownumber.
AvalidiRownumberisanintegerwhosevalueisgreaterthanzeroorequaltozero,andlowerthanorequaltothe
rowcountoftheTabularDataobject.
[in]iCol:TheVARIANTusedtodefinethecolumn.
WheniColvarianttypeifVT_I4,iColisinterpretedasacolumnnumber.Avalidcolumnnumberisanintegerwhose
valueisgreaterthanzeroorequaltozero,andlowerthanorequaltothecolumncountoftheTabularDataobject.
WheniColvarianttypeifVT_BSTR,iColisinterpretedasacolumnname.Columnnamesarenotcasesensitive.
[out]pVal:AddressofaBSTRstringusedtoreturntheformattedvalue.
Remarks
When0isusedfortheiRowparameter,thetitleofthecolumnspecifiedbyiColisreturned.Thetitleofacolumnislocalized
andmaybeshowntoauser,asopposedtothecolumnname.
6.14 CancelUpdate
Cancelsapendingupdate.ThismethodmaybecalledafterEditorAddNewtocanceltheoperation.
HRESULT CancelUpdate();
6.15 get_ColumnNumber
Returnsacolumnnumber.
6.16 get_CanEdit
Checksifrowscanbemodified.
89
Atoll3.2.1TaskAutomationGuide
Chapter6:TabularDataObject
Forsk2014
Parameters
[out]pVal:AddressoftheVARIANT_BOOLusedtoreturnwhetherrowscanbemodifiedornot.
Remarks
IfVARIANT_FALSEisreturned,thentheEditoperationonthistableisundefined.
6.17 get_CanAddNew
Checksifrowscanbeadded.
6.18 get_CanFilterSort
Checksifrowscanbefilteredorsorted.
6.19 get_Filter
Returnsthefiltercurrentlysetonthetable.
6.20 put_Filter
Filtersthetabledataaccordingtoafiltercriteria.
90
Atoll3.2.1TaskAutomationGuide
Chapter6:TabularDataObject
AT321_TAG_E1
Parameters
[in]vCriteria:TheVARIANTusedtospecifythefiltercriteria.WhenvCriteriaisoftypeVT_I4,itisinterpretedasanAtoRow
Filterenumerationvalue.WhenvCriteriaisoftypeVT_BSTR,itisinterpretedasafilterstring.Filterstringsarewhatcanbe
seenintheAtoll"Table"tabpropertiesforrecordfolders,whenusingadvancedfiltering.PleaserefertotheAtollUserManual
formoreinformationaboutadvancedfilteringondata.
Remarks
PleaserefertotheAtoRowFilterenumerationdefinitionforthelistofconstantsusedtofilteronlymodified,added,ordeleted
rows.
IfthetableisretrievedusingGetRecordswithaAllparametersettoFalse,settingthispropertyisthesameassettingthefilter
interactivelyinanAtollsession.
Toremoveanypreviousfilter,callthismethodeitherwithatoRowFilterNonevalueorwithanemptystring.
When the Atoll document is not connected to a database, atoRowFilterModifiedOrNew and atoRowFilterDeleted are not
available.
6.21 get_Sort
Returnsthesortordercurrentlysetonthetable.
91
Atoll3.2.1TaskAutomationGuide
Chapter6:TabularDataObject
Forsk2014
End Sub
6.22 put_Sort
Sortsthetabledata.
6.23 GetOriginalValue
Returnsanoriginalfieldvalue.
6.24 get_RowStatus
Returnsarowstatus.
92
Atoll3.2.1TaskAutomationGuide
Chapter6:TabularDataObject
AT321_TAG_E1
Remarks
WhenanAtolldocumentisopenfromadatabase,rowstatusesaresettoatoRowStatusUnmodifiedandoriginalvaluesare
setforallrowcolumns.
Whenthedocumentisarchivedorrefreshedfromthedatabase,rowstatusesaresettoatoRowStatusUnmodifiedandall
columnsoriginalvaluesaresetforrowsthathavebeenarchivedorrefreshed.
Whenanewrowiscreated,therowstatusissettoatoRowStatusNewandtheoriginalvalueforallcolumnsaresettothenull
value.
Whenarowismodified,therowstatusissettoatoRowStatusModified.Ifyoureverttherowchanges,therowstatusisset
toatoRowStatusUnmodified.
Whenarowisdeleted,therowstatusissettoatoRowStatusDeleted,therowcolumnvaluesaresettothenullvalue,andthe
originalcolumnvaluesarethecolumnvaluesjustbeforetherowwasdeleted.
6.25 get_Columns
Returnstablecolumnsdefinition.
ColumnName
Type
Description
LEGEND
String
Thedisplaynameofthecolumn
NAME
String
Thedatabasenameofthecolumn
TYPE
Integer
Thedatatypeofthecolumn.Validvaluesare:
0=Text
1=Shortinteger
2=Longinteger
3=Single
4=Double
5=True/False
6=Date/Time
7=Currency;
SIZE
Integer
Thesize,inbytes,foracolumnofTYPE0(Text).
DEFAULT
Variant
Thedefaultvalueofthecolumn.Thetypeofthevariantdependsonthe
typeofthecolumn,asindicatedbyTYPE.
MaybeNull.
FORMATTED_DEFAULT
String
Thedefaultvalueofthecolumn,formattedasastring.
GROUP
String
Thenameofthedatabasefieldgroupthecolumnbelongsto.
ISCUSTOMFIELD
Boolean
Whetherthecolumnisausercolumn(True),ornot(False).
CHOICELIST_TYPE
Integer
WhetheracolumnofTYPE0(Text)contentvaluesarerestrictedtothe
valuesspecifiedinCHOICELIST_VALUES.
CHOICELIST_VALUES
String
NewlineseparatedstringofvalidvaluesforacolumnofTYPEtext.
93
Atoll3.2.1TaskAutomationGuide
Chapter6:TabularDataObject
94
Forsk2014
Chapter7
ZonesandPredictions
TabularDataObjects
Atoll3.2.1TaskAutomationGuide
96
Forsk2014
Atoll3.2.1TaskAutomationGuide
Chapter7:ZonesandPredictionsTabularDataObjects
AT321_TAG_E1
7 ZonesandPredictionsTabularDataObjects
7.1 ZonesTabularDataObject
ColumnName
Type
Description
NAME
String
"ComputationZone"ifthisrowisthecomputationzone.
"FocusZone"ifthisrowispartofthefocuszone.
"FilterZone"ifthisrowispartofthefilteringzone.
"PrintZone"ifthisrowispartoftheprintingzone.
"ExpBitmapZone"ifthisrowispartofthecoverageexportzone.
Atoll>=2.8.1
"HotSpotZone"ifthisrowispartofthehotspotzone.
POINTS
Array
Anarrayofpointsasdoublevalues.
CONTOUR_NUM
Integer
Thecontourindex.
POLYGON_NUM
Integer
Thepolygonindex.
POLYGON_NAME
String
Atoll>=2.8.1
Thenameofthepolygon.
Forhotspotzones,itisthenameofaspecifichotspotzone.
Forotherzones,itisthenamethezonesubfolder,intheexplorerwindow.
Thiscolumnisreadonly.
AtollVersion
2.8.1
Itisnowpossibletoaccesshotspotzones.
Their content is identified by the "NAME" column ("HotSpotZone"), then a specific hot spot zone is specified by the
"POLYGON_NAME"column,whichisusedtoindicateaspecifichotspotzoneinthehotspotzonesfolder.
However,unlikeotherzones,hotspotzonesaccessisreadonly.Itisnotpossibletoeditahotspotzone,todeleteahotspot
zone,ortocreateanewhotspotzone.
Example
Readingthefirstcontourofthefocuszone:
97
Atoll3.2.1TaskAutomationGuide
Chapter7:ZonesandPredictionsTabularDataObjects
Forsk2014
Else
MsgBox "Not an array"
End If
End Sub
7.2 PredictionsTabularDataObject
The"PREDICTIONS"TabularDataobjectisreadonlyexceptfortheLOCKEDfield,whichcanbeusedtolockorunlockpahloss
matricesofatransmitter.
AtollVersion
2.8.0
ThefieldPATH_NAMEisreadwrite.ItsvaluecanbesettoNull,inwhichcasepathlossmatricesforTX_IDaredeleted.
ColumnName
Type
Description
TX_ID
String
Transmittername.
LOCKED
Boolean
Trueifthepathlossmatricesarelocked,otherwiseFalse.
VALID
Boolean
Trueifthemainandextendedpathlossmatricesarevalid,otherwiseFalse.
INVALID_CAUSE
String
Causeofinvalidity,whenVALIDreturnsFalse.
NullvaluewhenVALIDreturnsTrue.
SIZE
Integer
Sizeofthemainmatrixplusthesizeoftheextendedmatrix,inbytes.
PATHNAME
String
Nullvaluewhenthereisnostorageforthemainmatrix.
"(Embeddedindocument)"ifthestorageisnotexternal.
Otherwisecontainsthemainpathlossmatrixfilepath.
PATHLOSS
Object
TheobjectimplementstheIGridDatainterface.Thisgriddatacontainsthe
mainpathlossmatrixdatafortransmitterTX_ID.
Nullvaluewhenthereisnoavailableresultforthemainmatrix.
SIGNAL
Object
TheobjectimplementstheIGridDatainterface.Thisgriddatacontainsthe
mainsignallevelmatrixdatafortransmitterTX_ID.
Nullvaluewhenthereisnoavailableresultforthemainmatrix.
LOWRES_PATHLOSS
Object
TheobjectimplementstheIGridDatainterface.Thisgriddatacontainsthe
extendedpathlossmatrixdatafortransmitterTX_ID.
Nullvaluewhenthereisnoavailableresultfortheextendedmatrix.
LOWRES_SIGNAL
Object
TheobjectimplementstheIGridDatainterface.Thisgriddatacontainsthe
extendedsignallevelmatrixdatafortransmitterTX_ID.
Nullvaluewhenthereisnoavailableresultfortheextendedmatrix.
String
Atollversion 2.7.0
Nullvaluewhenthereisnostoragefortheextendedmatrix.
"(Embeddedindocument)"ifthestorageisnotexternal.
Otherwisecontainstheextendedpathlossmatrixfilepath.
LOWRES_PATHNAME
AtollVersion
2.8.1
Newcolumnsareavailable
ThesevaluesareavailableevenwhenVALIDreturnsFALSEbuttheyarenotuptodatewhentheresolutionofpathlossmatri
ces,thecalculationarea,orthetransmitterlocationhaschanged.
98
Atoll3.2.1TaskAutomationGuide
Chapter7:ZonesandPredictionsTabularDataObjects
AT321_TAG_E1
ColumnName
Type
Description
GRID_X
Double
Xcoordinateofthetopleftcornerofthemainpathlossmatrixupperleft
pixel.
Nullvaluewhenthereisnoavailableresultforthemainmatrix.
GRID_Y
Double
Ycoordinateofthetopleftcornerofthemainpathlossmatrixupperleft
pixel.
Nullvaluewhenthereisnoavailableresultforthemainmatrix.
GRID_NX
Integer
Numberofcolumnsinthemainpathlossmatrix.
Nullvaluewhenthereisnoavailableresultforthemainmatrix.
GRID_NY
Integer
Numberofrowsinthemainpathlossmatrix.
Nullvaluewhenthereisnoavailableresultforthemainmatrix.
GRID_RESX
Double
Resolutionofthemainpathlossmatrix,inmetre.
Nullvaluewhenthereisnoavailableresultforthemainmatrix.
GRID_RESY
Double
Resolutionofthemainpathlossmatrix,inmetre.
Nullvaluewhenthereisnoavailableresultforthemainmatrix.
LOWRES_GRID_X
Double
Xcoordinateofthetopleftcorneroftheextendedpathlossmatrixupper
leftpixel.
Nullvaluewhenthereisnoavailableresultfortheextendedmatrix.
LOWRES_GRID_Y
Double
Ycoordinateofthetopleftcorneroftheextendedpathlossmatrixupper
leftpixel.
Nullvaluewhenthereisnoavailableresultfortheextendedmatrix.
LOWRES_GRID_NX
Integer
Numberofcolumnsintheextendedpathlossmatrix.
Nullvaluewhenthereisnoavailableresultfortheextendedmatrix.
LOWRES_GRID_NY
Integer
Numberofrowsintheextendedpathlossmatrix.
Nullvaluewhenthereisnoavailableresultfortheextendedmatrix.
LOWRES_GRID_RESX
Double
Resolutionoftheextendedpathlossmatrix,inmetre.
Nullvaluewhenthereisnoavailableresultfortheextendedmatrix.
LOWRES_GRID_RESY
Double
Resolutionoftheextendedpathlossmatrix,inmetre.
Nullvaluewhenthereisnoavailableresultfortheextendedmatrix.
ColumnName
Type
Description
TX_PATHLOSS
Object
TheobjectimplementstheIGridDatainterface.
TX_SIGNAL
Object
TheobjectimplementstheIGridDatainterface.
TX_LOWRES_PATHLOSS
Object
TheobjectimplementstheIGridDatainterface.
TX_LOWRES_SIGNAL
Object
TheobjectimplementstheIGridDatainterface.
AtollVersion
3.1.0
Newcolumnsareavailable:
TX_PATHLOSS,TX_SIGNAL,TX_LOWRES_PATHLOSS,TX_LOWRES_SIGNALforthetransmitterTX_IDdonottakeintoaccount
itsrepeatersorremoteantennas.
Onthecontrary,usingPATHLOSS,SIGNAL,LOWRES_PATHLOSS,LOWRES_SIGNAL,contributionsfromrepeatersorremote
antennasarecombinedintoonematrix.
PleaseuseTX_PATHLOSS,TX_SIGNAL,TX_LOWRES_PATHLOSS,TX_LOWRES_SIGNALcolumnswhenyouneedtoconsider
transmittersignalorpathlossindependentlyfromitsrepeatersorremoteantennas.
AtollVersion
3.2.0
Itisnowpossibletoupdatepathlossmatriceswithexternalresults(.LOSfiles).
99
Atoll3.2.1TaskAutomationGuide
Chapter7:ZonesandPredictionsTabularDataObjects
Forsk2014
YoucaneditthePATH_NAMEorLOWRES_PATHNAMEcolumns,specifyingvalid.LOSabsolutefullpath.
Inthiscase,whentherowinthepredictionstableisupdated,pathlossmatricesareupdatedwiththecontentoffilesprevi
ouslyspecified.
Pleasenotethatfothistowork,youhavetogeoreferenceyourprovided.LOSfiles,withastandardBILheaderfile(.hdr).
Pleasenotethatevenifyour.LOSfilesneedtobegeoreferencedjustliketheywere.BILfiles,.LOSfilesarewrittenbottom
up,nottopdown.
TX_PATHLOSS
TX_SIGNAL
TX_LOWRES_PATHLOSS
TX_LOWRES_SIGNAL
100
Object
TheobjectimplementstheIGridDatainterface.Thisgriddatacontainsthe
mainpathlossmatrixdatafortransmitterTX_ID.
Nullvaluewhenthereisnoavailableresultforthemainmatrix.
Valuesreturneddonotincludecontributionsfromrepeatersorremote
antennasofthetransmitterTX_ID.
Object
TheobjectimplementstheIGridDatainterface.Thisgriddatacontainsthe
mainsignallevelmatrixdatafortransmitterTX_ID.
Nullvaluewhenthereisnoavailableresultforthemainmatrix.
Valuesreturneddonotincludecontributionsfromrepeatersorremote
antennasofthetransmitterTX_ID.
Object
TheobjectimplementstheIGridDatainterface.Thisgriddatacontainsthe
extendedpathlossmatrixdatafortransmitterTX_ID.
Nullvaluewhenthereisnoavailableresultfortheextendedmatrix.
Valuesreturneddonotincludecontributionsfromrepeatersorremote
antennasofthetransmitterTX_ID.
Object
TheobjectimplementstheIGridDatainterface.Thisgriddatacontainsthe
extendedsignallevelmatrixdatafortransmitterTX_ID.
Nullvaluewhenthereisnoavailableresultfortheextendedmatrix.
Valuesreturneddonotincludecontributionsfromrepeatersorremote
antennasofthetransmitterTX_ID.
Chapter8
CoordSystemObject
Atoll3.2.1TaskAutomationGuide
102
Forsk2014
Atoll3.2.1TaskAutomationGuide
Chapter8:CoordSystemObject
AT321_TAG_E1
8 CoordSystemObject
Thisobjectcontainstheentiredefinitionofacoordinatesystem.SeveralcoordinatesystemsareusedinAtolldocuments;one
fordisplay,oneforprojectedgeographicfiles,andoneforsitecoordinates.Thelastonecanberelatedtothesystemusedfor
display.
ThisobjectisnotdefinedinAtolllibrarybutintheFSKGISLiblibrary.Itcanconvertpointsfromonecoordinatesystemto
another.
TheCoordSystemobjectprovidesthefollowingpropertiesandmethods:
Name
Description
Code
Returnsorsetsthenumericcodeofthecoordinatessystem.
ConvertCoordsTo
Convertsthecoordinatesofapointexpressedinthecurrent
systemtoanotherone.
Datum
Returnsorsetsthenumericvalueofthedatum.
DatumName
Nameofthedatum.
Description
Descriptionofthedatum.
Ellipsoid
Returnsorsetsthenumericvalueoftheellipsoid.
EllipsoidName
Nameoftheellipsoid.
Name
Returnsorsetsthenameofthecoordinatessystem.
Pick
Opensthecoordinatessystemdialogue.
ProjMethod
Projectionmethodusedforthecurrentcoordinatessystem.
ProjParameter
Readsaparameteroftheprojection.
SetDatum
Changesthedatumofthesystem.
SetProjection
Setstheprojectionparametersofthecoordinatesystem.
Unit
Returnsorsetstheunitofthecoordinatesystem.
Attributes
Fordetailsoncoordinatesystems,seetheTechnicalReferenceGuide.
8.1 HowtoAccessaCoordSystemObject
Togetthecoordinatesystemusedforsites:
Dim doc
Dim coordSys
Set doc = Atoll.ActiveDocument
Set coordSys = doc.CoordSystemInternal
8.2 Code
Returnsorsetsthenumericcodeofthecoordinatessystem.
103
Atoll3.2.1TaskAutomationGuide
Chapter8:CoordSystemObject
Forsk2014
Parameters
pVal:AddressoftheLongreadasthecodeofthesystem.
val:Longvaluerepresentingthecodeofthesystemtoset.
Classical system codes have values less than 32767. System codes greater or equal to
32768correspondtouserdefinedsystems.
8.3 ConvertCoordsTo
Convertsthecoordinatesofapointexpressedinthecurrentsystemtoanotherone.
HRESULT ConvertCoordsTo(
IDispCoordSystem *targetCS,
VARIANT inPoint,
VARIANT *outPoint
);
Parameters
[in]targetCS:AnIDispCoordSysteminterfacepointerusedtospecifythecoordinatesystemtowhichinputcoordinatesmust
beconverted.
[in]inPoint:AVARIANTusedusedtospecifythecoordinatesofaninputpoint.Thecoordinatesareexpressedinthecurrent
coordinatesystem.TheVARIANTmustaonedimensionarrayof2floatingpointvalues(VT_ARRAY|VT_R8).Elementatindex
0isusedtospecifythexcoordinate,elementatindex1isusedtospecifytheycoordinate.
[out]outPoint:ApointertoaVARIANTusedtoreturnthecoordinateoftheinPointinputpointexpressedinthetargetCScoor
dinatesystem.ThetypeoftheVARIANTreturnedisVT_ARRAT|VT_R8:aonedimensionarrayof2floatingpointvalues.
Elementatindex0isusedtospecifythexcoordinate,elementatindex1isusedtospecifytheycoordinate.
Example
Public Sub ConvertSitesCoordinates
Dim sites
Dim x
Dim y
Dim oFrom
Set oFrom = ActiveDocument.CoordSystemInternal
Dim oTo
Set oTo = ActiveDocument.CoordSystemDisplay
Dim coords
Set sites = ActiveDocument.GetRecords("Sites", True)
Dim i
For i = 1 To sites.RowCount
x = sites.GetValue(i, "LONGITUDE")
y = sites.GetValue(i, "LATITUDE")
coords = oFrom.ConvertCoordsTo(oTo, Array(x, y))
104
Atoll3.2.1TaskAutomationGuide
Chapter8:CoordSystemObject
AT321_TAG_E1
LogMessage sites.GetValue(i,"NAME")&":"&CStr(coords(0))&";"&CStr(coords(1))
Next
End Sub
8.4 Datum
Returnsorsetsthenumericvalueofthedatum.
8.5 DatumName
Nameofthedatum.
8.6 Description
Descriptionofthedatum.
8.7 Ellipsoid
Returnsorsetsthenumericvalueoftheellipsoid.
8.8 EllipsoidName
Nameoftheellipsoid.
105
Atoll3.2.1TaskAutomationGuide
Chapter8:CoordSystemObject
Forsk2014
8.9 Name
Returnsorsetsthenameofthecoordinatessystem.
8.10 Pick
Opensthecoordinatessystemdialogue.
= 2,
fgProjected2D
= 4
} CoordSysType;
8.11 ProjMethod
Projectionmethodusedforthecurrentcoordinatessystem.
106
Atoll3.2.1TaskAutomationGuide
Chapter8:CoordSystemObject
AT321_TAG_E1
8.12 ProjParameter
Readsaparameteroftheprojection.
8.13 SetDatum
Changesthedatumofthesystem.
8.14 SetProjection
Setstheprojectionparametersofthecoordinatesystem.
8.15 Unit
Returnsorsetstheunitofthecoordinatesystem.
107
Atoll3.2.1TaskAutomationGuide
Chapter8:CoordSystemObject
108
Forsk2014
Chapter9
ChildFolderObject
Atoll3.2.1TaskAutomationGuide
110
Forsk2014
Atoll3.2.1TaskAutomationGuide
Chapter9:ChildFolderObject
AT321_TAG_E1
9 ChildFolderObject
AChildFolderobjectrepresentsanitemintheapplicationexplorerwindow.Itcanbeacollectionofsubitems.
TheChildFolderobjectprovidesthefollowingpropertiesandmethods:
Name
Description
Attributes
get_Application
ReturnstheApplicationobject.
Type:Applicationobject
Access:Read
get_Parent
ReturnstheparentChildFolderobject.
Type:ChildFolderobject
Access:Read
get_Name
ReturnstheChildFolderobjectdisplayname.
Type:String
Access:Read/Write
put_Name
SetstheChildFolderobjectdisplayname.
Type:String
Access:Read/Write
get_Count
ReturnsthenumberofchildrenoftheChildFolderobject.
Type:Integer
Access:Read
get_Item
ReturnsoneofthechildrenoftheChildFolderobject.
Type:ChildFolderchildren
collection
Access:Read
get__NewEnum
Returnsanobjectusedtoenumeratethechildrenofthe
ChildFolderobject.
get_Visible
ReturnsthevisibilitystateoftheChildFolderobject.
Type:Boolean
Access:Read/Write
put_Visible
SetsthevisibilitystateoftheChildFolderobject.
Type:Boolean
Access:Read/Write
get_Selected
ReturnstheselectedstateoftheChildFolderobject.
Type:Boolean
Access:Read/Write
put_Selected
SetstheselectedstateoftheChildFolderobject.
Type:Boolean
Access:Read/Write
Export
ExportsaChildFolderobjecttoafile,inagivenformat.
CentreOnMap
Centrestheapplicationmapwindowaroundthe
ChildFolderobject.
Redraw
RedrawstheChildFolderobject.
AddChild
AddsanewchildtothecurrentChildFolderobject.
Remove
RemovestheChildFolderobjectfromitsparentChildFolder
object.
get_position
ReturnstheChildFolderobjectpositionrelativetoits
parentChildFolderobject.
Type:Integer
Access:Read/Write
put_position
SetstheChildFolderobjectpositionrelativetoitsparent
ChildFolderobject.
Type:Integer
Access:Read/Write
get_Object
AccesstosomespecificfeaturesontheChildFolderobject.
get_dispatch
AccesstosomespecificfeaturesontheChildFolderobject.
get_ObjectKind
ReturnsatypeidentifieroftheChildFolderobject.
GetProperty
ReturnsaChildFolderobjectproperty.
SetProperty
SetsaChildFolderobjectproperty.
Type:String
Access:Read
111
Atoll3.2.1TaskAutomationGuide
Chapter9:ChildFolderObject
Forsk2014
Name
Description
GetPropertiesInfo
Returnsnamesandtypesforallpropertiesavailableonthe
ChildFolderobject.
PropertyIsPropertyContainer
ReturnstruewhenaChildFolderobjectpropertyisa
PropertyContainerobject.
PropertyIsTabularData
ReturnstruewhenaChildFolderobjectpropertya
TabularDataobject.
LoadProperties
Setspropertiesfromapropertycontainertothe
ChildFolderobject.
SaveProperties
SavesalltheChildFolderobjectpropertiestoanother
propertycontainer.
RemoveItem
RemovesoneofthechildrenoftheChildFolderobject.
SetCustomIcon
Setsthepathofanicontouseforacustomchildfolder.
Attributes
9.1 HowtoAccessaChildFolderObject
AChildFolderisfirstobtainedthrougharootentrypointfromthedocumentandisrelatedtoataboftheAtollExplorer
window.
MostChildFolderobjectsmayhavechildren,canbeselected,setvisible,andrenamed.Onlycoveragepredictionsmaybe
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
ReturnstheAtollApplicationobject.
112
Atoll3.2.1TaskAutomationGuide
Chapter9:ChildFolderObject
AT321_TAG_E1
Parameters
[out]ppVal:AddressoftheIApplicationinterfacepointerusedtoreturntheAtollApplicationobject.
9.3 get_Parent
ReturnstheparentAtollChildFolderobject.
9.4 get_Name
ReturnstheChildFolderobjectdisplayname.
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
SetstheChildFolderobjectdisplayname.
113
Atoll3.2.1TaskAutomationGuide
Chapter9:ChildFolderObject
Forsk2014
Parameters
[in]aNewVal:TheBSTRusedtospecifythedisplayname.
Example
See"get_Name"onpage 113.
9.6 get_Count
ReturnsthenumberofchildrenoftheChildFolderobject.
9.7 get_Item
ReturnsoneofthechildrenoftheChildFolderobject.
9.8 get__NewEnum
ReturnsanobjectusedtoenumeratethechildrenoftheChildFolderobject.
9.9 get_Visible
ReturnsthevisibilitystateoftheChildFolderobject.
114
Atoll3.2.1TaskAutomationGuide
Chapter9:ChildFolderObject
AT321_TAG_E1
9.10 put_Visible
SetsthevisibilitystateoftheChildFolderobject.
9.11 get_Selected
ReturnstheselectedstateoftheChildFolderobject.
115
Atoll3.2.1TaskAutomationGuide
Chapter9:ChildFolderObject
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
SetstheselectedstateoftheChildFolderobject.
9.13 Export
ExportsaChildFolderobjecttoafile,inagivenformat.Thismethodcanonlybeusedforstudies.
HRESULT Export(
const BSTR bstrFileName,
IDispCoordSystem* proj,
const BSTR bstrFormat
);
Parameters
[in]bstrFileName:Astringcontaininganabsolutefilepath.
[in]proj:AnIDispCoordSysteminterfacepointerusedtodefinethecoordinatesystemfortheexport.
[in]bstrFormat:AstringusedtodefinetheformatofthefilespecifiedbybstrFileName.
116
Forsk2014
Atoll3.2.1TaskAutomationGuide
Chapter9:ChildFolderObject
AT321_TAG_E1
ThesyntaxforthebstrFormatparameteris:
PropertyName=Value;[PropertyName=Value;]format
format:
Availablevaluesare:
SHP
AGD
MIF
TAB
BMP
TIF
TXT
ARCVIEWGRIDASCII
PNG
JP2
Pleasereadtheapplicationdocumentationtolearnmoreaboutthesefileformats.
ThedataexportedisthegeographiccoveragepredictionofastudywhenusingSHP,AGD,MIF,TAB,BMP,ARCVIEW
GRIDASCII,PNG,JP2,orTIFformats.However,ifyouspecifyTXTformat,thismethodwillexportthestudyreportin
tabulatedASCIItextformat.Thispredictionstudyreportisthesameastheoneavailablebyrightclickingthestudyin
theapplicationandselectingGenerateReport.
Availablepropertiesare:
PropertyName
Resolution
AreaType
Value
integer
0|1|2
Version
Description
2.8.1
Thisistheexportresolution,expressedinmeter.
Ifnotspecified,theresolutionusedtoperformtheexportis
thestudyresolution.
Itisonlyrelevantwhentheexportformatisavectorformat,
asopposedtoarasterformat.
2.8.1
Usedtospecifythezonetoexport.Availablevaluesare:
0:TheEntireCoveredArea
1:TheComputationZone
2:TheGeographicExportZone
Ifnotspecified,theentirecoveredareaisconsideredto
performtheexport.
Itisonlyrelevantforrasterformats,asopposedtovector
formats.
ReturnValue
S_OK:Exporthascompletedsuccessfully.
S_FALSE:Exportcouldntbeperformedbecauseofoneofthefollowingreasons:
ThefolderspecifiedinbstrFileNamedoesnotexist.
Thestudyvisibilitycheckboxiscleared.
Thestudyhasnocoverage.
WhenS_FALSEisreturned,nooutputfileiscreated.
Example
Const SID_PREDICTIONS = "{DA676EF0-E300-4AFF-BBFA-EC55D3798E4F}"
Public Sub ExportStudy
Dim oStudy
Dim oCS
Set oCS = ActiveDocument.CoordSystemDisplay
117
Atoll3.2.1TaskAutomationGuide
Chapter9:ChildFolderObject
Forsk2014
9.14 CentreOnMap
CentrestheAtollMapViewwindowaroundtheChildFolderobject.
HRESULT CentreOnMap(void);
Remarks
CentreOnMaponlymakessenseforChildFolderobjectsthatmayappearonAtollMapViewwindows.CentreOnMapcallswill
beignoredforobjectsthatdontsupportit.Noerrorwillbereturned.
9.15 Redraw
RedrawstheChildFolderobject.
HRESULT Redraw(void);
Remarks
RedrawonlymakessenseforChildFolderobjectsthatmayappearonAtollMapViewwindows.Redrawcallswillbeignored
forobjectsthatdontsupportit.Noerrorwillbereturned.
9.16 AddChild
AddsanewchildtothecurrentAtollchildfolderobject.
118
Atoll3.2.1TaskAutomationGuide
Chapter9:ChildFolderObject
AT321_TAG_E1
9.17 Remove
RemovestheChildFolderobjectfromitsparentChildFolderobject.
HRESULT Remove(void);
Remarks
AChildFolderobjectcannotbeusedanymoreafteritisremoved.ChildFolderobjectsmayberemovedbyAtoll,forinstance
whenF5isusedinteractivelytorefreshthescreen.
Atollversion>=2.8.2:
Thismethodisdeprecated.PleaseuseRemoveIteminstead.
9.18 get_position
ReturnstheChildFolderobjectpositionrelativetoitsparentChildFolderobject.
9.19 put_position
SetstheChildFolderobjectpositionrelativetoitsparentChildFolderobject.
IflPos 0,theChildFolderobjectismovedtothetop.
IflPos get_Count()1,theChildFolderobjectismovedtothebottom.
9.20 get_Object
AccesstosomespecificfeaturesontheChildFolderobject.
9.21 get_dispatch
AccesstosomespecificfeaturesontheChildFolderobject.
119
Atoll3.2.1TaskAutomationGuide
Chapter9:ChildFolderObject
Forsk2014
9.22 get_ObjectKind
ReturnsatypeidentifieroftheChildFolderobject.
120
Version
SID
StringValue
SpecificFeatures
2.4.0
SID_CLUTTER
{7CB51DE8A96111D286880060086457D1}
Tabulardataclutter
properties.
2.4.0
SID_SIMULATIONS
{CDDF1E1D19634D80A057D23A19570984}
Simulationsfolder.
2.4.0
SID_SIMULATIONSGROUP
{AF5E2B981D5448FA89C58BFA2936ABF2}
"Groupsofsimulations"
folder.
2.4.0
SID_SIMULATION
{095C5D9096F14BA885BBB2F990AC2DD9}
"Simulation"items.
2.5.1
SID_SITES
{90443F685B3B4AFDB7BBB057095EBAAD}
Sitesfolder.
2.5.1
SID_ANTENNAS
{5FBEB2AE3BBB4FBA94D85D8EA5A32069}
Antennasfolder.
2.5.1
SID_TRANSMITTERS
{F7E891E8F7F54870BF63AF559AD50FD3}
Transmittersfolder,ina
singleRATdocument.
2.5.1
SID_PREDICTIONS
{DA676EF0E3004AFFBBFAEC55D3798E4F}
Predictionsfolder.
2.5.1
SID_UMTS_PARAMETERS
{D4F57EE3778543489BA628998AA6BD80}
UMTSParametersfolder.
2.5.1
SID_CW_MEASUREMENTS
{41413C4AC9DE43DDA917612A0AF198FC}
CWMeasurementsfolder.
2.5.1
SID_MEASURE_TX
{2C102EE5BFF44A5A813002BD0E2F70D7}
CWMeasurements
transmitter.
2.5.1
SID_MEASURE_ITEM
{36858A487A85482E9DA0B9E935ADE84C}
CWMeasurements.
2.5.1
SID_TESTMOBILEDATA
{21C11380D8CF4902B622763522AD9FC4}
DriveTestDatafolder.
2.5.1
SID_NUM_MEASURE_ITEM
{916801F90539448C8C0C491FAC6399ED}
DriveTestDataitems.
2.5.1
SID_PARAMETERS_FOLDER
{43B88455226454F908F59A500DB4FD1}
Parametersfolder.
Atoll3.2.1TaskAutomationGuide
Chapter9:ChildFolderObject
AT321_TAG_E1
2.5.1
SID_HEXAGON_SCHEMA
{B167D45EA0BC4DC6B9D76F7B131CADF1}
HexagonalDesignfolder.
2.6.0
SID_TRAFFICFOLDER
{B3B25A07A9944e8dBBD151556D6C4245}
Trafficfolder.
2.7.0
SID_PROPAGATIONMODELS
{4A2D160B7D114D0792DFA3CF6B68D402}
Propagationmodelsfolder.
2.8.2
{16A53FB3A9614EEA8C302387DBF1CC24}
MasterlinkChildFolder
object.
2.8.2
{232BDB73A68F41A6A95475112D907BBF}
LinkChildFolderobject.
3.1.0
{CC6370627AFF4516BEFBBCC954E905B1}
GSMTransmittersfolder,ina
multiRATdocument.
3.1.0
{FD147AA0B9A247AC8CD551C77A708AF8}
LTETransmittersfolder,ina
multiRATdocument.
3.1.0
{090A23A1EE08420D9739651D1045EF16}
UMTSTransmittersfolder,in
amultiRATdocument.
3.2.0
{65FF5F7DDBF04B52ABB866F3414FD4C3}
CDMA2000Transmitters
folder,inamultiRAT
document.
3.2.1
StudyFolder
Asubfolderofthe
predictionsfolder.
9.23 GetProperty
ReturnsaChildFolderobjectproperty.
VBScript
VT_BOOL
Boolean
VT_I4
Integer
VT_R4
Single
VT_R8
Double
VT_UNKNOWN
Object
VT_DISPATCH
Object,TabularDataobject,ChildFolderobject,PropertyContainer
object
VT_BSTR
String
VT_ARRAY|(anyoftheprevioustypes)
Array,witharrayitemsoftheprevioustypes
TheerrorE_INVALIDARGisreturnedwhenthereisnopropertynamedbstrNamefortheChildFolderobject.Theproperties
availablefortheChildFolderobjectdependonthetypeoftheChildFolderobject,asreturnedbyget_ObjectKind.
121
Atoll3.2.1TaskAutomationGuide
Chapter9:ChildFolderObject
Forsk2014
9.24 SetProperty
SetsaChildFolderobjectproperty.
9.25 GetPropertiesInfo
ReturnsnamesandtypesforallpropertiesavailableontheChildFolderobject.
9.26 PropertyIsPropertyContainer
ReturnstruewhenaChildFolderobjectpropertyisaPropertyContainerobject.
HRESULT
PropertyIsPropertyContainer(const BSTR bstrName, VARIANT_BOOL *pValue);
Parameters
[in]bstrName:Thepropertyname.
[out]pValue:AddressoftheVARIANT_BOOLusedtoreturnwhetherthepropertyisaPropertyContainerobjectornot.
9.27 PropertyIsTabularData
ReturnstruewhenaChildFolderobjectpropertyisaTabularDataobject.
9.28 LoadProperties
SetspropertiesfromapropertycontainertotheChildFolderobject.
122
Atoll3.2.1TaskAutomationGuide
Chapter9:ChildFolderObject
AT321_TAG_E1
Parameters
[in]varSource:VARIANToftypeVT_DISPATCH,usedtospecifyapropertycontainerforthepropertiestoset.
9.29 SaveProperties
SavesalltheChildFolderobjectpropertiestoanotherpropertycontainer.
HRESULT SaveProperties( const VARIANT varDestination) ;
Parameters
[in]varDestination:VARIANToftypeVT_DISPATCH,usedtospecifyapropertycontainerwhereallpropertieswillbeset.
9.30 RemoveItem
RemovesoneofthechildrenoftheChildFolderobject.
HRESULT RemoveItem( const VARIANT idx) ;
Parameters
[in]idx:AVARIANToftypeVT_I4orVT_BSTRusedtospecifyoneofthechildrentoremove.
IfthetypeofthevariantisVT_I4,itisinterpretedasazerobasedindexinthelistofchildren.
IfthetypeofthevariantisVT_BSTR,itisfirstinterpretedasthedisplaynameofthechildtoremove,andifthedisplayname
isnotfound,itistheninterpretedasaChildFolderobjectkind,asreturnedbyget_ObjectKind.
Remarks
AChildFolderobjectcannotbeusedanymoreafteritisremoved.ChildFolderobjectsmayberemovedbytheapplication,for
instancewhenF5isusedinteractivelytorefreshthescreen.
ThismethodfailsforChildFolderobjectsthatcannotberemovedinteractively,andanerrorisreturnedinthatcase.
9.31 SetCustomIcon
Setsthepathofanicontouseforacustomchildfolder.
HRESULT SetCustomIcon(const BSTR bstrPath);
Parameters
[in]bstrPath:Thefullpathtotheiconfile(*.ico)toload.
123
Atoll3.2.1TaskAutomationGuide
Chapter9:ChildFolderObject
124
Forsk2014
Chapter10
PropertyContainer
Object
Atoll3.2.1TaskAutomationGuide
126
Forsk2014
Atoll3.2.1TaskAutomationGuide
Chapter10:PropertyContainerObject
AT321_TAG_E1
10 PropertyContainerObject
ThePropertyContainerobjectisagenericcontainercontainingasetofnamedpropertiesofarbitrarytypes.
ThePropertyContainerobjectprovidesthefollowingpropertiesandmethods:
Name
Description
Attributes
Get
Returnsanamedproperty.
Set
Setsanamedproperty.
GetInfo
Returnsnamesandtypesforallpropertiessettotheproperty
container.
IsPropertyContainer
Returnstruewhenanamedpropertyisofa
PropertyContainerobject.
Type:Boolean
Access:Read
IsTabularData
ReturnstruewhenanamedpropertyisofaTabularData
object.
Type:Boolean
Access:Read
Load
Addspropertiesfromanotherpropertycontainertothe
propertycontainer.
Save
Savesallthepropertiestoanotherpropertycontainer.
RemoveAll
Removesallpropertiesfromthepropertycontainer.
Remove
Removesanamedpropertyfromthepropertycontainer.
10.1 Get
Returnsanamedproperty.
VBScript
VT_BOOL
Boolean
VT_I4
Integer
VT_R4
Single
VT_R8
Double
VT_UNKNOWN
Object
VT_DISPATCH
Object,TabularDataObject,ChildFolderObject,PropertyContainer
Object
VT_BSTR
String
VT_ARRAY|(anyoftheprevioustypes)
Array,witharrayitemsoftheprevioustypes
127
Atoll3.2.1TaskAutomationGuide
Chapter10:PropertyContainerObject
Forsk2014
The error E_INVALIDARG is returned when the property named bstrName has not been previously set to the property
container.
10.2 Set
Setsanamedproperty.
10.3 GetInfo
Returnsnamesandtypesforallpropertiessettothepropertycontainer.
10.4 IsPropertyContainer
ReturnstruewhenanamedpropertyisaPropertyContainerobject.
10.5 IsTabularData
ReturnstruewhenanamedpropertyisaTabularDataobject.
10.6 Load
Addspropertiesfromanotherpropertycontainertothepropertycontainer.
128
Atoll3.2.1TaskAutomationGuide
Chapter10:PropertyContainerObject
AT321_TAG_E1
10.7 Save
Savesallthepropertiestoanotherpropertycontainer.
10.8 RemoveAll
Removesallpropertiesfromthepropertycontainer.
HRESULT RemoveAll(void);
10.9 Remove
Removesanamedpropertyfromthepropertycontainer.
129
Atoll3.2.1TaskAutomationGuide
Chapter10:PropertyContainerObject
130
Forsk2014
Chapter11
ChildFolderObject
Properties
Atoll3.2.1TaskAutomationGuide
132
Forsk2014
Atoll3.2.1TaskAutomationGuide
Chapter11:ChildFolderObjectProperties
AT321_TAG_E1
11 ChildFolderObjectProperties
ChildFolderobjectpropertiesarenamedproperties.ThesetofavailablepropertiesforagivenChildFolderobjectdependson
theChildFolderobjecttype,returnedbyget_ObjectKind.
ChildFolderobjectpropertynamesusuallyresembletheirGUIrepresentationsinthepropertiesdialoguesinsideAtoll.
ChildFolderobjectpropertiesaredividedintothefollowinggroupsaccordingtotheiruseandapplicationinAtoll:
"CommonChildFolderObjectProperties"onpage 134,
"PredictionsFolderProperties"onpage 134,
"CoveragePredictionProperties"onpage 135,
"GSMSimulationGroupProperties"onpage 142,
"UMTSSimulationGroupProperties"onpage 143,
"WiMAXandLTESimulationGroupProperties"onpage 144,
"3GPPMultiRATSimulationGroupProperties"onpage 145,
"PropagationModelProperties"onpage 146,
"CWMeasurementProperties"onpage 148,
"DriveTestDataProperties"onpage 149,
"CustomChildFolderObjectProperties"onpage 149,
"MasterLinkProperties"onpage 150,
"LinkProperties"onpage 150,
"VectorLayerProperties"onpage 150.
11.1 HowtoAccessChildFolderObjectProperties
ThefollowingsamplecodesshowhowtoreadandwriteChildFolderObjectproperties.
ReadingaChildFolderObjectProperty
item:AChildFolderobject.
propertyname:Thepropertyname.
propertyvalue:Thepropertyvalue.
133
Atoll3.2.1TaskAutomationGuide
Chapter11:ChildFolderObjectProperties
Forsk2014
11.2 CommonChildFolderObjectProperties
SomeChildFolderobjectpropertiesarecommontoallkindsofChildFolderobjects.Thesepropertiesincludethefollowing.
Name
Description
Attributes
NAME
ChildFolderobjectnameasitappearsintheExplorerwindow.
Version :2.6.1
Type:String
Access:Read/Write
VISIBLE
ChildFoldervisibilitystate.Thispropertyisonlyrelevantfor
geographicChildFolderobjects.
Version :2.6.1
Type:Boolean
Access:Read/Write
SELECTED
ChildFolderselectedstate,eitherselectedornotselected.
Version :2.6.1
Type:Boolean
Access:Read/Write
POSITION
ChildFolderposition,relativetotheparentChildFolderobject.
Version :2.6.1
Type:Integer
Access:Read/Write
OBJECTKIND
ChildFoldertypeidentifier.Thisisthesameasthevaluereturned
byget_ObjectKind.
Version :2.7.0
Type:String
Access:Read
ISGEOGRAPHIC
ReturnstrueiftheChildFolderobjectcanbevisibleintheMap
window,falseotherwise.
Whenthispropertyisfalse,thepropertiesandmethodsspecific
totheMapviewareneitherrelevantnorapplicable.
Version :2.7.0
Type:Boolean
Access:Read
VISIBILITYSCALEMIN
ChildFolderminimumvisibilityscaledisplayproperty.This
propertyisonlyrelevantforgeographicChildFolderobjects.
Version :2.7.0
Type:Integer
Access:Read/Write
VISIBILITYSCALEMAX
ChildFoldermaximumvisibilityscaledisplayproperty.This
propertyisonlyrelevantforgeographicChildFolderobjects.
Version :2.7.0
Type:Integer
Access:Read/Write
ADDTOLEGEND
ChildFolderaddtolegenddisplayproperty.Thispropertyisonly
relevantforgeographicChildFolderobjects.
Version :2.7.0
Type:Boolean
Access:Read/Write
DOCUMENT
ADocumentobject.
TheChildFolderobjectispartoftheDocumentobject.
Version :2.8.2
Type:Object
Access:Read
LEGEND
ChildFolderobjectnameasitappearsintheLegendwindow.
Version :3.2.0
Type:String
Access:Read/Write
11.3 PredictionsFolderProperties
Typereturnedbyget_ObjectKind:{DA676EF0E3004AFFBBFAEC55D3798E4F}
ThefollowingpropertiesareaccessiblethroughthePredictionsfolder.
134
Atoll3.2.1TaskAutomationGuide
Chapter11:ChildFolderObjectProperties
AT321_TAG_E1
Name
Description
Attributes
PRIVATESTORAGE
Pathtothepathlossmatricesprivatestoragefolder,asitappears
inthePredictionsfolderproperties.
Version :2.6.1
Type:String
Access:Read/Write
11.4 CoveragePredictionProperties
Thecoveragepredictiontypesreturnedbyget_ObjectKindforthevariouscoveragepredictionsarelistedbelow:
"GSMGPRSEDGECoveragePredictions"onpage 135,
"UMTSHSPACoveragePredictions"onpage 135,
"WiMAXCoveragePredictions"onpage 136,
"LTECoveragePredictions"onpage 136.
Coveragepredictionpropertiesareofthefollowingtypes:
"GeneralProperties"onpage 137,
"Group,Filter,andSortProperties"onpage 137,
"NonSimulationbasedCoverageConditions"onpage 137:Coverageconditionsforpredictionsthatcannotbebased
onsimulations,
"SimulationbasedCoverageConditions"onpage 139:Coverageconditionsforpredictionsthatcanbebasedonsim
ulations,
"ShadowingandIndoorCoverageConditions"onpage 140,
"DisplayProperties"onpage 140.
GSMGPRSEDGECoveragePredictions
Name
Type
CoveragebyTransmitter
{9E42C87F56D043caA31378A7CA9A811B}
CoveragebySignalLevel
{1FF202779A4C486aB0A490E7E8EC72E4}
OverlappingZones
{1F0C294B11A045c99B32640FED79BCA6}
CoveragebyC/ILevel
{8A94CAE7B4FF4dc6854ABC90FE8F0073}
InterferedZones
{EB45E33DFB3344f1A63BB4661ACE78B2}
CoveragebyGPRS/EDGECoding
Scheme
{6B062215EEC140e99A02F909AFF6B5DB}
RLC/MACThroughput/Timeslot
{02BE397A1F4B423eAEC4B8138974ADD8}
ApplicationThroughput/Timeslot
{3F8F8CB3A5DC49f98F3D0E7243AA0E6C}
CircuitQualityIndicatorAnalysis
{67EC97E99F064b0f90C0E42A67FE560C}
Attributes
UMTSHSPACoveragePredictions
Name
Type
CoveragebyTransmitter
{A6FB7132FB5E42ccA1C10BEA4AF09921}
CoveragebySignalLevel
{E82C3B13240E4dd3A553583ADDF57713}
OverlappingZones
{53B30925B781499d90E43F9B8570871B}
CoveragebyTotalNoiseLevel(DL)
{1C9384EB57CA433fBDB307E1BE317890}
PilotQualityAnalysis(Ec/Io)
{66287FC581FA40b684E32C2C4E13D121}
ServiceAreaAnalysis(Eb/Nt)(DL)
{5C6427F7D63A4046B8BD1A5E9D165890}
ServiceAreaAnalysis(Eb/Nt)(UL)
{D75ADE37FB8A4693A78847109A913C29}
EffectiveServiceAreaAnalysis(Eb/
Nt)(DL+UL)
{5F74AEFA295842cc8244C12DC19B26C3}
Attributes
135
Atoll3.2.1TaskAutomationGuide
Chapter11:ChildFolderObjectProperties
Forsk2014
Name
Type
HandoffZones
{39A63BBA02EC43e7852307E29B519181}
PilotPollutionAnalysis
{2199E577F3F54ffdBCAB0D748CA7CCD3}
HSDPAQualityandThroughput
Analysis
{BFDDFC83D8EE4225840FEF842DE19B74}
HSUPAQualityandThroughput
Analysis
{E9ED15F1EC144451ADFA1953A6FB2526}
ScramblingCodeCollisionZones
{AC612067A173439eBF7A76B17933A30E}
Attributes
WiMAXCoveragePredictions
Name
Type
Attributes
CoveragebyTransmitter
{BE607087CB08453CB2A0B356CD38C3F5}
Version :2.7.1
CoveragebySignalLevel
{9C602E1CE5E744CA8E5B878D74D07885}
Version :2.7.1
OverlappingZones
{86560A81DE6041CC9B9E83BF33CEF491}
Version :2.7.1
EffectiveSignalAnalysis(DL)
{6A657977CF0E415C8486C41664F7035E}
Version :2.7.1
EffectiveSignalAnalysis(UL)
{3F803866104142678D28FCA43445A642}
Version :2.7.1
CoveragebyC/(I+N)Level(DL)
{DCB4B7564D0242DBB83814A62F603922}
Version :2.7.1
CoveragebyC/(I+N)Level(UL)
{4163305DE2034A7899F6E59EA537AB7E}
Version :2.7.1
CoveragebyBearer(DL)
{C5A270AA15A1443DBBCB77B1B99D447F}
Version :2.7.1
CoveragebyBearer(UL)
{A07FB55064C74D2AB63479FC6A981828}
Version :2.7.1
CoveragebyThroughput(DL)
{645C7166CE004EFBB9AFA7F25A3BBBA6}
Version :2.7.1
CoveragebyThroughput(UL)
{1A8B4ACB8D5149AAAA673ADAB48F09B6}
Version :2.7.1
CoveragebyAerial(DL)
{4A9ED8C5F2DE432B8507C65A3DFE47E3}
Version :3.2.0
Name
Type
Attributes
CoveragebyTransmitter
{BE607087CB08453CB2A0B356CD38C3F5}
Version :2.8.0
CoveragebySignalLevel
{9C602E1CE5E744CA8E5B878D74D07885}
Version :2.8.0
OverlappingZones
{86560A81DE6041CC9B9E83BF33CEF491}
Version :2.8.0
EffectiveSignalAnalysis(DL)
{6A657977CF0E415C8486C41664F7035E}
Version :2.8.0
EffectiveSignalAnalysis(UL)
{3F803866104142678D28FCA43445A642}
Version :2.8.0
CoveragebyC/(I+N)Level(DL)
{DCB4B7564D0242DBB83814A62F603922}
Version :2.8.0
CoveragebyC/(I+N)Level(UL)
{4163305DE2034A7899F6E59EA537AB7E}
Version :2.8.0
CoveragebyBearer(DL)
{C5A270AA15A1443DBBCB77B1B99D447F}
Version :2.8.0
CoveragebyBearer(UL)
{A07FB55064C74D2AB63479FC6A981828}
Version :2.8.0
CoveragebyThroughput(DL)
{645C7166CE004EFBB9AFA7F25A3BBBA6}
Version :2.8.0
CoveragebyThroughput(UL)
{1A8B4ACB8D5149AAAA673ADAB48F09B6}
Version :2.8.0
CoveragebyQualityIndicator(DL)
{B682A005CCC24C7CA9FAD2FEBA633E15}
Version :2.8.0
LTECoveragePredictions
136
Atoll3.2.1TaskAutomationGuide
Chapter11:ChildFolderObjectProperties
AT321_TAG_E1
Name
Type
Attributes
CoveragebyQualityIndicator(UL)
{E648833C48E149C0A56F6B94DBA9C358}
Version :2.8.0
11.4.1 GeneralProperties
Thesepropertiesareavailableforallkindsofcoveragepredictions.
Name
Description
Attributes
DESCRIPTION
Comments
Version :2.7.0
Type:String
Access:Read/Write
RESOLUTION
Resolutionoftheprediction,inmeters.
Version :2.7.0
Type:Integer
Access:Read/Write
LOCKED
Returnstruewhenthepredictionislockedforcalculations,
falseotherwise.
Version :2.7.0
Type:Boolean
Access:Read/Write
ISEMPTY
Returnstruewhenthepredictioncoverageisempty,false
otherwise.
Version :2.7.0
Type:Boolean
Access:Read
ISPERTRANSMITTER
Returnstruewhenthepredictionispertransmitter,false
otherwise.Thereturnvaluedependsonthedisplayfieldof
theprediction.
Version :2.7.0
Type:Boolean
Access:Read
URL
Anemptystringwhenthecoveragepredictiondoesnot
haveexternalnumericalresults,otherwisetheabsolute
pathtothediskfoldercontainingnumericalresults.
Version :3.2.1
Type:String
Access:Read
11.4.2 Group,Filter,andSortProperties
ThesepropertiesarecalledRECORDSETCONDITIONS,whichareavailableforallkindsofcoveragepredictions.
Name
Attributes
RECORDSETCONDITIONS
Version :2.7.0
PropertyContainerobject
ThefollowingRECORDSETCONDITIONSareavailable:
Name
Description
Attributes
GROUPBY
"GroupBy"partoftherecordsetconditions,appliedtothe
Transmitterstable.
Version :2.7.0
Type:String
Access:Read/Write
FILTER
"Filter"partoftherecordsetconditions,appliedtothe
Transmitterstable.
Version :2.7.0
Type:String
Access:Read/Write
SORT
"Sort"partoftherecordsetconditions,appliedtothe
Transmitterstable.
Version :2.7.0
Type:String
Access:Read/Write
11.4.3 NonSimulationbasedCoverageConditions
ThesepropertiesarecalledCOVERAGECONDITIONS.
137
Atoll3.2.1TaskAutomationGuide
Chapter11:ChildFolderObjectProperties
Forsk2014
Name
Attributes
COVERAGECONDITIONS
Version :2.7.0
PropertyContainerobject
Thesepropertiesareavailableforthefollowingcoveragepredictions:
GSMGPRSEDGE:
CoveragebyTransmitter
CoveragebySignalLevel
OverlappingZones
CoveragebyC/ILevel
InterferedZones
CoveragebyGPRS/EDGECodingScheme
RLC/MACThroughput/Timeslot
ApplicationThroughput/Timeslot
UMTSHSPA:
CoveragebyTransmitter
CoveragebySignalLevel
OverlappingZones
WiMAX(Version :2.7.1):
CoveragebyTransmitter
CoveragebySignalLevel
OverlappingZones
LTE(Version :2.8.0):
CoveragebyTransmitter
CoveragebySignalLevel
OverlappingZones
ThefollowingCOVERAGECONDITIONSareavailable:
138
Name
Description
Attributes
FIELDTYPE
Thefieldtypetobasethepredictionwith.
Thevaluesare:1=PathLoss(dB);2=TotalLosses(dB);
3=SignalLevel(dBm);4=SignalLevel(dBV);5=SignalLevel
(dBV/m);
Version :2.7.0
Type:Integer
Access:Read/Write
SERVERTYPE
Thewaytochoosetransmittersamongavailable(active,not
filtered)onesforthecurrentcoverageprediction.
Thevaluesare:0=All;1=BestSignalLevel;2=SecondBest
SignalLevel;
ForGSMGPRSEDGEdocuments,thefollowingvaluesare
alsoavailable:3=BestSignalLevelperHCSLayer;4=Second
BestSignalperHCSLayer;5=BestSignalLeveloftheHighest
PriorityHCSLayer;
6=BestIdleModeReselectionCriterion(C2);
Version :2.7.0
Type:Integer
Access:Read/Write
SERVERMARGIN
Themargin(indB)fromthebestserversignalleveland
signallevelfromotherserverstakingpartintothecurrent
coverage(availableonlyifthebestsignallevelorhighest
priorityoptionisselected)
e.g.:Ifthetwobestserversignallevelsarewithinthe
margin,thesearebothconsideredinthecoveragearea.
Version :2.7.0
Type:Single
Access:Read/Write
TRXTYPE
GSMGPRSEDGE:TheTRXtypetotakeintoaccountforthe
currentcoverageprediction(BCCH,TCH,TCH_EGPRS,
TCH_INNER).
UMTSHSPA:Thecarriernumbertotakeintoaccountforthe
currentcoverageprediction(ALL=Best;0=Carriernumber0;
1=Carriernumber1;2=Carriernumber2;)
Version :2.7.0
Type:
PropertyContainer
object
Access:Read/Write
USESUBCELLRECEPTIONTHRESHOLD
Whethertousethelowerreceptionthresholddefinedfor
thetransmittersubcellornot.WhensettoTrue,the
FIELDMINIMUMpropertyisignored.
Version :2.7.0
Type:Boolean
Access:Read/Write
Atoll3.2.1TaskAutomationGuide
Chapter11:ChildFolderObjectProperties
AT321_TAG_E1
Name
Description
Attributes
FIELDMINIMUM
Thecoveragepredictionlowerthresholdassociatedwith
theFIELDTYPEproperty.Whensetto32768,nominimum
valuewillbeconsidered.
Version :2.7.0
Type:Single
Access:Read/Write
FIELDMAXIMUM
Thecoveragepredictionupperthresholdassociatedwith
theFIELDTYPEproperty.Whensetto32767,nomaximum
valuewillbeconsidered.
Version :2.7.0
Type:Single
Access:Read/Write
11.4.4 SimulationbasedCoverageConditions
ThesepropertiesarecalledSIMULATIONCONDITIONS.
Name
Attributes
SIMULATIONCONDITIONS
Version :2.7.0
Type:PropertyContainerobject
Thesepropertiesareavailableforthefollowingcoveragepredictions:
UMTSHSPA:
CoveragebyTotalNoiseLevel(DL)
PilotQualityAnalysis(Ec/Io)
ServiceAreaAnalysis(Eb/Nt)(DL)
ServiceAreaAnalysis(Eb/Nt)(UL)
EffectiveServiceAreaAnalysis(Eb/Nt)(DL+UL)
HandoffZones
PilotPollutionAnalysis
HSDPAQualityandThroughputAnalysis
HSUPAQualityandThroughputAnalysis
ScramblingCodeCollisionZones
WiMAX:
CoveragebyC/(I+N)Level(DL)
CoveragebyC/(I+N)Level(UL)
CoveragebyBearer(DL)
CoveragebyBearer(UL)
CoveragebyThroughput(DL)
CoveragebyThroughput(UL)
LTE(Version :2.8.0):
CoveragebyC/(I+N)Level(DL)
CoveragebyC/(I+N)Level(UL)
CoveragebyBearer(DL)
CoveragebyBearer(UL)
CoveragebyThroughput(DL)
CoveragebyThroughput(UL)
CoveragebyQualityIndicator(DL)
CoveragebyQualityIndicator(UL)
ThefollowingSIMULATIONCONDITIONSareavailable:
Name
Description
Attributes
TERMINAL
Thenameoftheterminaltypeusedfortheprediction.
Version :2.7.0
Type:String
Access:Read/Write
MOBILITY
Thenameofthemobilitytypeusedfortheprediction.
Version :2.7.0
Type:String
Access:Read/Write
SERVICE
Thenameoftheserviceusedfortheprediction.
Version :2.7.0
Type:String
Access:Read/Write
139
Atoll3.2.1TaskAutomationGuide
Chapter11:ChildFolderObjectProperties
Forsk2014
Name
Description
Attributes
SIMULATION
Thenameofthesimulationusedfortheprediction.When
settoanemptystring,nosimulationwillbeusedtoperform
theprediction.
Version :2.7.0
Type:String
Access:Read/Write
AVERAGESIMULATION
Whethertheaveragesimulationwillbeusedtoperformthe
prediction.Thispropertyisnotrelevantwhenthe
SIMULATIONpropertyisempty.Thispropertyisnot
availableforWiMAXandLTEpredictions.
Version :2.7.0
Type:Boolean
Access:Read/Write
MINIMUMPROBABILITY
Theminimumprobabilityusedtoperformtheprediction.
ThispropertyisonlyrelevantwhentheSIMULATION
propertyisnotemptyandwhentheAVERAGESIMULATION
propertyissettoFalse.Thispropertyisnotavailablefor
WiMAXandLTEpredictions.
Version :2.7.0
Type:Single
Access:Read/Write
CARRIER
Thecarriernumberusedtoperformtheprediction.This
propertyisnotavailableforWiMAXandLTEpredictions.
Version :2.7.0
Type:Integer
Access:Read/Write
DOWNGRADINGALLOWED
Whetherdowngradingwillbeconsideredtoperformthe
prediction,ornot.ThispropertyisnotavailableforWiMAX
andLTEpredictions.
Version :2.7.0
Type:Boolean
Access:Read/Write
BEARER
Thebearerusedtoperformtheprediction.Thispropertyis
onlyrelevantforaHSDPAPrediction.Thispropertyisnot
availableforWiMAXandLTEpredictions.
Version :2.7.0
Type:Integer
Access:Read/Write
11.4.5 ShadowingandIndoorCoverageConditions
ThesepropertiesarecalledCLUTTERCONDITIONS.
Name
Attributes
CLUTTERCONDITIONS
Version :2.7.0
Type:PropertyContainerobject
Thesepropertiesareavailableforallkindsofcoveragepredictions:
Name
Description
Attributes
SHADOWING
Whethertocalculateshadowingmarginsrelatedtothe
definedcelledgecoverageprobabilityandthestandard
deviation(s)perclutterclassornot.WhensettoFalse,no
shadowingeffectisconsidered.
Version :2.7.0
Type:Boolean
Access:Read/Write
INDOORCOVERAGE
Whethertodecreasethereceivedsignallevelatthe
receiveroftheindoorlossdefinedforthecorresponding
clutterclass(clutterclassproperties)
Version :2.7.0
Type:Boolean
Access:Read/Write
EDGECOVERAGEPROBABILITY
Avaluebetween0and100,expressinginpercentagevalue
therequiredcoverageprobabilityatthecelledge.
Version :2.7.0
Type:Single
Access:Read/Write
11.4.6 DisplayProperties
Displaypropertiesforcoveragepredictionsareaccessedthroughapropertynamed"DISPLAYPROPERTIES."The"DISPLAY
PROPERTIES"propertyisacontainerobjectusedtocontainindividualdisplayproperties.
140
Name
Attributes
DISPLAYPROPERTIES
Version :2.7.0
Type:PropertyContainerobject
Atoll3.2.1TaskAutomationGuide
Chapter11:ChildFolderObjectProperties
AT321_TAG_E1
Thepropertiesavailableinthe"DISPLAYPROPERTIES"propertycontainerare,forallkindsofcoveragepredictions:
REPRESENTATIONtabulardataobject
The"REPRESENTATION"tabulardataobjectcontainsattributesofintervalsorvaluesusedtodisplaythepredictiononthe
map.Thistabulardataobjectcanbeeditedtochange,remove,oradddisplayintervalsordisplayvalues.
The"REPRESENTATION"tabulardataobjectisavailableasa"DISPLAYPROPERTIES"propertynamed"REPRESENTATION"
Name
Attributes
REPRESENTATION
Version :2.7.0
Type:TabularDataobject
Theschemaofthe"REPRESENTATION"tabulardataobjectis:
TabularDataColumnName
Description
Attributes
LINESTYLE
Thestyleofthelineusedtodisplaytheintervalorthevalue.
Thevaluesare:5=None;0=Solid;128=SolidDoubleLine;
1=Dash;2=DashDot;4=DashDotDot;
Version :2.7.0
Type:Integer
Access:Read/Write
LINEWIDTH
Thewidthofthelineusedtodisplaytheintervalorthe
value,expressedintenthofapoint.Forinstance,tohavea
linewidthof0,5pt,theLINEWIDTHpropertyvaluemustbe
setto5.
Version :2.7.0
Type:Integer
Access:Read/Write
FILLSTYLE
Thegraphicalstyleusedtofilltheinteriorofthesurface
definedbythedisplayintervalorthedisplayvalue.The
valuesare:0=None;1=Full;2=Horizontal;3=Vertical;
4=DownDiagonal;5=UpDiagonal;6=Grid;7=Treillis;
Version :2.7.0
Type:Integer
Access:Read/Write
MAINCOLOR
Themaincolorassignedtothedisplayintervalorthedisplay
value.ThecolorformatisRGB.
See"ConvertingIntegerstoRGBandViceversa"on
page 141.
Version :2.7.0
Type:Integer
Access:Read/Write
SECONDARYCOLOR
Thesecondarycolorassignedtothedisplayintervalorthe
displayvalue.ThecolorformatisRGB.
See"ConvertingIntegerstoRGBandViceversa"on
page 141.
Version :2.7.0
Type:Integer
Access:Read/Write
SYMBOL
Thispropertyisnotusedtodisplayapredictionintervalora
predictionvalue.
Version :2.7.0
Type:Integer
Access:Read/Write
SYMBOLSIZE
Thispropertyisnotusedtodisplayapredictionintervalora
predictionvalue.
Version :2.7.0
Type:Integer
Access:Read/Write
VALUE
Thetextassignedtothedisplayvalue.Whenthedisplay
typeofthepredictionissettointervals,aNullvalueis
returned.
Version :2.7.0
Type:StringorNull
Access:Read/Write
MINVALUE
Theminimumvalueofthedisplayinterval.Whenthe
displaytypeofthepredictionissettodisplayuniqueor
discretevalues,aNullvalueisreturned.
Version :2.7.0
Type:DoubleorNull
Access:Read/Write
MAXVALUE
Themaximumvalueofthedisplayinterval.Whenthe
displaytypeofthepredictionissettodisplayuniqueor
discretevalues,aNullvalueisreturned.
Version :2.7.0
Type:DoubleorNull
Access:Read/Write
ConvertingIntegerstoRGBandViceversa
ToconvertIntegertoRGBcolorcomponents:
141
Atoll3.2.1TaskAutomationGuide
Chapter11:ChildFolderObjectProperties
Forsk2014
Dim Red
Dim Green
Dim Blue
Let Red = (color And &HFF)
Let Green = ((color \ 256) And &HFF)
Let Blue = ((color \ 65536) And &HFF)
ToconvertRGBcolourcomponentstoInteger:
Dim color
Let color = (Red + Green * 256 + Blue * 65536)
OtherDISPLAYPROPERTIESproperties
DISPLAYPROPERTIES
PropertyName
Description
Attributes
TYPE
Avaluebetween0and2usedtochoosewhichvalueclasses
todisplayonthemapforthecurrentprediction:0=Unique;
1=DiscreteValues;2=ValueIntervals;
Version :2.7.0
Type:Integer
Access:Read/Write
FIELD
Thefieldtitleusedtochoosewhichcoveragetodisplayon
themap.Thefieldtitlemustbecompatiblewiththedisplay
typeproperty.
Version :2.7.0
Type:String
Access:Read/Write
TRANSPARENCY
Avaluebetween0and100usedtoadjustthelevelof
transparencyofthedisplayintervalorthedisplayvalue.
Version :2.7.0
Type:Integer
Access:Read/Write
11.5 GSMSimulationGroupProperties
ThefollowingpropertiesareaccessibleforaGSMMonteCarlosimulationgroup.
Name
Description
TRAFFICMAPS
Thenamesofthetrafficmapsusedbyasimulation
group.
NUMBEROFSIMULATIONS
Thenumberofsimulationsinasimulationgroup.
Attributes
Version :3.2.1
Type:ArrayofStrings
Access:Read/Write
Version :3.2.1
EXECUTELATER
Type:Integer
Access:Read/Write
Version :3.2.1
Whensettotrue,thegroupofsimulationswillberunas
Type:Boolean
partofthepredictionscalculation.
Access:Read
Version :3.2.1
GLOBALSCALINGFACTOR
GENERATORINITIALISATION
142
Globaltrafficdensitiesweighting.
Type:Single
Access:Read/Write
Version :3.2.1
Theseedofthepseudorandomnumbergenerator,used
Type:Integer
toobtaintwoidenticaluserdistributions.
Access:Read/Write
Atoll3.2.1TaskAutomationGuide
Chapter11:ChildFolderObjectProperties
AT321_TAG_E1
Name
Description
MAXNUMBEROFITERATIONS
Themaximumnumberofiterationsiftheconvergence
criteriacannotbereached.
ULCONVERGENCETHRESHOLD
(forSingleRATdocuments)
GSMULCONVERGENCETHRESHOLD
(for3GPPMultiRATdocuments)
DLCONVERGENCETHRESHOLD
(forSingleRATdocuments)
Attributes
Version :3.2.1
Type:Integer
Access:Read/Write
Version :3.2.1
TheULrelativeinterferencedifferencetoreachbetween Type:Single
Access:Read/Write
twoiterativesteps.
Version :3.2.1
TheDLrelativeinterferencedifferencetoreachbetween Type:Single
Access:Read/Write
twoiterativesteps.
GSMDLCONVERGENCETHRESHOLD
(for3GPPMultiRATdocuments)
ULCONVERGENCEINTERFERENCES
Version :3.2.1
TheULnoiseriserelativeinterferencetoreachbetween
Type:Single
twoiterativesteps.
Access:Read/Write
DLCONVERGENCEPWRCTRLGAIN
ThepowercontrolgaindifferencetoreachDLbetween
twoiterativesteps.
Version :3.2.1
Type:Single
Access:Read/Write
11.6 UMTSSimulationGroupProperties
Typereturnedbyget_ObjectKind:{AF5E2B981D5448FA89C58BFA2936ABF2}
ThefollowingpropertiesareaccessibleforaUMTSMonteCarlosimulationgroup.
Name
Description
Attributes
TRAFFICMAPS
Thenamesofthetrafficmapsusedbyasimulationgroup.
Type:ArrayofStrings
Access:Read/Write
NUMBEROFSIMULATIONS
Thenumberofsimulationsinasimulationgroup.
Version :2.7.1
Type:Integer
Access:Read/Write
EXECUTELATER
Whensettotrue,thegroupofsimulationswillberunas
partofthepredictionscalculation.
Version :2.7.1
Type:Boolean
Access:Read
INFORMATIONABOUTMOBILES
Thetypeofoutputsneededinthe"Mobiles"tabofeach
simulationinthesimulationsgroup.Availablevaluesare:
0=OnlytheAverageSimulationAndStatistics;1=No
InformationAboutMobiles;2=StandardInformationAbout
Mobiles;3=DetailedInformationAboutMobiles;
Version :2.7.1
Type:Integer
Access:Read/Write
BEARERRATEDOWNGRADING
Whensettotrue,R99bearerdowngradingisallowed.
Version :2.7.1
Type:Boolean
Access:Read/Write
GLOBALSCALINGFACTOR
Globaltrafficdensitiesweighting.
Version :2.7.1
Type:Single
Access:Read/Write
GENERATORINITIALISATION
Theseedofthepseudorandomnumbergenerator,usedto
obtaintwoidenticaluserdistributions.
Version :2.7.1
Type:Integer
Access:Read/Write
MAXNUMBEROFITERATIONS
Themaximumnumberofiterationsiftheconvergence
criteriacannotbereached.
Version :2.7.1
Type:Integer
Access:Read/Write
143
Atoll3.2.1TaskAutomationGuide
Chapter11:ChildFolderObjectProperties
Forsk2014
Name
Description
Attributes
ULCONVERGENCETHRESHOLD
TheULrelativeinterferencedifferencetoreachbetween
twoiterativesteps.
Version :2.7.1
Type:Single
Access:Read/Write
DLCONVERGENCETHRESHOLD
TheDLrelativeinterferencedifferencetoreachbetween
twoiterativesteps.
Version :2.7.1
Type:Single
Access:Read/Write
CONSTRAINTNUMBEROFCES
Whensettotrue,themaximumnumberofchannel
elementsdefinedpersiteisrespected.
Version :2.7.1
Type:Boolean
Access:Read/Write
CONSTRAINTNUMBEROFCODES
Whensettotrue,OVSFcodesavailibilityischecked.
Version :2.7.1
Type:Boolean
Access:Read/Write
CONSTRAINTULLOADFACTOR
Whensettotrue,themaximumULloadfactorisrespected.
Version :2.7.1
Type:Boolean
Access:Read/Write
CONSTRAINTDLLOAD
Whensettotrue,themaximumDLloadisrespected.
Version :2.7.1
Type:Boolean
Access:Read/Write
CONSTRAINTUSECELLMAXULLOADFA
CTOR
Whensettotrue,themaximumULloadfactorisdefined
percell.
Version :2.7.1
Type:Boolean
Access:Read/Write
CONSTRAINTUSECELLMAXDLLOAD
Whensettotrue,themaximumDLloadisdefinedpercell.
Version :2.7.1
Type:Boolean
Access:Read/Write
MAXULOADFACTOR
GlobalULloadfactortoimposetocells.
Validvaluesarecomprisedbetween0(0%)and1(100%).
Version :2.7.1
Type:Single
Access:Read/Write
MAXDLLOAD
GlobalDLloadtoimposetocells.
Validvaluesarecomprisedbetween0(0%)and1(100%).
Version :2.7.1
Type:Single
Access:Read/Write
IUBTHROUGHPUTS
Iubthroughputs.
Version :3.1.1
Type:Boolean
Access:Read/Write
11.7 WiMAXandLTESimulationGroupProperties
Typereturnedbyget_ObjectKind:{AF5E2B981D5448FA89C58BFA2936ABF2}
ThefollowingpropertiesareaccessibleforaWiMAXorLTEMonteCarlosimulationgroup.
144
Name
Description
Attributes
TRAFFICMAPS
Thenamesofthetrafficmapsusedbyasimulationgroup.
Version :2.8.1
Type:ArrayofStrings
Access:Read/Write
SUBSCRIBERLISTS
Thenamesofthesubscriberlistsusedbyasimulations
group.
Version :2.8.1
Type:ArrayofStrings
Access:Read/Write
NUMBEROFSIMULATIONS
Thenumberofsimulationsinasimulationgroup.
Version :2.8.1
Type:Integer
Access:Read/Write
Atoll3.2.1TaskAutomationGuide
Chapter11:ChildFolderObjectProperties
AT321_TAG_E1
Name
Description
Attributes
EXECUTELATER
Whensettotrue,thegroupofsimulationswillberunas
partofthepredictionscalculation.
Version :2.8.1
Type:Boolean
Access:Read
GLOBALSCALINGFACTOR
Globaltrafficdensitiesweighting.
Version :2.8.1
Type:Single
Access:Read/Write
GENERATORINITIALISATION
Theseedofthepseudorandomnumbergenerator,usedto
obtaintwoidenticaluserdistributions.
Version :2.8.1
Type:Integer
Access:Read/Write
MAXNUMBEROFITERATIONS
Themaximumnumberofiterationsiftheconvergence
criteriacannotbereached.
Version :2.8.1
Type:Integer
Access:Read/Write
ULCONVERGENCETHRESHOLD
TheULrelativetrafficloaddifferencetoreachbetweentwo
iterativesteps.
Version :2.8.1
Type:Single
Access:Read/Write
DLCONVERGENCETHRESHOLD
TheDLrelativetrafficloaddifferencetoreachbetweentwo
iterativesteps.
Version :2.8.1
Type:Single
Access:Read/Write
ULNOISERISECONVERGENCETHRESH
OLD
TheULnoiseriserelativeinterferencetoreachbetween
twoiterativesteps.
Version :2.8.1
Type:Single
Access:Read/Write
CONSTRAINTUSECELLMAXULTRAFFIC
LOAD
Whensettotrue,themaximumULtrafficloadisdefined
percell.
Version :2.8.1
Type:Boolean
Access:Read/Write
CONSTRAINTUSECELLMAXDLTRAFFIC
LOAD
Whensettotrue,themaximumDLtrafficloadisdefined
percell.
Version :2.8.1
Type:Boolean
Access:Read/Write
MAXULTRAFFICLOAD
GlobalULtrafficloadtoimposetocells.
Version :2.8.1
Type:Single
Access:Read/Write
MAXDLTRAFFICLOAD
GlobalDLtrafficloadtoimposetocells.
Version :2.8.1
Type:Single
Access:Read/Write
BACKHAULCAPACITY
NOISERISECONTROL
BackhaulCapacity
NoiseRiseControl
Version :3.2.1
Type:Boolean
Access:Read/Write
Version :3.2.1
Type:Boolean
Access:Read/Write
11.8 3GPPMultiRATSimulationGroupProperties
Thefollowingpropertiesareaccessiblefora3GPPMultiRATsimulationgroup.
Ina3GPPMultiRATdocument,youcanaccessallthepropertieswehaveforallthetechnologiesavailableinyourdocument,
exceptULCONVERGENCETHRESHOLDandDLCONVERGENCETHRESHOLDwhichareprefixedwiththetechnologyname.
145
Atoll3.2.1TaskAutomationGuide
Chapter11:ChildFolderObjectProperties
Name
Forsk2014
Description
Attributes
GSMULCONVERGENCETHRESHOLD
Version :3.2.1
ForGSMtechnology:
TheULrelativeinterferencedifferencetoreachbetween Type:Single
twoiterativesteps.
Access:Read/Write
GSMDLCONVERGENCETHRESHOLD
Version :3.2.1
ForGSMtechnology:
TheDLrelativeinterferencedifferencetoreachbetween Type:Single
twoiterativesteps.
Access:Read/Write
Name
Description
Attributes
Version :3.2.1
ForUMTStechnology:
UMTSULCONVERGENCETHRESHOLD TheULrelativeinterferencedifferencetoreachbetween Type:Single
twoiterativesteps.
Access:Read/Write
UMTSDLCONVERGENCETHRESHOLD
Name
Version :3.2.1
ForUMTStechnology:
TheDLrelativeinterferencedifferencetoreachbetween Type:Single
twoiterativesteps.
Access:Read/Write
Description
Attributes
LTEULCONVERGENCETHRESHOLD
Version :3.2.1
ForLTEtechnology:
TheULrelativeinterferencedifferencetoreachbetween Type:Single
twoiterativesteps.
Access:Read/Write
LTEDLCONVERGENCETHRESHOLD
Version :3.2.1
ForLTEtechnology:
TheDLrelativeinterferencedifferencetoreachbetween Type:Single
twoiterativesteps.
Access:Read/Write
11.9 PropagationModelProperties
TheTypereturnedbyget_ObjectKindforthePropagationModelsfolder:{4A2D160B7D114D0792DFA3CF6B68D402}
get_ObjectKindisaccessibleforthePropagationModelsfolderforversion 2.7.0.
TheTypereturnedbyget_ObjectKindfortheStandardPropagationModel:Atoll.StdPropagModel.1
get_ObjectKindisaccessiblefortheStandardPropagationModelforversion 2.7.0.
TheStandardPropagationModelpropertiesarecalledMODELPROPERTIES.
Name
Attributes
MODELPROPERTIES
Thepropertycontainerholdingthepropagationmodelparameters
Version :2.7.0
Type:PropertyContainerobject
ThefollowingMODELPROPERTIESareavailablefortheStandardPropagationModel:
Name
146
Description
Attributes
EFFECTIVEANTENNAHEIGHTMETHO
D
Version :2.7.0
Type:Integer
Access:Read/Write
EFFECTIVEANTENNAHEIGHTDISTANC
EMIN
Version :2.7.0
Type:Double
Access:Read/Write
Atoll3.2.1TaskAutomationGuide
Chapter11:ChildFolderObjectProperties
AT321_TAG_E1
Name
Description
Attributes
EFFECTIVEANTENNAHEIGHTDISTANC
EMAX
Version :2.7.0
Type:Single
Access:Read/Write
DIFFRACTIONMETHOD
Version :2.7.0
Type:Integer
Access:Read/Write
CLUTTERLOSSES
CLUTTERCLEARANCES
LossforeachclutterclassdefinedintheAtolldocument.
Whentherearenoclutterclasses,theNullvalueis
returned,otherwisethesizeofthereturnedarrayisthe
numberofclutterclassesdefinedintheAtolldocument.
Version :2.7.0
Type:ArrayofSingle
Access:Read/Write
ClearanceforeachclutterclassdefinedintheAtoll
Version :2.7.0
document.Whentherearenoclutterclasses,theNullvalue
Type:ArrayofSingle
isreturned,otherwisethesizeofthereturnedarrayisthe
Access:Read/Write
numberofclutterclassesdefinedintheAtolldocument.
CLUTTERWEIGHTINGFUNCTION
Version :2.7.0
Type:Integer
Access:Read/Write
CLUTTERMAXIMUMDISTANCE
Version :2.7.0
Type:Double
Access:Read/Write
K1
Version :2.7.0
Type:ArrayofSingle
Access:Read/Write
K2
Version :2.7.0
Type:ArrayofSingle
Access:Read/Write
K3
Version :2.7.0
Type:Double
Access:Read/Write
K4
Version :2.7.0
Type:Double
Access:Read/Write
K5
Version :2.7.0
Type:Double
Access:Read/Write
K6
Version :2.7.0
Type:Double
Access:Read/Write
KCLUTTER
Version :2.7.0
Type:Double
Access:Read/Write
NEARTRANSMITTERMAXIMUMDISTA
NCE
Version :2.7.0
Type:Double
Access:Read/Write
PROFILES
Version :2.7.0
Type:Integer
Access:Read/Write
GRIDCALCULATION
Version :2.7.0
Type:Integer
Access:Read/Write
147
Atoll3.2.1TaskAutomationGuide
Chapter11:ChildFolderObjectProperties
Name
Forsk2014
Description
Attributes
CONSIDERCLUTTERHEIGHTSINDIFFR
ACTION
Version :2.7.0
Type:Integer
Access:Read/Write
HILLYTERRAINCORRECTION
Version :2.7.0
Type:Integer
Access:Read/Write
CLUTTERRECEIVERHEIGHTS
Heightofthereceiverforeachclutterclassdefinedinthe
Version :2.7.0
Atolldocument.Whentherearenoclutterclasses,theNull
Type:ArrayofSingle
valueisreturned,otherwisethesizeofthereturnedarrayis
Access:Read/Write
thenumberofclutterclassesdefinedintheAtolldocument.
LIMITATIONTOFREESPACELOSS
Version :2.7.0
Type:Integer
Access:Read/Write
RECEIVERONTOPOFCLUTTER
Version :2.7.0
Type:Integer
Access:Read/Write
11.10 CWMeasurementProperties
TheTypereturnedbyget_ObjectKindfortheCWMeasurementsfolder:SID_CW_MEASUREMENTS
ThefollowingpropertiesareaccessiblefortheCWMeasurementsfolder:
Name
Description
Attributes
VECTORDATAFILTER
Advancedvectortablefilter,asitappearsinCW
Measurementsfoldersproperties.
Type:String
Access:Read/Write
TheTypereturnedbyget_ObjectKindforaCWMeasurementssubfolder:MeasureTx
ThefollowingpropertiesareaccessibleforaCWMeasurementssubfolder:
Name
Description
Attributes
VECTORDATAFILTER
Advancedvectortablefilter,asitappearsinCW
Measurementssubfolderproperties.
Type:String
Access:Read/Write
TheTypereturnedbyget_ObjectKindforaCWMeasurementsitem:MeasureItem
ThefollowingpropertiesareaccessibleforaCWMeasurementsitem:
Name
Description
Attributes
VECTORDATAFILTER
Advancedvectortablefilter,asitappearsinCW
Measurementsitemproperties.
Type:String
Access:Read/Write
PREDICTIONMODEL
Nameofapropagationmodel.
Type:String
Access:Read/Write
Type:String
Access:Read/Write
HEADER
TRANSMITTERNAME
148
Nameofatransmitter.
Type:String
Access:Read/Write
TRANSMITTERFREQUENCY
Type:Single
Access:Read/Write
RECEIVERHEIGHT
Type:Single
Access:Read/Write
Atoll3.2.1TaskAutomationGuide
Chapter11:ChildFolderObjectProperties
AT321_TAG_E1
Name
Description
Attributes
RECEIVERGAIN
Type:Single
Access:Read/Write
RECEIVERLOSSES
Type:Single
Access:Read/Write
VECTORDATA
Tablecontentofthemeasurementpath.
Type:TabularDataobject
TECHNOLOGYNAME
Technologyname:"UMTS","LTE",or"GSM"
Version :3.1.1
Type:String
Access:Read/Write
11.11 DriveTestDataProperties
TheTypereturnedbyget_ObjectKindforaDriveTestDataitem:NumMeasureItem
ThefollowingpropertiesareaccessibleforaDriveTestDataitem:
Name
Description
Attributes
HEADER
Type:String
Access:Read/Write
RECEIVERHEIGHT
Type:Single
Access:Read/Write
RECEIVERGAIN
Type:Single
Access:Read/Write
RECEIVERLOSSES
Type:Single
Access:Read/Write
VECTORDATA
Tablecontentofthemeasurementpath.
Type:TabularDataobject
11.12 CustomChildFolderObjectProperties
TheTypereturnedbyget_ObjectKindforacustomChildFolderobjectistheversiondependentPROGIDofthecustomChild
Folderobject.
get_ObjectKindisaccessibleforthecustomChildFolderobjectsforversion 2.7.0.
ThefollowingpropertiesareaccessibleforacustomChildFolderobject.
Name
Description
Attributes
MODELPROPERTIES
ThepropertycontainerholdingthecustomChildFolderobject
properties.
TheMODELPROPERTIESPropertyContainerobjectwill
containpropertiesexposedbythecustomChildFolderobject
.
Version :2.7.0
Type:PropertyContainer
object
Access:Read/Write
CANRENAME
ReturnstruewhenthecustomChildFolderobjectcanbe
renamed.
Whenfalseisreturned,the"Rename"contextmenuoption
fortheChildFolderobjectisunavailable.
Version :2.7.0
Type:Boolean
Access:Read/Write
CANDELETE
ReturnstruewhenthecustomChildFolderobjectcanbe
deleted.
Whenfalseisreturned,the"Delete"contextmenuoptionfor
theChildFolderobjectisunavailable.
Version :2.7.0
Type:Boolean
Access:Read/Write
TRANSPARENCY
Theglobaltransparencybetween0and100associatedwith
thecustomChildFolderobject.
Version :2.7.0
Type:Integer
Access:Read/Write
149
Atoll3.2.1TaskAutomationGuide
Chapter11:ChildFolderObjectProperties
Forsk2014
Name
Description
Attributes
COMMENT
ThecommentstringassociatedwiththecustomChildFolder
object.
Version :3.2.1
Type:String
Access:Read/Write
11.13 MasterLinkProperties
MasterLinkChildFolderobjectsarelocatedastoplevelitemsineithertheDatatabortheGeotabofthedocumentexplorer
window.They are usedtospecifylinksfromoneChildFolderobjectto anotherChildFolderobject(thetargetChildFolder
object),locatedinanotherDocumentobject(thetargetDocumentobject).
TheTypereturnedbyget_ObjectKindforMasterLinkChildFolderobjectsis:
{16A53FB3-A961-4EEA-8C30-2387DBF1CC24}
ThefollowingpropertiesareaccessibleforMasterLinkChildFolderobjects.
Name
Description
Attributes
TARGET
ThetargetChildFolderobject.
TheNullvalueisreturnedwhenthetargetDocumentobject
isnotopenedinthecurrentsession.
Type:Object,orNull
value.
Access:Read
TARGETDOCUMENTFULLNAME
Thefullpathtothetargetdocument.ATLfile.
Anerrorisreturnedwhenthetargetfilecannotbelocated.
Type:String
Access:Read
11.14 LinkProperties
LinkChildFolderobjectsarechildrenofMasterLinkChildFolderobjects.
TheTypereturnedbyget_ObjectKindforLinkChildFolderobjectsis:
{232BDB73-A68F-41A6-A954-75112D907BBF}
ThefollowingpropertiesareaccessibleforLinkChildFolderobjects.
Name
TARGET
Description
Attributes
ThetargetChildFolderobject.
Type:Object,orNull
TheNullvalueisreturnedwhenthetargetDocumentobject
value.
isnotopenedinthecurrentsession.
Access:Read
11.15 VectorLayerProperties
ThefollowingpropertiesareaccessibleforVectorLayerChildFolderobjects.
Name
VECTORDATA
DISPLAYPROPERTIES
Description
Thevectortableofthevectorlayer.
Thevectorlayerdisplayproperties.
Attributes
Version :3.2.1
Type:TabularData
object
Version :2.7.0
Type:
PropertyContainer
object
11.15.1 DisplayProperties
Displaypropertiesforvectorlayersareaccessedthroughapropertynamed"DISPLAYPROPERTIES."The"DISPLAYPROPERTIES
"propertyisacontainerobjectusedtocontainindividualdisplayproperties.
150
Atoll3.2.1TaskAutomationGuide
Chapter11:ChildFolderObjectProperties
AT321_TAG_E1
Thepropertiesavailableinthe"DISPLAYPROPERTIES"propertycontainerare,forallkindsofvectorlayers:
REPRESENTATIONtabulardataobject
The"REPRESENTATION"tabulardataobjectcontainsattributesofintervalsorvaluesusedtodisplaythevectorlayeronthe
map.Thistabulardataobjectcanbeeditedtochange,remove,oradddisplayintervalsordisplayvalues.
The"REPRESENTATION"tabulardataobjectisavailableasa"DISPLAYPROPERTIES"propertynamed"REPRESENTATION"
DISPLAYPROPERTIES
PropertyName
Attributes
REPRESENTATION
Version :3.2.1
Type:TabularDataobject
Theschemaofthe"REPRESENTATION"tabulardataobjectis:
TabularDataColumnName
Description
Attributes
LINESTYLE
Thestyleofthelineusedtodisplaytheintervalorthevalue.
Thevaluesare:5=None;0=Solid;128=SolidDoubleLine;
1=Dash;2=DashDot;4=DashDotDot;
Version :3.2.1
Type:Integer
Access:Read/Write
LINEWIDTH
Thewidthofthelineusedtodisplaytheintervalorthe
value,expressedintenthofapoint.Forinstance,tohavea
linewidthof0,5pt,theLINEWIDTHpropertyvaluemustbe
setto5.
Version :3.2.1
Type:Integer
Access:Read/Write
FILLSTYLE
Thegraphicalstyleusedtofilltheinteriorofthesurface
definedbythedisplayintervalorthedisplayvalue.The
valuesare:0=None;1=Full;2=Horizontal;3=Vertical;
4=DownDiagonal;5=UpDiagonal;6=Grid;7=Treillis;
Version :3.2.1
Type:Integer
Access:Read/Write
MAINCOLOR
Themaincolorassignedtothedisplayintervalorthedisplay
value.ThecolorformatisRGB.
See"ConvertingIntegerstoRGBandViceversa"on
page 141.
Version :3.2.1
Type:Integer
Access:Read/Write
SECONDARYCOLOR
Thesecondarycolorassignedtothedisplayintervalorthe
displayvalue.ThecolorformatisRGB.
See"ConvertingIntegerstoRGBandViceversa"on
page 141.
Version :3.2.1
Type:Integer
Access:Read/Write
SYMBOL
Thispropertyisnotusedtodisplayavectorlayerintervalor
avectorlayervalue.
Version :3.2.1
Type:Integer
Access:Read/Write
SYMBOLSIZE
Thispropertyisnotusedtodisplayavectorlayerintervalor
avectorlayervalue.
Version :3.2.1
Type:Integer
Access:Read/Write
VALUE
Thetextassignedtothedisplayvalue.Whenthedisplay
typeofthevectorlayerissettointervals,aNullvalueis
returned.
Version :3.2.1
Type:StringorNull
Access:Read/Write
MINVALUE
Theminimumvalueofthedisplayinterval.Whenthe
displaytypeofthevectorlayerissettodisplayuniqueor
discretevalues,aNullvalueisreturned.
Version :3.2.1
Type:DoubleorNull
Access:Read/Write
MAXVALUE
Themaximumvalueofthedisplayinterval.Whenthe
displaytypeofthevectorlayerissettodisplayuniqueor
discretevalues,aNullvalueisreturned.
Version :3.2.1
Type:DoubleorNull
Access:Read/Write
ConvertingIntegerstoRGBandViceversa
ToconvertIntegertoRGBcolorcomponents:
151
Atoll3.2.1TaskAutomationGuide
Chapter11:ChildFolderObjectProperties
Forsk2014
Dim Red
Dim Green
Dim Blue
Let Red = (color And &HFF)
Let Green = ((color \ 256) And &HFF)
Let Blue = ((color \ 65536) And &HFF)
ToconvertRGBcolourcomponentstoInteger:
Dim color
Let color = (Red + Green * 256 + Blue * 65536)
OtherDISPLAYPROPERTIESproperties
152
DISPLAYPROPERTIES
PropertyName
Description
Attributes
TYPE
Avaluebetween0and2usedtochoosewhichvalueclasses
todisplayonthemapforthecurrentvectorlayer:
0=Unique;1=DiscreteValues;2=ValueIntervals;
Version :3.2.1
Type:Integer
Access:Read/Write
FIELD
Thefieldtitleusedtochoosewhichcoveragetodisplayon
themap.Thefieldtitlemustbecompatiblewiththedisplay
typeproperty.
Version :3.2.1
Type:String
Access:Read/Write
TRANSPARENCY
Avaluebetween0and100usedtoadjustthelevelof
transparencyofthedisplayintervalorthedisplayvalue.
Version :3.2.1
Type:Integer
Access:Read/Write
Chapter12
ChildFolderFeature
Objects
Atoll3.2.1TaskAutomationGuide
154
Forsk2014
Atoll3.2.1TaskAutomationGuide
Chapter12:ChildFolderFeatureObjects
AT321_TAG_E1
12 ChildFolderFeatureObjects
FeatureobjectsofferfeaturescloselytiedtosomeAtolldocumentfolders.ThefollowingChildFolderFeatureobjectsareavail
ablethroughtheDispatchpropertyofChildFolderobjectsofAtolldocumentfolders:
"ClutterFeatureObject"onpage 155,
"TrafficFeatureObject"onpage 158,
"UMTSTrafficScenarioProviderObject"onpage 161,
"EnvironmentBasedTrafficMapFeatureObject"onpage 163,
"SimulationFeatureObject"onpage 165,
"SimulationGroupFeatureObject"onpage 168.
12.1 ClutterFeatureObject
TheClutterFeatureobjectgivesaccesstoclutterclassesproperties.ItisavailableforallAtolldocuments.Itisassociatedwith
theClutterClassesfolderofanAtolldocument.
TheClutterFeatureobjectprovidesthefollowingpropertiesandmethods:
Name
Description
get_Source
ReturnstheClutterClassesChildFolderobject.
get_ClassAttributes
ReturnsaTabularDataobjectholdingtheclutterclassattributes.
get_DefaultAttributes
ReturnsaTabularDataobjectholdingtheclutterclassdefault
values.
Attributes
12.1.1 HowtoAccesstheClutterFeatureObject
TheObjectKindpropertyfortheClutterClassesfolderis:
{7CB51DE8-A961-11D2-8688-0060086457D1}
SamplecodetoaccesstheClutterFeatureobject:
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
ReturnstheClutterClassesChildFolderobject.
155
Atoll3.2.1TaskAutomationGuide
Chapter12:ChildFolderFeatureObjects
Forsk2014
12.1.3 get_ClassAttributes
ReturnsaTabularDataobjectholdingtheclutterclassattributes.
12.1.4 get_DefaultAttributes
ReturnsaTabularDataobjectholdingtheclutterclassdefaultvalues.
12.1.5 AccessingClutterClassAttributes
SamplemacrotooutputthevariousclutterclassattributestotheAtolleventviewer:
156
Atoll3.2.1TaskAutomationGuide
Chapter12:ChildFolderFeatureObjects
AT321_TAG_E1
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."
157
Atoll3.2.1TaskAutomationGuide
Chapter12:ChildFolderFeatureObjects
Forsk2014
End Sub
12.2 TrafficFeatureObject
TheTrafficFeatureobjectgivesaccesstofeaturesassociatedwiththetrafficfolder,suchastheexportofthecumulatedtraf
fic.ItisavailableforallAtolldocumentsexceptMicrowaveLinksdocuments.ItisassociatedwiththeTrafficfolderofanAtoll
document.
TheTrafficFeatureobjectprovidesthefollowingpropertiesandmethods:
Name
Description
get_Source
ReturnstheTrafficChildFolderobject.
get_ScenarioProvider
CreatesanewTrafficScenarioProviderobjectinstance.
ExportCumulatedTraffic
Exportsthecumulatedtraffic.
HasTrafficForService
Determinesifatrafficmapcontainstrafficinformationforagiven
service.
Attributes
12.2.1 HowtoAccesstheTrafficFeatureObject
TheObjectKindpropertyfortheTrafficfolderis:
{B3B25A07-A994-4E8D-BBD1-51556D6C4245}
SamplecodetoaccesstheTrafficFeatureObject:
' 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
ReturnstheTrafficChildFolderobject.
12.2.3 get_ScenarioProvider
CreatesanewTrafficScenarioProviderobjectinstance.See"UMTSTrafficScenarioProviderObject"onpage 161formore
informationontheUMTSTrafficScenarioProviderobject.
158
Atoll3.2.1TaskAutomationGuide
Chapter12:ChildFolderFeatureObjects
AT321_TAG_E1
Parameters
[out]ppProvider:AddressoftheITrafficScenarioProviderinterfacepointerusedtoreturnanewTrafficScenarioProvider
objectinstance.
Remarks
AnerrorisreturnedwhenthismethodiscalledforanAtolldocumentnotbasedontheUMTSHSPAtemplate.
12.2.4 ExportCumulatedTraffic
Exportsthecumulatedtraffic.
159
Atoll3.2.1TaskAutomationGuide
Chapter12:ChildFolderFeatureObjects
Forsk2014
AnAtoRegionenumerationvalueusedtospecifytheareausedtoexportthecumulatedtraffic:
atoEntireProjectArea:Theentireprojectarea
atoComputationZone:Thecomputationzone
[in]bstrTerminal:
ABSTRusedtospecifytheterminalnameusedtoexportthecumulatedtraffic.
If"(ALL)"isspecified,thenallterminalsareusedtoexportthecumulatedtraffic.
[in]bstrMobility:
ABSTRusedtospecifythemobilitynameusedtoexportthecumulatedtraffic.
If"(ALL)"isspecified,thenallmobilitiesareusedtoexportthecumulatedtraffic.
[in]bstrService:
ABSTRusedtospecifytheservicenameusedtoexportthecumulatedtraffic.
If"(ALLCS)"isspecified,thenallcircuitservicesareusedtoexportthecumulatedtraffic.
If"(ALLPS)"isspecified,thenallpacketservicesareusedtoexportthecumulatedtraffic.
[in]vTrafficMaps:
AVARIANTusedtospecifythetrafficmapsusedtoexportthecumulatedtraffic.ThetypeoftheVARIANTmustbeVT_ARRAY
|VT_VARIANTwithVARIANTsoftypeVT_BSTR.TheVARIANTarraycontainsthenamesofthetrafficmaps.
[in]lResolution:
Alongusedtospecifytheresolutioninmeterusedtoexportthecumulatedtraffic.
[in]atoDirection:
AnAtoDirectionenumerationvalueusedtospecifythekindoftrafficusedtoexportthecumulatedtraffic.
12.2.5
Determinesifatrafficmapcontainstrafficinformationforagivenservice.
HRESULT HasTrafficForService(
BSTR bstrServiceName,
enum _AtoDirection atoDirection,
IChildFolder* pTrafficMap,
VARIANT_BOOL* pHasTraffic
);
Parameters
[in]bstrServiceName:
ABSTRusedtospecifytheaservicename.
[in]atoDirection:
AnAtoDirectionenumerationvalueusedtospecifythekindoftraffictolookfor:
atoUplinkDownlink(=0):Uplinkanddownlinktraffic
atoUplink(=1):Uplinktraffic
atoDownlink(=2):Downlinktraffic
[in]pTrafficMap:
AIChildFolderinterfacepointerusedtospecifythetrafficmapChildFolderobject.Thetrafficmapissearchedfortrafficinfor
mationrelatedtothebstrServiceNameservice.
ThisparametermaybeNULL.Inthiscase,alltrafficmapsinthetrafficmapfolderaresearched.
160
Atoll3.2.1TaskAutomationGuide
Chapter12:ChildFolderFeatureObjects
AT321_TAG_E1
[out]pHasTraffic:
ApointertoaVARIANT_BOOLvalueusedtoreturnwhetherthetrafficmapspecifiedbypTrafficMap has some traffic information for the service specified by bstrServiceName.
Remark
WhenHasTrafficForServicereturnsVARIANT_FALSE,thetrafficmapisguaranteednottocontaintrafficinformationforthe
When HasTrafficForService returns VARIANT_TRUE, the traffic map still may not contain traffic information for the given
service.
12.3 UMTSTrafficScenarioProviderObject
ThetrafficscenarioproviderallowsdevelopingexternalUMTSsimulationmodules.RawmobiledataisgeneratedbyAtolland
providedtotheexternalUMTSsimulatorthroughthisobject.
TheTrafficScenarioProviderobjectprovidesthefollowingpropertiesandmethods:
Name
Description
GetMeanSize
Returnstheaveragecountofmobiles.
Create
Createsrawmobiledata.
Attributes
12.3.1 GetMeanSize
Returnstheaveragecountofmobiles.
HRESULT GetMeanSize(
const VARIANT aSelectedMapsNames,
double dScale,
const VARIANT aReserved,
ULONG *pMobilesCount
);
Parameters
[in]aSelectedMapsNames:
AVARIANTvalueusedtospecifythenamesofthetrafficenvironmentmaps.ThetypeoftheVARIANTmustbeVT_ARRAY|
VT_UI1,itcontainsthenamesofthetrafficenvironmentmaps,separatedbytheASCIIcharactercode0.
[in]dScale:
Adoublevalueusedtospecifythescalingfactorusedinthedeterminationofthemobilescount.
[in]aReserved:
AVARIANTvaluereservedforfutureuse.TheVARIANTtypemustbeVT_EMPTY.
[out]pMobilesCount:
AddressoftheULONGintegerusedtoreturntheaveragecountofmobiles.
12.3.2 Create
Createsrawmobiledata.ThemobilesdataisreturnedasaTabularDataobjectcontainingthepositionofthemobilesand
otherinformationrelatedtothestateofmobiles.
161
Atoll3.2.1TaskAutomationGuide
Chapter12:ChildFolderFeatureObjects
Forsk2014
HRESULT Create(
const VARIANT aSelectedMapsNames,
double dScale,
enum AtoTrafficScenarioLaw aLaw,
const VARIANT aRreserved,
ITabularData **ppMobiles
);
Parameters
[in]aSelectedMapsNames:
AVARIANTvalueusedtospecifythenamesofthetrafficmaps.ThetypeoftheVARIANTmustbeVT_ARRAY|VT_UI1,it
containsthenamesofthetrafficmaps,separatedbytheASCIIcharactercode0.
[in]dScale:
Adoublevalueusedtospecifythescalingfactorusedinthedeterminationofthemobilescount.
Thescalingfactorisrelativetotheaveragesizeofmobiles,asreturnedbyGetMeanSize.
[in]aLaw:TheAtoTrafficScenarioLawenumerationvalueusedtospecifythelawofprobabilityusedtogetarandomcountof
mobiles.
[in]aReserved:AVARIANTvalueusedtospecifyadditionalparameters.
Atollversion<2.7.0:
TheVARIANTtypemustbeVT_EMPTY.
Atollversion>=2.7.0:
When the VARIANT type is VT_DISPATCH, it is interpreted as a PropertyContainer object, implementing the
IPropertyContainer2interface.
Thepropertycontainerobjectmaycontaintheproperties:
Name:RANDOMSEED
Type:VT_I4
Description:Anintegervalueusedtospecifytherandomseedofthepseudorandomnumbergeneratorusedtodeter
minetheaveragecountofmobiles,andthemobilespositions.
[out]ppMobiles:
AddressoftheITabularDatainterfacepointerusedtoreturnthepositionofthemobilesandotherinformationrelatedtothe
stateofmobiles.Thetabulardataschemais:
162
ColumnName
Value
Type
Description
Xcoordinate
Long
Expressedinthedocumentprojectioncoordinatesystem
Ycoordinate
Long
Expressedinthedocumentprojectioncoordinatesystem
SERVICE
Servicename
String
FromtheUMTSServicestable
TERMINAL
Terminalname
String
FromtheUMTSTerminalstable
MOBILITY
Mobilitytype
String
FromtheUMTSMobilitytable
CLUTTER
Cluttercode
Short
FromtheIClutterinterface
ACTIVITY
Mobileactivity
String
"ActiveDL","UL","UL+DL"
Atoll3.2.1TaskAutomationGuide
Chapter12:ChildFolderFeatureObjects
AT321_TAG_E1
12.4 EnvironmentBasedTrafficMapFeatureObject
Userprofileenvironmentbasedtrafficmapfeatureobjectsgiveaccesstouserprofileenvironmentbasedtrafficmapsattrib
utes.TheyareavailableforallAtolldocumentsexceptMicrowaveLinksdocuments.Theyareassociatedwithuserprofile
environmentbasetrafficmapscontainedintheTrafficfolderofanAtolldocument.
TheUserProfileEnvironmentBasedTrafficMapFeatureobjectprovidesthefollowingpropertiesandmethods:
Name
Description
get_Source
ReturntheTrafficMapChildFolderobjectassociatedwiththe
TrafficMapperEnvironmentFeatureobject.
get_ClassAttributes
ReturnsaTabularDataobjectholdingthetrafficmapenvironment
attributes.
get_DefaultAttributes
Notimplemented
Attributes
12.4.1 HowtoAccessEnvironmentBasedTrafficMapFeature
Objects
TheObjectKindpropertyforUserProfileEnvironmentBasedTrafficMapsis:
{E8784A75-AE03-4F4F-B923-6E8BF20725C5}
TheUserProfileEnvironmentBasedTrafficMapFeatureobjectforauserprofileenvironmentbasedtrafficmapisreturned
bytheDispatchpropertyoftheuserprofileenvironmentbasedtrafficmapChildFolderobject.
12.4.2 get_Source
ReturntheUserProfileEnvironmentBaseTrafficMapChildFolderobjectassociatedwiththeUserProfileEnvironmentBased
TrafficMapFeatureObject.
12.4.3 get_ClassAttributes
ReturnsaTabularDataobjectholdingtheuserprofileenvironmentbasedtrafficmapattributes.
12.4.4 get_DefaultAttributes
HRESULT get_DefaultAttributes(ITabularData **ppTable);
Remarks
Thismethodisnotimplemented.Pleasedontusethismethod.
163
Atoll3.2.1TaskAutomationGuide
Chapter12:ChildFolderFeatureObjects
Forsk2014
12.4.5 AccessingEnvironmentBasedTrafficMapsAttributes
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()
164
Atoll3.2.1TaskAutomationGuide
Chapter12:ChildFolderFeatureObjects
AT321_TAG_E1
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 SimulationFeatureObject
SimulationFeatureobjectsgiveaccesstosimulationresults.TheyareassociatedwithSimulationChildFolderobjects.
165
Atoll3.2.1TaskAutomationGuide
Chapter12:ChildFolderFeatureObjects
Forsk2014
SimulationFeatureobjectsareavailableinAtolldocumentsbasedonthetemplates:
UMTSHSPA
LTE
CDMA20001xRTT1xEVDO
WiMAX802.16e
TDSCDMA
TheSimulationFeatureobjectprovidesthefollowingpropertiesandmethods:
Name
Description
get_Source
ReturnstheassociatedSimulationChildFolderobject.
get_Statistics
ReturnsaTabularDataobjectholdingtheresultsaspresentedin
the"Statistics"propertypageofthesimulationpropertysheet.
get_Cells
ReturnsaTabularDataobjectholdingtheresultsaspresentedin
the"Cells"propertypageofthesimulationpropertysheet.
get_Sites
ReturnsaTabularDataobjectholdingtheresultsaspresentedin
the"Sites"propertypageofthesimulationpropertysheet.
get_Mobiles
ReturnsaTabularDataobjectholdingtheresultsaspresentedin
the"Mobiles"propertypageofthesimulationpropertysheet.
get_Results
ReturnsaTabularDataobjectholdingtherequiredresults,
dependingontheparameterpassedtothismethod.
Attributes
12.5.1 HowtoAccessSimulationFeatureObjects
TheObjectKindpropertyfortheSimulationChildFolderobjectsis:
{095C5D90-96F1-4BA8-85BB-B2F990AC2DD9}
SimulationChildFolderobjectsarechildofSimulationGroupsChildFolderobjects.
SimulationFeatureobjectsareavailablethroughtheDispatchpropertyofSimulationChildFolderobjects:
Dim oSimulation
Dim oSimulationChildFolder
Set oSimulation = oSimulationChildFolder.Dispatch
12.5.2 get_Source
ReturnstheassociatedSimulationChildFolderobject.
12.5.3 get_Statistics
eturnsaTabularDataobjectholdingtheresultsaspresentedinthe"Statistics"propertypageofthesimulationpropertysheet.
166
Atoll3.2.1TaskAutomationGuide
Chapter12:ChildFolderFeatureObjects
AT321_TAG_E1
12.5.4 get_Cells
ReturnsaTabularDataobjectholdingtheresultsaspresentedinthe"Cells"propertypageofthesimulationpropertysheet.
12.5.5 get_Sites
ReturnsaTabularDataobjectholdingtheresultsaspresentedinthe"Sites"propertypageofthesimulationpropertysheet.
12.5.6 get_Mobiles
ReturnsaTabularDataobjectholdingtheresultsaspresentedinthe"Mobiles"propertypageofthesimulationproperty
sheet.
12.5.7 get_Results
ReturnsaTabularDataobjectholdingtherequiredresults.
HRESULTget_Results(enumAtoSimulationResultsType aType, ITabularData **ppResults);
Parameters
[in]aType:AnAtoSimulationResultsTypeenumerationvalue,usedtospecifythesimulationresultstoreturn.
Enumerationvaluesare:
167
Atoll3.2.1TaskAutomationGuide
Chapter12:ChildFolderFeatureObjects
Forsk2014
atoSimulationResultsStatistics
atoSimulationResultsCells
atoSimulationResultsSites
atoSimulationResultsMobiles
atoSimulationResultsGsmSubCells
100
atoSimulationResultsGsmTRXs
101
[out]ppResults:AddressoftheITabularDatainterfacepointerusedtoreturnthesimulationresults.
12.6 SimulationGroupFeatureObject
SimulationGroupFeatureobjectsgiveaccesstogroupofsimulationsproperties.AnAtolldocumentcancontainzero,one,or
moregroupofsimulations.Inturn,simulationgroupscancontainzeroormoresimulations.Theyarelocatedinthe"Simula
tions"folderoftheAtolldocument.SimulationGroupFeatureobjectsareassociatedwithgroupofsimulationsChildFolder
objectsofanAtolldocument.
SimulationGroupFeatureobjectsareavailableinAtolldocumentsbasedonthetemplates:
UMTSHSPA
LTE
CDMA20001xRTT1xEVDO
WiMAX802.16e
TDSCDMA
TheSimulationGroupFeatureobjectprovidesthefollowingpropertiesandmethods:
Name
Description
get_Source
ReturnstheassociatedSimulationGroupChildFolder
object.
get_Statistics
ReturnsaTabularDataobjectholdingthestatisticsofthe
simulationgroup.
get_MeanSimulation
ReturnsaSimulationFeatureobjectgivingaccesstothe
averagesimulationproperties.
get_StdDevSimulation
ReturnsaSimulationFeatureobjectusedtoaccessthe
standarddeviationsimulationproperties.
12.6.1 HowtoAccessSimulationGroupFeatureObjects
TheObjectKindpropertyforGroupofSimulationsfolderis:
{AF5E2B98-1D54-48FA-89C5-8BFA2936ABF2}
SamplecodetoaccessSimulationGroupFeatureobjects:
168
Attributes
Atoll3.2.1TaskAutomationGuide
Chapter12:ChildFolderFeatureObjects
AT321_TAG_E1
"{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
End If
Next
SimulationGroupFeatureObjects = True
End Function
169
Atoll3.2.1TaskAutomationGuide
Chapter12:ChildFolderFeatureObjects
Forsk2014
12.6.2 get_Source
ReturnstheassociatedSimulationGroupChildFolderobject.
12.6.3 get_Statistics
ReturnsaTabularDataobjectholdingthestatisticsofthesimulationgroup.
12.6.4 get_MeanSimulation
ReturnsaSimulationFeatureobjectgivingaccesstotheaveragesimulationproperties.
12.6.5 get_StdDevSimulation
ReturnsaSimulationFeatureobjectusedtoaccessthestandarddeviationsimulationproperties.
170
Atoll3.2.1TaskAutomationGuide
Chapter12:ChildFolderFeatureObjects
AT321_TAG_E1
12.6.6 AccessingMobiles,Cells,Sites,forSimulationsandSimula
tionGroups
HereisasamplemacrousedtodisplaythevariousavailableresultsforsimulationgroupsandsimulationsintheAtollevent
viewer,fortheactivedocument:
'
"{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
171
Atoll3.2.1TaskAutomationGuide
Chapter12:ChildFolderFeatureObjects
Forsk2014
172
Atoll3.2.1TaskAutomationGuide
Chapter12:ChildFolderFeatureObjects
AT321_TAG_E1
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..."
DumpTable(oSimulation.Mobiles)
LogMessage "End Mobiles."
LogMessage "End " & name & "."
End Sub
173
Atoll3.2.1TaskAutomationGuide
Chapter12:ChildFolderFeatureObjects
Forsk2014
174
Atoll3.2.1TaskAutomationGuide
Chapter12:ChildFolderFeatureObjects
AT321_TAG_E1
arraySimulations)
12.7 3GPPMultiRATSimulationGroupFeatureObject
MultiRATSimulationGroupFeatureobjectsareavailableinAtolldocumentsbasedonthetemplates:
3GPPMultiRAT
3GPPMultiRATSimulationGroupFeatureobjectsaresimilartoSimulationGroupFeatureobjectsavailableinsingleRAT
documents,exceptsomemethodsin3GPPMultiRATSimulationGroupFeatureobjectsrequirethenameofthetechnology
tobespecified.MultiRATSimulationGroupFeatureobjectsprovidethefollowingpropertiesandmethods:
Name
Description
get_Source
Returnstheassociated3GPPSimulationGroupChildFolder
object.
get_Statistics
ReturnsaTabularDataobjectholdingthestatisticsofthe
simulationgroupforthespecifiedtechnology.
get_MeanSimulation
ReturnsaSimulationFeatureobjectgivingaccesstothe
averagesimulationpropertiesforthespecifiedtechnology.
get_StdDevSimulation
ReturnsaSimulationFeatureobjectusedtoaccessthe
standarddeviationsimulationpropertiesforthespecified
technology.
Attributes
12.7.1 get_Source
Returnstheassociated3GPPMultiRATSimulationGroupChildFolderobject.
175
Atoll3.2.1TaskAutomationGuide
Chapter12:ChildFolderFeatureObjects
Forsk2014
12.7.2 get_Statistics
ReturnsaTabularDataobjectholdingthestatisticsofthesimulationgroupforthespecifiedtechnology.
12.7.3 get_MeanSimulation
ReturnsaSimulationFeatureobjectgivingaccesstotheaveragesimulationpropertiesforthespecifiedtechnology.
HRESULT get_MeanSimulation(
const BSTR bstrTechno,
ISimulation **ppMeanValues
);
Parameters
[in]bstrTechno:Astringusedtospecifytherequestedtechnology.Availablevaluesare"GSM,UMTS,orLTE.
[out]ppMeanValues:AddressoftheISimulationinterfacepointerusedtoreturntheSimulationFeatureobjectcorresponding
totheaveragesimulation.
Remarks
ThereturnedSimulationFeatureobjectisnotassociatedwithaparticularChildFolderobjectintheAtolldocument.
Anerrorisreturnedwhennosimulationinthesimulationgrouphasconverged.Theaveragesimulationisnotavailablewhen
nosimulationinthesimulationgrouphasconverged.
Anerrorisreturnedwhenthesimulationgrouphasnotbeencalculatedyet,forinstancewhenthe3GPPsimulationgrouphas
beencreatedwiththecheckbox"ExecuteLater"set.
12.7.4 get_StdDevSimulation
ReturnsaSimulationFeatureobjectusedtoaccessthestandarddeviationsimulationpropertiesforthespecifiedtechnology.
HRESULT get_StdDevSimulation(
const BSTR bstrTechno,
ISimulation **ppStdDevValues
);
[in]bstrTechno:Astringusedtospecifytherequestedtechnology.Availablevaluesare"GSM,UMTS,orLTE.
[out]ppStdDevValues:AddressoftheISimulationinterfacepointerusedtoreturntheSimulationFeatureobjectcorrespond
ingtothestandarddeviationsimulation.
Remarks
ThereturnedSimulationFeatureobjectisnotassociatedwithaparticularChildFolderobjectintheAtolldocument.
Anerrorisreturnedwhennosimulationinthesimulationgrouphasconverged.Thestandarddeviationsimulationisnotavail
ablewhennosimulationinthesimulationgrouphasconverged.
Anerrorisreturnedwhenthesimulationgrouphasnotbeencalculatedyet,forinstancewhenthesimulationgrouphasbeen
createdwiththecheckbox"ExecuteLater"set.
AnerrorisreturnedwhentheAtolldocumentisbasedontheLTE,WiMAX802.16etemplates.Thestandarddeviationsimu
lationisnotavailableforLTEandWiMAX.
176
Atoll3.2.1TaskAutomationGuide
Chapter12:ChildFolderFeatureObjects
AT321_TAG_E1
12.8 GSMInterferenceMatrixFeatureObject
GSMInterferenceMatrixFeatureobjectsgiveaccesstoGSMinterferencematrices.Adocumentcancontainzero,one,or
moreinterferencematrices.Theyarelocatedinthe"Interferencematrices"folderofthedocument.
GSMInterferenceMatrixFeatureobjectsareavailableindocumentsbasedontheGSMGPRSEDGEtemplate.
GSMInterferenceMatrixFeatureobjectsprovidethefollowingpropertiesandmethods:
Name
Description
Attributes
get_Source
Returnsthe"InterferenceMatrices"ChildFolderobject.
Type:ChildFolder
object
Access:Read
Load
Loadsaninterferencematrix.
CompleteScopeInfo
Completesscopeinformation.
get_Scope
Returnsthescopeoftheinterferencematrix.
Type:TabularData
object
Access:Read
get_Active
Returnstheinterferencematrixactivestate.
Type:Boolean
Access:Read/Write
put_Active
Setstheinterferencematrixactivestate.
Type:Boolean
Access:Read/Write
get_Type
Returnsthetypeoftheinterferencematrix.
Type:Integer
Access:Read/Write
put_Type
Setsthetypeoftheinterferencematrix.
Type:Integer
Access:Read/Write
get_BasedOnTraffic
Type:Boolean
Access:Read/Write
put_BasedOnTraffic
Type:Boolean
Access:Read/Write
get_Resolution
Returnstheresolutionoftheinterferencematrix
calculation.
Type:Integer
Access:Read/Write
put_Resolution
Setstheresolutionoftheinterferencematrixcalculation.
Type:Integer
Access:Read/Write
get_StdDev
Returnstheinterferencematrixstandarddeviation.
Type:Single
Access:Read/Write
put_StdDev
Setstheinterferencematrixstandarddeviation.
Type:Single
Access:Read/Write
get_InfoQuantityIndicator
Returnstheinterferencematrixinformationquantity
indicator.
Type:Integer
Access:Read/Write
put_InfoQuantityIndicator
Setstheinterferencematrixinformationquantity
indicator.
Type:Integer
Access:Read/Write
get_CdfTab
ReturnstheinterferencematrixCDFtabulardata.
Type:TabularData
object
Access:Read
12.8.1 HowtoAccessGSMInterferenceMatrixFeatureObjects
TheObjectKindpropertyforanInterferenceMatrixChildFolderobjectsis:
{5144E1F9-E539-4F8C-BC0C-49A11C6389E8}
InterferenceMatrixChildFolderobjectsarechildrenofthefoldernamed"InterferenceMatrices".
177
Atoll3.2.1TaskAutomationGuide
Chapter12:ChildFolderFeatureObjects
Forsk2014
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
Returnsthe"InterferenceMatrices"ChildFolderobject.
12.8.3 Load
Loadsaninterferencematrix.
HRESULT Load();
Remarks
Thismethodmustbecalledbeforeanyaccesstoaninterferencematrix.
12.8.4 CompleteScopeInfo
Completesscopeinformation.
HRESULT CompleteScopeInfo();
Remarks
Thismethodmustbecalledaftertransmittersareaddedtothescope.
12.8.5 get_Scope
Returnsthescopeoftheinterferencematrix.
HRESULT get_Scope(ITabularData **ppTable);
Parameters
[out]ppTable:TheaddressoftheITabularDatainterfacepointerusedtoreturnthescopeoftheinterferencematrix.
Remarks
ThescopeofaninterferencematrixisaTabularDataobjectcontainingamappingfromtherowidentifierforatransmitter
tothefollowinginformation:
Thecoveragepercentageasvictim,andasinterferer.Thedefaultvaluesare100.
TheBSICandBCCHwhentheinterferencematrixinformationwascollected.Thedefaultvaluesare1.
178
Atoll3.2.1TaskAutomationGuide
Chapter12:ChildFolderFeatureObjects
AT321_TAG_E1
12.8.6 put_Active
Setstheactivestate.
12.8.7 get_Active
Returnstheactivestate.
HRESULT get_Active(VARIANT_BOOL *pIsActiveVal);
Parameters
[out]pIsActiveVal:AddressoftheVARIANT_BOOLusedtoreturntheactivestateoftheinterferencematrix.
Remarks
Anactiveinterferencematrixisusedbytheautomaticfrequencyplanningprocesswhentheinterferencematrixscopeinter
sectstheautomaticfrequencyplanningscope.
12.8.8 get_Type
Returrnstheinterferencematrixtype.
HRESULT get_Type(IM_TYPE *pImTypeVal);
Parameters
[out]pImTypeVal:Addressoftheenumerationvalueusedtoreturntheinterferencematrixtype.
Remarks:
Availableenumerationvaluesusedtospecifyaninterferencematrixtypeare:
1:PROPAG_IM
Forinterferencematricesbasedonpropagationdata.Theirreliabilitydependsontheaccuracyandcorrectnessofnetwork
andgeogrpahicaldata.
2:OMC_RESELCTION_IM
ForinterferencematricesbasedonreselectionstatisticsfromtheOMC.Theirreliabilityisusuallylowduetothedifference
betweenthelocationswheremobilesareswitchedonandwheretheyareactuallyusedtoaccessthenetwork.
3:OMC_SIMPLE_HO_IM
Theirreliabilityisusuallylowduetothefactthatinterferenceismeasuredonlyamongexistingneighbours,whichmightnot
becorrectlyassigned.Thistypeofinterferencematrixishighlycorrelatedwiththeneighbourrelations.Itcanbeusedto
removeexcessiveneighbourconstraints.However,itcannotbeusedtocompleteanymissingneighbourinformation.Another
reasonforlowreliabilityisthatinterferenceinformationiscollectedfromhandoverregionsonly,insteadoffromtheservice
area.
4:OMC_NEI_EXT_HO_IM
InterferencematricesbasedonRXLEVstatisticsfromtheOMC(neighbours,aswellastemporaryneighbours).
Theycanbeaverygoodsourceofinterferenceinformationiftheyarestatisticallystablebecausetheyarenotsensitiveto
dataerrors.Ontheotherhand,theyhavemanydisadvantages,suchas:
179
Atoll3.2.1TaskAutomationGuide
Chapter12:ChildFolderFeatureObjects
Forsk2014
TransmitterswiththesameBSICandBCCHcannotbedifferentiated.
TransmittershavingthesameBCCHwillneverhaveaninterferenceentry.
Informationislostwhenmorethan6interferersexistatanylocation.
IfmanyinterfererssharethesameBCCH,theyincreaseeachothersinterferencelevels.
HCSlayerscancauseproblemsbecausetherearemoreserversatanypoint,macrolayerserversarestronger,oracorrection
marginmightbeintroducedforsomeequipment.
Thistypeofinterferencematrixcanbecreatedusinganextendedneighbourslist.
5:TEST_MOBILE_DATA_IM
Interferencematricesbasedontestmobiledata.
Reliabilitycanbelowbecauseusuallythetestmobiledatasamplingzoneandthetrafficmodelarenotrelated.Secondly,the
measurementsarecarriedoutforexistingneighboursonly.
6:CW_IM
InterferencematricesbasedonCWmeasurements.
Theirreliabilitycanbelowbecausethemeasurementsusuallydonotreflectthetrafficmodel.However,thissourceofinfor
mationcanbeveryreliableforasubsetoftransmittersthatwereproperlyscanned.CarryingoutCWmeasurementsisexpen
sivewhichmeansthatthecollectedinformationisoftenpartialoroutofdate.
7:SCAN_DATA_IM
Interferencematricesbasedonscandatadrivetests.
Theyarehighlyreliableandanexcellentsourceofinformation,butarenotusefulinaradioplanningtoolbecausenoinfor
mationisavailabletomaptransmitterstothereceivedsignalsatanypixel.
8:UPPER_BOUND_ENTRY_COLLECTION
Upperboundinterferencematrix.
Thesourceofthistypeofinterferencematrixisnotdefined.Itcanbebasedonuserexperience.Theinformationcontained
inthisinterferencematrixisusedasanupperlimit,i.e.,ifthisinterferencematrixindicatesacertainlevelofinterference,it
shouldnotbeexceededbecauseotherinterferencematricesshowhigherinterference.Ifanupperboundinterferencematrix
doesnotcontaininformationaboutanentry,itisignored.
9:LOWER_BOUND_ENTRY_COLLECTION
Lowerboundinterferencematrix.
Thesourceofthistypeofinterferencematrixisnotdefined.Itcanbebasedonuserexperience.Theinformationcontained
inthisinterferencematrixisusedasalowerlimit.Thistypeofinterferencematrixcanbeveryusefulbecauseyoucanedit
entriesinthisinterferencematrix,andbecertainthattheinterferencewillbeatleastashighasthevalueyouentered.This
approachcanbeusedwhenuserexperienceshowsacertainlevelofinterferencewhichtheradionetworkplanningtoolis
unabletocalculate.
12.8.9 put_Type
Setstheinterferencematrixtype.
HRESULT put_Type(IM_TYPE imTypeVal);
Parameters
[in]imTypeVal:Theenumerationvalueusedtospecifytheinterferencematrixtype.
12.8.10 get_BasedOnTraffic
Returnsbasedontraffic.
HRESULT get_BasedOnTraffic(VARIANT_BOOL *pbBasedOntraf) ;
Parameters
[out]pbBasedOntraf:TheaddressoftheVARIANT_BOOLvalueusedtoreturnbasedontraffic.
180
Atoll3.2.1TaskAutomationGuide
Chapter12:ChildFolderFeatureObjects
AT321_TAG_E1
Remark
ThismethodonlymakessenseforinterferencematricesoftypePROPAG_IM.Inthatcase,thereturnvalueindicateswhether
theinterferencematrixtakesintoaccountnonuniformtrafficdistributionswithineachcell.
12.8.11 put_BasedOnTraffic
Setsbasedontraffic.
HRESULT put_BasedOnTraffic(VARIANT_BOOL bBasedOntraf) ;
Parameters
[in]bBasedOntraf:TheVARIANT_BOOLvalueusedtospecifybasedontraffic.
12.8.12 get_Resolution
Returnstheresolutionoftheinterferencematrixcalculation.
HRESULT get_Resolution(long *piResolutionParamVal);
Parameters
[out]piResolutionParamVal:Theaddressofthelongintegerusedtoreturntheresolutionoftheinterferencematrixcalcula
tion.
Remarks
ForinterferencematricesoftypePROPAG_IM,thereturnvalueistheresolutionoftheinterferencematrixcalculation.
ForinterferencematricesoftypeTEST_MOBILE_DATA_IM,CW_IM,orSCAN_DATA_IM,thereturnvalueisthenumberof
measurementspercalculationpointintheinterferencematrix.
12.8.13 put_Resolution
Setstheresolutionoftheinterferencematrixcalculation.
HRESULT put_Resolution(long iResolutionParamVal) ;
Parameters
[in]:iResolutionParamVal:Thelongintegerusedtospecifytheresolutionoftheinterferencematrixcalculation.
12.8.14 get_StdDev
Returnstheinterferencematrixstandarddeviation.
HRESULT get_StdDev(float *pfStdDevParamVal);
Parameters
[out]pfStdDevParamVal:Addressofthesingleprecisionfloatingpointvalueusedtoreturntheinterferencematrixstandard
deviation.
Remarks
ForinterferencematricesoftypePROPAG_IM,thereturnvalueisthestandarddeviationofthepropagationmodelusedin
theinterferencematrixcalculation.
ForinterferencematricesoftypeTEST_MOBILE_DATA_IM,CW_IM,orSCAN_DATA_IM,thereturnvalueisthestandarddevi
ationofthemeasurementequipment.
181
Atoll3.2.1TaskAutomationGuide
Chapter12:ChildFolderFeatureObjects
Forsk2014
12.8.15 put_StdDev
Setstheinterferencematrixstandarddeviation.
HRESULT put_StdDev(float fStdDevParamVal);
Parameters
[in]fStdDevParamVal:Thesingleprecisionfloatingpointvalueusedtospecifytheinterferencematrixstandarddeviation.
12.8.16 get_InfoQuantityIndicator
Returnstheinformationquantityindicator.
HRESULT get_InfoQuantityIndicator(long *piInfoQuantIndic);
Parameters
[out]pilInfoQuantIndic:Addressofthelongintegerusedtoreturntheinformationquantityindicator.
Remarks
ForinterferencematricesoftypePROPAG_IM,thereturnvalueisaninformationabouttheinterferencematrixcalculation
parameters.
ForinterferencematricesoftypeTEST_MOBILE_DATA_IM,CW_IM,orSCAN_DATA_IM,thereturnvalueisthenumberof
calculationpointspervictim.
ForinterferencematricesoftypeOMC_RESELCTION_IM,OMC_SIMPLE_HO_IM,orOMC_NEI_EXT_HO_IM,thereturnvalue
isthenumberofdayssincetheOMCstatisticswerecollected.
12.8.17 put_InfoQuantityIndicator
Setstheinformationquantityindicator.
HRESULT put_InfoQuantityIndicator(long iInfoQuantIndic) ;
Parameters
[in]ilInfoQuantIndic:Thelongintegerusedtospecifytheinformationquantityindicator.
12.8.18 get_CdfTab
ReturnstheinterferencematrixCDFtabulardata.
HRESULT get_CdfTab(ITabularData **ppTable) ;
Parameters
[out]ppTable:AddressoftheITabularDatainterfacepointerusedtoreturntheinteferencematrixtabulardata.
Remarks
ThestructureoftheTabularDataobjectreturnedis:
Column1:Rowidentifierofthevictimtransmitter
Column2:Rowidentifieroftheinterferertransmitter
Column3:Amaximumlossvalue
Column4:
AsafearrayoftypeVT_ARRAY|VT_R4,VT_ARRAY|VT_R8,orVT_VARIANThaving1dimensionandcontainingtheC/Ivalues
oftheCDF.
182
Atoll3.2.1TaskAutomationGuide
Chapter12:ChildFolderFeatureObjects
AT321_TAG_E1
Column5:
AsafearrayoftypeVT_ARRAY|VT_R4,orVT_ARRAY|VT_R8,orVT_VARIANThaving1dimensionandcontainingtheproba
bilityvaluesoftheCDF.
Performanceconsiderations:
Whendeletingelements,trytoalwaysdeletethelastelementfirst.
Wheneditinganexistingelement,donotchangecolumns1,2,or3.
183
Atoll3.2.1TaskAutomationGuide
Chapter12:ChildFolderFeatureObjects
184
Forsk2014
Chapter13
DocumentCommands
Atoll3.2.1TaskAutomationGuide
186
Forsk2014
Atoll3.2.1TaskAutomationGuide
Chapter13:DocumentCommands
AT321_TAG_E1
13 DocumentCommands
TheAtollAPIenablesexecutingcommandsonAtolldocuments.
Commandsareinvokedbytheirnames,whichmustbeknowninadvance.
ThefollowingcommandsareavailableforallAtolldocuments:
Name
Description
Attributes
IMPORTXML
ThiscommandperformsthesametaskastheAtoll"File >Data
Exchange >XMLFileImport..."mainmenucommand.
Version: 2.7.1
EXPORTXML
ThiscommandperformsthesametaskastheAtoll"File >Data
Exchange >XMLFileExport..."mainmenucommand.
Version: 2.7.0
APPENDTABLECOLUMN
Thiscommandaddsanewcolumntoadatabasetable.This
commandisonlyavailableforAtolldocumentsthatarenot
connectedtodatabases.
Version: 2.8.0
Thefollowingcommandsareavailableforradionetworktechnologydocuments:
Name
Description
Attributes
CALCULATEPOINTS
ThiscommandreturnssignallevelsindBmforagivensetofpoints
andasetoftransmitters.
Version: 2.6.0
IMPORTTESTMOBILEDATA
ThiscommandimportsasetofdrivetestdatafilesintoanAtoll
document.
Version: 2.6.1
RUNNEIGHBOURALLOCATI
ON
PerformsneighbourallocationonaGSMnetwork.
Version: 2.6.1
RUNINTERTECHNOLOGYNE
IGHBOURALLOCATION
PerformsintertechnologyneighbourallocationonaGSMorUMTS
network.
Version: 2.6.1
RUNINTRACARRIERNEIGHB
OURALLOCATION
PerformsintracarrierneighbourallocationonaUMTSnetwork.
Version: 2.6.1
RUNINTERCARRIERNEIGHB
OURALLOCATION
PerformsintercarrierneighbourallocationonaUMTSnetwork.
Version: 2.6.1
CLONESTUDY
Thiscommandclonesacoverageprediction.
Version: 2.7.0
DUPLICATESTUDY
Thiscommandduplicatesacoverageprediction.
Version: 2.7.0
COMPARESTUDY
Thiscommandcomparestwocoveragepredictions.
Version: 2.7.0
CALCULATEEQUIPMENTLO
SSES
Thiscommandcalculatesequipmentlossesandnoisefigureforall
transmittersinthedocumenttransmittersfolder.
Version: 2.7.0
CALCULATEREPEATERS
Thiscommandcalculatespropagationlosses,azimuth,mechanical
tilt,orgainsforallrepeatersinthedocumenttransmittersfolder.
Version: 2.7.0
CALCULATEREMOTEANTEN
NAS
Thiscommandcalculatespropagationlosses,azimuth,mechanical
tilt,orgainsforallremoteantennasinthedocumenttransmitters
folder.
Version: 2.7.0
EXPORTACTIVESETANALYSI
S
Thiscommandexportstheactivesetanalysistotextfiles.
Version: 2.7.0
CALCULATEPOINTSECI0
ThiscommandreturnsEc/I0valuesindBforagivensetofpointsand
asetoftransmitters.
Version: 2.7.0
RUNALLCARRIERSALLOCATI
ON
PerformsallcarriersallocationonaTDSCDMAnetwork.
Version: 2.8.1
RUNMASTERCARRIERALLO
CATION
PerformsmastercarrierallocationonaTDSCDMAnetwork.
Version: 2.8.1
187
Atoll3.2.1TaskAutomationGuide
Chapter13:DocumentCommands
Forsk2014
Name
Description
Attributes
MWRun
Thiscommandrunsanalysisforagivensetoflinks.
Version: 2.6.1
EXPORTMAPWINDOW
Exportsaregionofthemapwindowasanimage
Version: 3.1.0
IMPORTPLANETDATAFILE
Importsaplanetdatafile
Version: 3.1.0
EXPORTMWLINKANALYSISP
ROFILEPICTURE
ExportsamicrowavelinkanalysisprofilepicturetoaWindows
bitmapfile.
Version: 3.1.0
InputParameters
Commands may have input parameters. The types and names of input parameters are unique and are specific to each
command.PropertyContainerobjectsareusedtoholdinputparameters.
Results
Commandsmayreturnresults.Resultsarespecifictoeachcommand.TheresultsofacommandarereturnedusingaProper
tyContainerobject.Eachresulthasauniquenameandanassociatedtype.
13.1 HowtoInvokeaDocumentCommand
Thestepstoinvokeacommandarethesameforallcommands.
SamplescriptinvokinganAtolldocumentcommand:
13.2 IMPORTXML
ThiscommandperformsthesametaskastheAtoll"File >DataExchange >XMLFileImport..."mainmenucommand.
Version
2.7.1
InputParameters
Name
Description
Attributes
PATH
ThePATHinputparameterisusedtospecifythesourcefolder
containingXMLfilestoimport.
Version: 2.7.1
Type:String
DefaultParameters
None.GetCommandDefaultsonIDocument4interfaceforthecommandIMPORTXMLreturnsanemptyPropertyContainer
object.
Results
None.ThedataintheAtolldocumentareupdatedwiththecontentofXMLfiles.
188
Atoll3.2.1TaskAutomationGuide
Chapter13:DocumentCommands
AT321_TAG_E1
13.3 EXPORTXML
ThiscommandperformsthesametaskastheAtoll"File >DataExchange >XMLFileExport..."mainmenucommand.
Version
2.7.1
InputParameters
Name
Description
Attributes
PATH
ThePATHinputparameterisusedtospecifythedestinationfolder
whereXMLfileswillbeexported.
Version: 2.7.1
Type:String
DefaultParameters
None.GetCommandDefaultsforthecommandEXPORTXMLreturnsanemptyPropertyContainerobject.
Results
None.ThedataintheAtolldocumentareexportedtoasetofXMLfiles.
13.4 APPENDTABLECOLUMN
This command addsa newcolumnto a databasetable. This command isonlyavailableforAtoll documentsthatarenot
connectedtodatabases.
Version
2.8.0
InputParameters
Name
Description
Attributes
TABLE
TheTABLEinputparameterisusedtospecifyatablename.Thenew
columnwillbeaddedtothetablenamedTABLE.
Version: 2.8.0
Type:String
NAME
TheNAMEinputparameterisusedtospecifythedatabasenameof
thenewcolumntoaddtotheTABLEtable.Thevalueiscase
insensitiveandmustnotincludespacesanddotcharacters.
Version: 2.8.0
Type:String
LEGEND
TheLEGENDinputparameterisusedtospecifythedisplaynameof
thenewcolumntoaddtotheTABLEtable.Thevalueiscasesensitive
andspacescharactersareallowed.
Version: 2.8.0
Type:String
TYPE
TheTYPEinputparameterisusedtospecifythedatatypeofthenew
columntoaddtothetable.Validvaluesare:0=Text;1=Shortinteger;
2=Longinteger;3=Single;4=Double;5=True/False;6=Date/Time;
7=Currency;
Version: 2.8.0
Type:Integer
SIZE
TheSIZEinputparameterisusedtospecifythesize,inbytes,fora
columnoftype0(Text).TheSIZEinputparameterisspecifictothe
textdatatype.
Version: 2.8.0
Type:Integer
DEFAULT
TheDEFAULTinputparameterisusedtospecifythedefaultvalueof
thenewcolumn.Thedefaultvalueisthecolumnvaluefornewrows,
whenthecolumnvalueisnotsetexplicitly.WhentheDEFAULTinput
parameterisnotspecified,thedefaultvalueforthenewcolumnis
Null(VT_NULL).ThetypeoftheDEFAULTinputparametervalue
mustmatchthedatatypeofthenewcolumn,asspecifiedbythe
TYPEinputparameter.
Version: 2.8.0
Type:Null,String,
Integer,Boolean,
Single,Double,
Currency,orDate
GROUP
TheGROUPinputparameterisusedtospecifythenameofthegroup
thenewcolumnbelongsto.
Version: 2.8.0
Type:String
189
Atoll3.2.1TaskAutomationGuide
Chapter13:DocumentCommands
Forsk2014
Name
Description
Attributes
CHOICELIST
TheCHOICELISTinputparameterisusedtospecifythelistofpossible
valuesforanewcolumnoftype0(Text).TheCHOICELISTinput
parameterisspecifictotextcolumns.Pleasenotethattheactual
columnvalueisnotrestrictedtothevaluesdefinedinthechoicelist.
TheCHOICELISTparametermaybeusedbyAtolltodisplaypreferred
valuestotheuser,forinstanceinacomboboxcontrol.
Version: 2.8.0
Type:ArrayofStrings
DefaultParameters
TheTABLE,NAME,LEGEND,andTYPEinputparametershavenodefaultvalues,theymustbespecified.Defaultvaluesfor
otherinputparametersarereturnedbyGetCommandDefaultsforthecommandAPPENDTABLECOLUMN:
InputParameterName
DefaultValue
LEGEND
Empty.
SIZE
10bytes.
DEFAULT
Null
GROUP
Empty.
CHOICELIST
Empty.
Results
None.Uponsuccessfulcompletionthenewcolumnisaddedtothetable.
13.5 CALCULATEPOINTS
ThiscommandreturnssignallevelsindBmforagivensetofpointsandasetoftransmitters.
Pathlossmatrices,whethertheyarevalidornot,arenotused.ThereforetheCalculatePointscommandisnotdependenton
thepathlossmatricesresolution.Signallevelsarecalculatedusingthepropagationmodelofeachtransmitter.
Version
2.6.0
InputParameters
Name
Description
Attributes
POINTS
ThePOINTSinputparameterisusedtodefineasetofpoints.
Version: 2.6.1
Type:ArrayofIntegers
TRANSMITTERS
TheTRANSMITTERSinputparameterisusedtodefineasetof
transmitters.
Version: 2.6.1
Type:ArrayofStrings
TheTECHNOLOGYinputparameterisusedtospecifythetechnology
oftransmittersspecifiedbytheTRANSMITTERSinputparameter.
Availablevaluesare:
"GSM"
"UMTS"
"LTE"
"CDMA2000"
Version: 3.2.0
Type:String
TECHNOLOGY
ThisparameterisignoredforsingleRATdocuments.
ThePOINTSarraymusthave2dimensions,0and1.Thesizeofdimension0isthenumberofpoints.Thesizeofdimension1
is2,index0and1fordimension1aretheXandYcoordinates,respectively.Thecoordinatesofpointsareexpressedinthe
projectioncoordinatesystemoftheAtolldocument.
TheTRANSMITTERSarraymusthave1dimension.Thesizeofthearrayisthenumberoftransmitters.Arrayvaluesaretrans
mittersIDs,astheyappearintheTX_IDfieldoftheTransmitterstable
190
Atoll3.2.1TaskAutomationGuide
Chapter13:DocumentCommands
AT321_TAG_E1
DefaultParameters
None.GetCommandDefaultsforthecommandCALCULATEPOINTSreturnsanemptyPropertyContainerobject.
Results
Name
Description
Attributes
SIGNALS
TheSIGNALSresultisusedtoreturnsignalslevels.
Version: 2.6.1
Type:TabularData
object
TheSIGNALSTabularDataobjecthasonerecordforeachtransmitterbelongingtotheTRANSMITTERSinputparameter.The
rownumberngivesthesignalreceivedonthepointnumbern.TheSIGNALSTabularDataobjecthasthefollowingstructure:
ColumnName
Description
Attributes
TX_ID
Astringholdingatransmitteridentifier.
Type:String
Pn
Thesignallevelreceivedonpointnumbernfromthetransmitter
identifiedbythefieldTX_ID.
Whenthesignallevelislessthan200dBm,thetypeofthevariant
returnedforthefieldPnisVT_NULL.
Type:SingleorNull
13.6 IMPORTTESTMOBILEDATA
ThiscommandimportsasetofdrivetestdatafilesintoanAtolldocument.
Version
2.6.1
InputParameters
Name
Description
Attributes
NAME
NameoftheAtollExploreritemwherethedrivetestdatais
imported.
Version: 2.6.1
Type:String
RECEIVERHEIGHT
Receiverheight.
Version: 2.6.1
Type:Double
RECEIVERGAIN
Receivergain.
Version: 2.6.1
Type:Double
RECEIVERLOSSES
Receiverlosses.
Version: 2.6.1
Type:Double
MEASUREMENTUNIT
Measurementunit.Validvaluesare:0=dBm;1=dBV;2=dBV/m
Version: 2.6.1
Type:Integer
MEASUREMENTCSCODE
Codeofthecoordinatesystemusedformeasurementpointsinthe
drivetestdatatoimport.
ThecodeforacoordinatesystemisreportedintheAtollproperties
dialogueofthecoordinatesystem.
Version: 2.6.1
Type:Integer
CONFIGURATIONNAME
Atollconfigurationname,asreportedintheAtolldrivetestdata
importdialogue.
Beforeimportingdrivetestdata,adrivetestdataconfigurationhas
tobedefinedinAtoll.CONFIGURATIONNAMEisthenamegivento
thedrivetestdataconfiguration.
Version: 2.6.1
Type:String
FILES
TheFILESinputparameterisusedtodefinethesetoffilestoimport.
Eachfilemustbespecifiedusingitsabsolutepath.
Version: 2.6.1
Type:ArrayofStrings
191
Atoll3.2.1TaskAutomationGuide
Chapter13:DocumentCommands
Forsk2014
Name
Description
Attributes
Version: 3.2.0
CONFIGURATIONFILE
TheCONFIGURATIONFILEinputparameterisusedtospecifythefull
pathtotheinitializationfile(.ini)containingthe
CONFIGURATIONNAME.Thisparameterisoptional.Whenitisnot
specifiedtheconfigurationfileusedistheoneusedintheproject.
Type:String
DefaultParameters
None.GetCommandDefaultsforthecommandIMPORTTESTMOBILEDATAreturnsanemptyPropertyContainerobject.
Results
None.
13.7 RUNNEIGHBOURALLOCATION
PerformsneighbourallocationonaGSMnetwork.
Version
2.6.1
InputParameters
Name
Description
Attributes
TRANSMITTERFOLDER
Asubfolderofthetransmittersfolder,orthetransmittersfolder
itself.
Version: 2.6.1
Type:ChildFolder
object
DefaultParameters
None. GetCommandDefaults for the command RUNNEIGHBOURALLOCATION returns an empty PropertyContainer object.
TheneighbourallocationparametersusedtocomputeneighboursaretheonessetintotheAtolldocument.Theneigbour
allocationparameterscanbesetbyimportingauserconfigurationfilecontainingneighbourallocationparameters.Usethe
AtollDocumentobjectSetConfigmethodtoimporttheneighbourallocationparameters.
Results
Name
Description
Attributes
NEIGHBOURS
TheNEIGHBOURSresultisusedtoreturnneighbourrelations.
Version: 2.6.1
Type:TabularData
object
192
Description
Attributes
Transmitter
Type:String
Number
Type:Integer
Maximumnumber
Type:Integer
Neighbour
Type:String
Importance(%)
Type:Single
Cause
Type:String
Coverage(%)
Type:Single
Coverage(km)
Type:Single
Atoll3.2.1TaskAutomationGuide
Chapter13:DocumentCommands
AT321_TAG_E1
13.8 RUNINTERTECHNOLOGYNEIGHBOURALLOCATION
Performsintertechnologyneighbourallocation.
Version
2.6.1
InputParameters
Name
Description
Attributes
TRANSMITTERFOLDER
Asubfolderofatransmittersfolder,oratransmittersfolder
itself.
Version: 2.6.1
Type:ChildFolderobject
NeighbourTechnologyName
Astringusedtospecifythetechnologyofallocated
neighbours.
Availablevaluesare:
"GSM",
"UMTS",
"LTE"
Version: 3.1.0
Type:String
DefaultParameters
None.GetCommandDefaultsforthecommandRUNINTERTECHNOLOGYNEIGHBOURALLOCATIONreturnsanemptyProperty
Containerobject.TheneighbourallocationparametersusedtocalculateneighboursaretheonessetintheAtolldocument.
Theneigbourallocationparameterscanbesetbyimportingauserconfigurationfilecontainingneighbourallocationparam
eters.UsetheAtollDocumentobjectSetConfigmethodtoimporttheneighbourallocationparameters.
Results
Name
Description
Attributes
NEIGHBOURS
TheNEIGHBOURSresultisusedtoreturnneighbourrelations.
Version: 2.6.1
Type:TabularData
object
TheNEIGHBOURSTabularDataobjecthasonerecordforeachneighbourrelationbetweentwotransmittersbelongingto
TRANSMITTERFOLDER.
Name
Description
Attributes
Transmitter
Type:String
Number
Type:Integer
Maximumnumber
Type:Integer
Neighbour
Type:String
Cause
Type:String
Coverage(%)
Type:Single
Coverage(km)
Type:Single
Distance(m)
Type:Single
13.9 RUNINTRACARRIERNEIGHBOURALLOCATION
PerformsintracarrierneighbourallocationonaUMTSnetwork.
Version
2.6.1
193
Atoll3.2.1TaskAutomationGuide
Chapter13:DocumentCommands
Forsk2014
InputParameters
Name
Description
Attributes
TRANSMITTERFOLDER
Asubfolderofthetransmittersfolder,orthetransmittersfolder
itself.
Version: 2.6.1
Type:ChildFolder
object
DefaultParameters
None.GetCommandDefaultsforthecommandRUNINTRACARRIERNEIGHBOURALLOCATIONreturnsanemptyPropertyCon
tainerobject.TheneighbourallocationparametersusedtocalculateneighboursaretheonessetintheAtolldocument.The
neigbourallocationparameterscanbesetbyimportingauserconfigurationfilecontainingneighbourallocationparameters.
UsetheAtollDocumentobjectSetConfigmethodtoimporttheneighbourallocationparameters.
Results
Name
Description
Attributes
NEIGHBOURS
TheNEIGHBOURSresultisusedtoreturnneighbourrelations.
Version: 2.6.1
Type:TabularData
object
Description
Attributes
Cell
Type:String
Number
Type:Integer
Maximumnumber
Type:Integer
Neighbour
Type:String
Cause
Type:String
Coverage(%)
Type:Single
Coverage(km)
Type:Single
Distance(m)
Type:Single
13.10 RUNINTERCARRIERNEIGHBOURALLOCATION
PerformsintercarrierneighbourallocationonaUMTSnetwork.
Version
2.6.1
InputParameters
Name
Description
Attributes
TRANSMITTERFOLDER
Asubfolderofthetransmittersfolder,orthetransmittersfolder
itself.
Version: 2.6.1
Type:ChildFolder
object
DefaultParameters
None.GetCommandDefaultsforthecommandRUNINTERCARRIERNEIGHBOURALLOCATIONreturnsanemptyPropertyCon
tainerobject.TheneighbourallocationparametersusedtocomputeneighboursaretheonessetintotheAtolldocument.
Theneigbourallocationparameterscanbesetbyimportingauserconfigurationfilecontainingneighbourallocationparam
eters.UsetheAtollDocumentobjectSetConfigmethodtoimporttheneighbourallocationparameters.
194
Atoll3.2.1TaskAutomationGuide
Chapter13:DocumentCommands
AT321_TAG_E1
Results
Name
Description
Attributes
NEIGHBOURS
TheNEIGHBOURSresultisusedtoreturnneighbourrelations.
Version: 2.6.1
Type:TabularData
object
TheNEIGHBOURSTabularDataobjecthasonerecordforeachneighbourrelationbetweentwotransmittersbelongingto
TRANSMITTERFOLDER.
ColumnName
Description
Attributes
Cell
Cell
Type:String
Number
Type:Integer
Maximumnumber
Type:Integer
Neighbour
Type:String
Cause
Type:String
Coverage(%)
Type:Single
Coverage(km)
Type:Single
Distance(m)
Type:Single
13.11 CLONESTUDY
Thiscommandclonesacoverageprediction.
Version
2.7.0
InputParameters
Name
Description
Attributes
STUDY
TheSTUDYinputparameterholdsthestudytoclone.Thestudyto
cloneisastudyobjectcontainedinthePredictionsfolderoftheAtoll
document.
Version: 2.7.0
Type:ChildFolder
object
NEWSTUDYNAME
TheNEWSTUDYNAMEinputparameterisusedtodefinethenameof
thenewclonedstudy.
Version: 2.7.0
Type:String
DefaultParameters
None.GetCommandDefaultsforthecommandCLONESTUDYreturnsanemptyPropertyContainerobject.
Results
Name
Description
Attributes
NEWSTUDY
TheNEWSTUDYresultisusedtoreturnthenewcloned
studyobject.
Version: 2.7.0
Type:ChildFolderobject
13.12 DUPLICATESTUDY
Thiscommandduplicatesacoverageprediction.
195
Atoll3.2.1TaskAutomationGuide
Chapter13:DocumentCommands
Forsk2014
Version
2.7.0
InputParameters
Name
Description
Attributes
STUDY
TheSTUDYinputparameterholdsthestudytoduplicate.Thestudy
toduplicateisastudyobjectcontainedinthePredictionsfolderof
theAtolldocument.
Version: 2.7.0
Type:ChildFolder
object
NEWSTUDYNAME
TheNEWSTUDYNAMEinputparameterisusedtodefinethenameof
thenewduplicatedstudy.
Version: 2.7.0
Type:String
NEWSTUDYPARENT
TheNEWSTUDYPARENTinputparameterisusedtospecifyasub
folderofthePredictionsfolder.Thenewstudywillbecreatedinthe
NEWSTUDYPARENTsubfolderofthePredictionsfolder.
Thisparameterisoptional.Ifnotspecifiedthenewstudywillbe
createdattherootofthePredictionsfolder.
Version: 3.2.1
Type:ChildFolder
object
DefaultParameters
None.GetCommandDefaultsforthecommandDUPLICATESTUDYreturnsanemptyPropertyContainerobject.
Results
Name
Description
Attributes
NEWSTUDY
TheNEWSTUDYresultisusedtoreturnthenewduplicatedstudy
object.
Version: 2.7.0
Type:ChildFolder
object
13.13 COMPARESTUDY
Thiscommandcomparestwocoveragepredictions.
Version
2.7.0
InputParameters
Name
Description
Attributes
STUDY1
TheSTUDY1inputparameterholdsthefirststudyinvolvedinthe
comparison.ItisastudyobjectcontainedinthePredictionsfolderof
theAtolldocument.
Version: 2.7.0
Type:ChildFolder
object
STUDY2
TheSTUDY2inputparameterholdsthesecondstudyinvolvedinthe
comparison.ItisastudyobjectcontainedinthePredictionsfolderof
theAtolldocument.
Version: 2.7.0
Type:ChildFolder
object
NEWSTUDYNAME
TheNEWSTUDYNAMEinputparameterisusedtodefinethenameof
thecomparisonstudy.
Version: 2.7.0
Type:String
DefaultParameters
None.GetCommandDefaultsonIDocument4interfaceforthecommandCOMPARESTUDYreturnsanemptyPropertyCon
tainerobject.
196
Atoll3.2.1TaskAutomationGuide
Chapter13:DocumentCommands
AT321_TAG_E1
Results
Name
Description
Attributes
NEWSTUDY
TheNEWSTUDYresultisusedtoreturnthecomparisonstudyobject.
Version: 2.7.0
Type:ChildFolder
object
13.14 CALCULATEEQUIPMENTLOSSES
Thiscommandcalculatesequipmentlossesandnoisefigureforalltransmittersinadocumenttransmittersfolder.
Version
2.7.0
InputParameters
Name
Description
Attributes
TRANSMITTERFOLDER
Asubfolderofatransmittersfolder,oratransmittersfolderitself.
Version: 3.1.0
Type:ChildFolder
object
None.
DefaultParameters
None.GetCommandDefaultsforthecommandCALCULATEEQUIPMENTLOSSESreturnsanemptyPropertyContainerobject.
Results
None.Thefield"LOSSES"ofthe"TRANSMITTERS"tableisupdatedforalltransmittersinthedocumenttransmittersfolder.
Thiscommandisthesameasthe"Equipment|RecalculateLosses"orthe"Equipment|RecalculateLossesandNoiseFigure"
menuoptionavailableinAtollonthedocumenttransmittersfolder.
13.15 CALCULATEREPEATERS
Thiscommandcalculatespropagationlosses,azimuth,mechanicaltilt,orgainsforallrepeatersinadocumenttransmitters
folder.
Version
2.7.0
InputParameters
Name
Description
Attributes
PROPAGATIONLOSSES
ThePROPAGATIONLOSSESinputparameterisusedtospecify
whetherrepeatersdonorsidepropagationlosseswillbecalculated.
Version: 2.7.0
Type:Boolean
AZIMUTHSANDTILTS
TheAZIMUTHSANDTILTSinputparameterisusedtospecifywhether
repeatersdonorsideazimuthsandtiltswillbecalculated.
Version: 2.7.0
Type:Boolean
GAINS
TheGAINSinputparameterisusedtospecifywhetherrepeaters
gainswillbecalculated.
Version: 2.7.0
Type:Boolean
TRANSMITTERFOLDER
Asubfolderofatransmittersfolder,oratransmittersfolderitself.
Version: 3.1.0
Type:ChildFolder
object
197
Atoll3.2.1TaskAutomationGuide
Chapter13:DocumentCommands
Forsk2014
DefaultParameters
GetCommandDefaultsforthecommandCALCULATEREPEATERSreturnsaPropertyContainerobjectwiththeproperties:
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.
IfthePROPAGATIONLOSSESinputparameterissettoTrue,thenthecalculationtask"Repeaters|CalculateDonorSideProp
agationLosses"onthedocumenttransmittersfolderisperformed.
If the AZIMUTHSANDTILTS input parameter is set to True, then the calculation task "Repeaters | Calculate Donor Side
AzimuthsandTilts"onthedocumenttransmittersfolderisperformed.
IftheGAINSinputparameterissettoTrue,thenthecalculationtask"Repeaters|CalculateGains"onthedocumenttrans
mittersfolderisperformed.
13.16 CALCULATEREMOTEANTENNAS
Thiscommandcalculatespropagationlosses,azimuth,mechanicaltilt,orgainsforallremoteantennasinadocumenttrans
mittersfolder.
Version
2.7.0
InputParameters
Name
Description
Attributes
PROPAGATIONLOSSES
ThePROPAGATIONLOSSESinputparameterisusedtospecify
whetherremoteantennasdonorsidepropagationlosseswillbe
calculated.
Version: 2.7.0
Type:Boolean
AZIMUTHSANDTILTS
TheAZIMUTHSANDTILTSinputparameterisusedtospecifywhether
remoteantennasdonorsideazimuthsandtiltswillbecalculated.
Version: 2.7.0
Type:Boolean
GAINS
TheGAINSinputparameterisusedtospecifywhetherremote
antennasgainswillbecalculated.
Version: 2.7.0
Type:Boolean
TRANSMITTERFOLDER
Asubfolderofatransmittersfolder,oratransmittersfolderitself.
Version: 3.1.0
Type:ChildFolder
object
DefaultParameters
GetCommandDefaultsforthecommandCALCULATEREMOTEANTENNASreturnsaPropertyContainerobjectwiththeproper
ties:
198
PropertyName
Type
Value
PROPAGATIONLOSSES
Boolean
True
AZIMUTHSANDTILTS
Boolean
True
GAINS
Boolean
True
Atoll3.2.1TaskAutomationGuide
Chapter13:DocumentCommands
AT321_TAG_E1
Results
None. The "TRANSMITTERS" table content and the "REPEATERS" table content are updated depending on the requested
calculation.
IfthePROPAGATIONLOSSESinputparameterissettoTrue,thenthecalculationtask"RemoteAntennas|CalculateDonor
SidePropagationLosses"onthedocumenttransmittersfolderisperformed.
IftheAZIMUTHSANDTILTSinputparameterissettoTrue,thenthecalculationtask"RemoteAntennas|CalculateDonorSide
AzimuthsandTilts"onthedocumenttransmittersfolderisperformed.
IftheGAINSinputparameterissettoTrue,thenthecalculationtask"RemoteAntennas|CalculateGains"onthedocument
transmittersfolderisperformed.
13.17 EXPORTACTIVESETANALYSIS
Thiscommandexportstheactivesetanalysistotextfiles.
Version
2.7.1
InputParameters
Input parameters include general parameters, simulation conditions (SIMULATIONCONDITIONS), shadowing and indoor
coverageconditions(CLUTTERCONDITIONS),andfilteringparameters(RECORDSETCONDITIONS).
Name
Description
Attributes
SIMULATIONCONDITIONS
TheSIMULATIONCONDITIONSPropertyContainerobjectusedhere
hasasubsetoftheSIMULATIONCONDITIONSpropertyofa"Pilot
QualityAnalysis(Ec/Io)"PredictionChildFolderObject.Thereforethe
SIMULATIONCONDITIONSpropertyofa"PilotQualityAnalysis(Ec/
Io)"PredictionChildFolderObjectcanbeuseddirectly,additional
contentinthisPropertyContainerobjectwillbeignored.
Version: 2.7.1
Type:
PropertyContainer
object
Version: 2.7.1
Type:
PropertyContainer
object
CLUTTERCONDITIONS
RECORDSETCONDITIONS
TheRECORDSETCONDITIONSPropertyContainerobjectusedhere
hasasubsetoftheRECORDSETCONDITIONSpropertyofaPrediction
ChildFolderObject.ThereforetheRECORDSETCONDITIONSproperty
ofaPredictionChildFolderObjectcanbeuseddirectly,additional
contentinthisPropertyContainerobjectwillbeignored.
Version: 2.7.1
Type:
PropertyContainer
object
Thegeneralparametersinclude:
Name
Description
Attributes
RESOLUTION
Theresolutioninmeterusedtoexporttheactivesetanalysis.
Version: 2.7.1
Type:Integer
DEPTH
Themaximumnumberofcellsintheactivesetanalysistoexportona
givenpoint.
Version: 2.7.1
Type:Integer
TEXTSEPARATOR
TheASCIIcodeofthecharacterusedasthefielddelimiterinthe
exportedtextfiles.
Version: 2.7.1
Type:Integer
EXPORTFULLPATH
Thefullpathofthefilewheretheactivesetisexported.
Version: 2.7.1
Type:String
SIMULATIONCONDITIONSinclude:
199
Atoll3.2.1TaskAutomationGuide
Chapter13:DocumentCommands
Forsk2014
Name
Description
Attributes
TERMINAL
Thenameoftheterminalusedtoexporttheactiveset.
Version: 2.7.1
Type:String
MOBILITY
Thenameofthemobilityusedtoexporttheactiveset.
Version: 2.7.1
Type:String
SERVICE
Thenameoftheserviceusedtoexporttheactiveset.
Version: 2.7.1
Type:String
CARRIER
Thecarriernumberusedtoexporttheactiveset.
Version: 2.7.1
Type:Integer
Name
Description
Attributes
SHADOWING
Whethertocalculateshadowingmarginsrelatedtothedefinedcell
edgecoverageprobabilityandthestandarddeviation(s)perclutter
classornot.WhensettoFalse,noshadowingeffectisconsidered.
Version: 2.7.1
Type:Boolean
INDOORCOVERAGE
Whethertodecreasethereceivedsignallevelatthereceiverofthe
indoorlossdefinedforthecorrespondingclutterclass(clutterclass
properties).
Version: 2.7.1
Type:Boolean
EDGECOVERAGEPROBABILI
TY
Avaluebetween0and100,expressinginpercentagevaluethe
requiredcoverageprobabilityatthecelledge.
Version: 2.7.1
Type:Single
CLUTTERCONDITIONSinclude:
RECORDSETCONDITIONSinclude:
Name
Description
Attributes
FILTER
"Filter"partoftherecordsetconditions,appliedtothetransmitters
table.
Version: 2.7.1
Type:String
DefaultParameters
PropertyName
DefaultValue
SIMULATIONCONDITIONS
ThesameastheSIMULATIONCONDITIONSpropertyofanew"Pilot
QualityAnalysis(Ec/Io)"prediction.
RECORDSETCONDITIONS
ThesameastheRECORDSETCONDITIONSpropertyofanew"Pilot
QualityAnalysis(Ec/Io)"prediction.
RESOLUTION
ThesameastheRESOLUTIONpropertyofanew"PilotQuality
Analysis(Ec/Io)"prediction.
DEPTH
3,iebydefaultthemaximumnumberofcellsoftheactiveset
analysisis3.
TEXTSEPARATOR
59,ietheASCIIcodeofthe;character.Fieldsintheexported
fileswillbeseparatedbythe;character.
Results
None.TheactivesetanalysisisexportedtothefilespecifiedbytheEXPORTFULLPATHinputparameter.
Theareaexportedisthecomputationzoneofthedocument.
Whentheareaonwichtheactivesetanalysishastobeexportedistoolarge,theexportissplittedintoseveraltextfiles.The
numberandthesizeofthesetextfilescannotbecontrolled.Thetextfilesarenumberedstartingfrom0.Forinstance,when
theEXPORTFULLPATHinputparameterissetto"c:\activeset.txt",thefollowingfilesmaybecreated:
c:\activeset0.txt
c:\activeset1.txt
c:\activeset2.txt
200
Atoll3.2.1TaskAutomationGuide
Chapter13:DocumentCommands
AT321_TAG_E1
TextFileFormat
Thetextfileinwhichtheactivesetanalysisisexportedhasaheader,followedbythedata.Thedataandtheheaderaresepa
ratedbyablankline.
Header
Theheaderismadeofseveral[key;value]records.Thereisone[key;value]headerrecordperlineintheexportfile:
type;[Technologyofthedocumentusedtoexporttheactiveset]
timestamp;[Dateandtimewhentheactivesethasbeenexported]
resolution;[Resolutioninmeterusedtoexporttheactiveset]
xmin;[MinimumXvalueoftherectangularareaforwhichtheactivesetisexported]
xmax;[MaximumXvalueoftherectangularareaforwhichtheactivesetisexported]
ymin;[MinimumYvalueoftherectangularareaforwhichtheactivesetisexported]
ymax;[MaximumYvalueoftherectangularareaforwhichtheactivesetisexported]
x_num_pixels;[NumberofpixelsoftheexportareaalongtheXaxis]
y_num_pixels;[NumberofpixelsoftheexportareaalongtheYaxis]
Data
Thedataformatismadeofonelineperpixel.Thelineformatforonepixelis:
X;Y;[Carrier;][Transmitter_1;Ec/I0;I0]...[Transmitter_n;Ec/I0;I0]
X:Xcoordinateofthepixel,inmeter
Y:Ycoordinateofthepixel,inmeter
Whentheactivesetisnotempty,itislistedthereafteronthesameline:
Carrier:Carrieroftheactiveset
Thereareatmostntransmittersintheactivesetanalysis,wherenistheDEPTHinputparameter.Transmitternames
arelistedalongwiththeEc/I0andI0value.
Transmitter_n:Nameofthetransmitter
Ec/I0:Ec/I0indB
I0:I0indB
Extractofanactivesetexportfile:
type;UMTS
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
201
Atoll3.2.1TaskAutomationGuide
Chapter13:DocumentCommands
Forsk2014
23300;-14200;
23350;-14200;
[...]
13.18 CALCULATEPOINTSECI0
ThiscommandreturnsEc/I0valuesindBforagivensetofpointsandasetoftransmitters.
Version
2.7.1
InputParameters
Name
Description
Attributes
POINTS
ThePOINTSinputparameterisusedtodefineasetofpoints.
Version: 2.7.1
Type:ArrayofIntegers
TRANSMITTERS
TheTRANSMITTERSinputparameterisusedtodefineasetof
transmitters.
Version: 2.7.1
Type:ArrayofStrings
STUDY
TheSTUDYinputparameterisusedtodefinetheparametersusedto
calculatetheEc/I0values.Itisastudyobjectcontainedinthe
PredictionsfolderoftheAtolldocument.TheSTUDYinput
parametermustbeastudyoftype"PilotQualityAnalysis(Ec/I0)".
Version: 2.7.1
Type:ChildFolder
object
ThePOINTSarraymusthave2dimensions,0and1.Thesizeofdimension0isthenumberofpoints.Thesizeofdimension1
is2,index0and1fordimension1aretheXandYcoordinates,respectively.Thepointscoordinatesareexpressedinthe
projectioncoordinatesystemoftheAtolldocument.
TheTRANSMITTERSarraymusthave1dimension.Thesizeofthearrayisthenumberoftransmitters.Arrayvaluesaretrans
mittersIDs,astheyappearintheTX_IDfieldoftheTransmitterstable.
DefaultParameters
None.GetCommandDefaultsontheIDocument4interfaceforthecommandCALCULATEPOINTSECI0returnsanemptyProp
ertyContainerobject.
Results
Name
Description
Attributes
VALUES
TheVALUESresultisusedtoreturnEc/I0values.
Version: 2.7.1
Type:TabularData
object
TheVALUEStabulardataobjecthasonerecordforeachtransmitterbelongingtotheTRANSMITTERSinputparameter.The
rownumberngivestheEc/I0valueonthepointnumbern.
ColumnName
Description
Attributes
TX_ID
Astringholdingatransmitteridentifier.
Type:String
Pn
TheEc/I0valueonpointnumbernfromthetransmitteridentifiedby
thefieldTX_ID.
Type:SingleorNull
13.19 RUNALLCARRIERSALLOCATION
PerformsallcarriersallocationonaTDSCDMAnetwork.
202
Atoll3.2.1TaskAutomationGuide
Chapter13:DocumentCommands
AT321_TAG_E1
Version
2.8.1
InputParameters
Name
Description
Attributes
TRANSMITTERFOLDER
Asubfolderofthetransmittersfolder,orthetransmittersfolder
itself.
Version: 2.8.1
Type:ChildFolder
object
CONFREQUENCYALLOCATI AbooleanvalueusedtospecifywhethertoperformCoNfrequency
ON
allocation(True)orDiffNfrequencyallocation(False).
Version: 2.8.1
Type:Boolean
Abooleanvalueusedtospecifywhethertheallocationresultswillbe
commitedinthedocument(True),ornot(False).
Version: 2.8.1
Type:Boolean
COMMITRESULTS
DefaultParameters
None.GetCommandDefaultsforthecommandRUNALLCARRIERSALLOCATIONreturnsanemptyPropertyContainerobject.
Results
Name
Description
Attributes
CARRIERS
TheCARRIERSresultisusedtoreturncarrierallocationinformation.
Version: 2.8.1
Type:TabularData
object
TheCARRIERSTabularDataobjecthasonerecordforeachtransmitterscarrierallocation.
Name
Description
Attributes
Transmitter
Type:String
Carriers
Type:Integer
MasterCarrier
Type:Integer
13.20 RUNMASTERCARRIERALLOCATION
PerformsmastercarrierallocationonaTDSCDMAnetwork.
Version
2.8.1
InputParameters
Name
Description
Attributes
TRANSMITTERFOLDER
Asubfolderofthetransmittersfolder,orthetransmittersfolder
itself.
Version: 2.8.1
Type:ChildFolder
object
DELETEEXISTINGALLOCATI
ON
Abooleanvalueusedtospecifywhethertodeletetheexisting
allocation(True),ornot(False).
Version: 2.8.1
Type:Boolean
COMMITRESULTS
Abooleanvalueusedtospecifywhethertheallocationresultswillbe
commitedinthedocument(True),ornot(False).
Version: 2.8.1
Type:Boolean
203
Atoll3.2.1TaskAutomationGuide
Chapter13:DocumentCommands
Forsk2014
DefaultParameters
None. GetCommandDefaults for the command RUNMASTERCARRIERALLOCATION returns an empty PropertyContainer
object.
Results
Name
Description
Attributes
CARRIERS
TheCARRIERSresultisusedtoreturncarrier
allocationinformation.
Version: 2.8.1
Type:TabularDataobject
TheCARRIERSTabularDataobjecthasonerecordforeachtransmitterscarrierallocation.
ColumnName
Description
Attributes
Transmitter
Type:String
MasterCarrier
Type:Integer
13.21 MWRun
Thiscommandrunsanalysisforagivensetoflinks.Theanalysiscantakeintoaccountinterferers.
Theresultsareprovidedinatabulardataformat.Thefieldsareallthecolumnsdisplayedwhenrunninglinkbudgetsorinter
ferencecalculationonawholelinksfolder.
Version
2.6.1
InputParameters
AlltheparametersthattheusercanprovideasinputthroughtheGUIcanbeprovidedtothiscommand.
204
Name
Description
Attributes
LINKS
Arraycontainingthenamesofthelinkstobecalculated.These
includethelinkswhicharefiltered,active,andinsidethefocuszone.
ThisisthesamelistwhichisusedbyAtollwhenrunningcalculation
ontheLinksfolder.
Version: 2.6.1
Type:ArrayofStrings
INTERFERENCE
Defineswhichpropagationmodelistobeusedforinterference.If
true,recommendationITU452isused.Iffalse,themodeldefinedin
thelinkspropertiesisused.
Version: 2.6.1
Type:Boolean
QUALITYMODEL
Defineswhichqualitymodelistobeusedforanalysis.Validvalues
are:0=ITURecommendation5305;1=ITURecommendation5308;
2=ITURecommendation53010;3=VigantsBarnettmethod;4=KQ
Factormethod;
Version: 2.6.1
Type:Integer
QUALITYOBJECTIVE0
QUALITYOBJECTIVE1
QUALITYOBJECTIVE2
QUALITYOBJECTIVE3
DefinesthepriorityofobjectivesthatAtollmustusedtofindthe
appropriatequalityobjective."QualityObjective0"containsthe
objectiveswhicharethehigherpriorityobjectives.
"QualityObjective3"containsthelowestpriorityobjectives.
Each"QualityObjectiveX"issettoaninterger:0="Asafunctionof
Rate";1=ITUTG821;2=ITUTG826;3=Customized;
Version: 2.6.1
Type:Integer
AvailabilityObjective0
AvailabilityObjective1
AvailabilityObjective2
AvailabilityObjective3
DefinesthepriorityofobjectivesthatAtollmustusedtofindthe
appropriateavailabilityobjective."AvailabilityObjective0"contains
theobjectiveswhicharethehigherpriorityobjectives."Q
AvailabilityObjective3"containsthelowestpriorityobjectives.
Each"AvailabilityObjectiveX"issettoaninterger:0="Asafunctionof
Rate";1=ITUTG821;2=ITUTG826;3=Customized;
Version: 2.6.1
Type:Integer
Atoll3.2.1TaskAutomationGuide
Chapter13:DocumentCommands
AT321_TAG_E1
Name
Description
Attributes
RainModel
Defineswhichrainmodelistobeusedforanalysis:0=ITU
Recommendation5305;1=ITURecommendation5308;2=ITU
Recommendation53010;3=Cranemethod;
Version: 2.6.1
Type:Integer
RBER
ResidualBER;usedbyRecommendationITU5308andaboveto
calculateperformanceparameters.Typicallyintherangefrom1010
to1013forthebitratesof2to155Mbit/s,respectively.
Version: 2.6.1
Type:Double
ALFA1
UsedbyRecommendationITU5308andabovetocalculate
performanceparameters.
10to30,numberoferrorsperburstfortheBERintherangefrom
103toBERSES
Version: 2.6.1
Type:Integer
ALFA2
UsedbyRecommendationITU5308andabovetocalculate
performanceparameters.
1to10,numberoferrorsperburstfortheBERintherangefrom
BERSEStoRBER
Version: 2.6.1
Type:Integer
RefDelayM
UsedbyRecommendationITU5308andabovetocalculate
predictionofoutageinunprotecteddigitalsystems.
RefDelayMisthereferencedelay(ns)usedtoobtainthesignature
forminimumphase.
Version: 2.6.1
Type:Single
RefDelayNM
UsedbyRecommendationITU5308andabovetocalculate
predictionofoutageinunprotecteddigitalsystems.
RefDelayNMisthereferencedelay(ns)usedtoobtainthesignature
fornonminimumphase.
Version: 2.6.1
Type:Single
EquipPercent
Thispercentisusedtocalculatetheavailabilityobjectivewhichwill
becomparedtotheoutageduetoequipmentfailures.
Itsvalueissupposedtobebetween0and100.
Version: 2.6.1
Type:Single
RainPercent
Thispercentisusedtocalculatetheavailabilityobjectivewhichwill
becomparedtotheavailabilityoutage.
Itsvalueissupposedtobebetween0and100.
Version: 2.6.1
Type:Single
kMoy
Definesthevalueoftheaverageearthcurvatureusedincalculation.
Version: 2.6.1
Type:Single
kMin
Definesthevalueofthesecondearthcurvatureusedtodisplaythe
ellipsoid.(notusedduringlinkbudgetsnorinterferences
calculation).
Version: 2.6.1
Type:Single
UseAtpc
OptionwhichdefinesifpowermustbereducedornotwiththeATPC
value.
Version: 2.6.1
Type:Boolean
Rec530Simple
Defineswhichmethodmustbeusedtocalculategeoclimatic
parameters(usedforquality).Forthesimpleone,Rec530Simple
mustbesettoTrue.
Version: 2.6.1
Type:Boolean
IgnoreXPD
BooleanwhichtellsifthecalculationoffadingduetoXPDmustbe
takenintoaccountornotinthetotalresult.
Version: 2.6.1
Type:Boolean
IgnorePR
Booleanwhichtellsifthecalculationoffadingduetoenhancements
mustbetakenintoaccountornotinthetotalresult.
Version: 2.6.1
Type:Boolean
OneBER
FlagwhichdefinesifthecalculationmustbedonefortheBER
definedinthelinksproperties(OneBER=0/False)orifthe
calculationmustbedonewiththesameBERsforallthelinks
(OneBER=1/True).
Version: 2.6.1
Type:Boolean
BER1
FirstvalueofBERwhichisusedwhenOneBER=1.
Version: 2.6.1
Type:Double
BER2
SecondvalueofBERwhichisusedwhenOneBER=1.
Notethatthisvalueisnotusedwhenrunningcalculationswiththis
API.UsingtheAPImeansthatcalculationsareonlydisplayedwith
BER1.
Version: 2.6.1
Type:Double
205
Atoll3.2.1TaskAutomationGuide
Chapter13:DocumentCommands
206
Forsk2014
Name
Description
Attributes
Rec838
DefineswhichreleaseofrecommendationITU838mustbeused:
0=Rec8381;1=Rec8383;
Version: 2.6.1
Type:Double
CALC_LINK_PORTS
Definestheexpectedresults:
"all"meansthatalltheportsofeachlinkarecalculatedand
displayedinthefinalresult.
"worst"meansthatthefinalresultwilldisplayonlytheworstport.
"selected"meansthatthefinalresultwilldisplaytheresultforthe
portdefinedintheportparameter.
Version: 2.6.1
Type:String
CALC_WITH_NOI
Definestheanalysisisalinkanalysiswithoutinterferers(links
budgets,CALC_WITH_NOI=True)oriftotalinterferencemustbe
takenintoaccount(CALC_WITH_NOI=False)
Besidestheinterestofhavingresultswithorwithoutinterference,
thereaderwillseefurtherinthisdocumentthatcalculationwithout
interferenceprovidesmoredetailedresultsonthelinkconfiguration
(sortofreportofthelinkproperties).
Version: 2.6.1
Type:Boolean
InterferenceDistanceMax
Definesthemaximumdistance(inmeters)tosearchpotential
interferers.
Version: 2.6.1
Type:Double
InterferenceDropMin
Definesthethresholdofdropmargin(indB)underwhichan
interferencelevelisnotaddedtothetotalresult.
Version: 2.6.1
Type:Double
InterferenceCalcGo
DefinesiftheA>>Bwaymustbecalculatedanddisplayedornotin
thefinalresult.Thisoptionconcernsnotonlyinterference
calculationbutalsolinksbudgets.
Version: 2.6.1
Type:Boolean
InterferenceCalcReturn
DefinesiftheB>>Awaymustbecalculatedanddisplayedornotin
thefinalresult.Thisoptionconcernsnotonlyinterference
calculationbutalsolinksbudgets.
Version: 2.6.1
Type:Boolean
InterferenceCalcUplink
Definesiftheuplinkinterferencemustbecalculatedanddisplayed
ornotinthefinalresult.
Version: 2.6.1
Type:Boolean
InterferenceCalcDownlink
Definesifthedownlinkinterferencemustbecalculatedand
displayedornotinthefinalresult.
Version: 2.6.1
Type:Boolean
InterferenceRainSurfCorrel
ation
Valueofthearea(km2)whichisusedtocalculatethecorrelation
betweentwolinks.
Version: 2.6.1
Type:Single
InterferenceAutoWeight
Percentwhichdefinesifinterfererlevelismoreimportantornot
thatinterferingeffects.Thispercentisonlyusedforsemiautomatic
channelallocationandhasnoinfluencewhenrunningcalculation
withthisAPI.
Version: 2.6.1
Type:Integer
InterferenceUseAtpc
Optionwhichdefinesifinterfererpowermustbereducedornot
withtheATPCvalue.
Version: 2.6.1
Type:Boolean
InterferenceWidth
Percentofthechannelswidthwhichcaninterfereorbeinterfered.
Version: 2.6.1
Type:Integer
InterferenceOverShoot
Flagwhichdefineshowpassiverepeatersaretakenintoaccount
whenrunninginterference:0=interferencethroughpassivearenot
takenintoaccount;1=linkswithpassiverepeatersmayalsointerfere
throughtheirownpassive;2=anysignalcaninterferethrougha
repeater.;
Version: 2.6.1
Type:Integer
INTERF_DETAIL
Definesifresultsmustcontaindetailsornot.
"none"meansnodetail
"uplink"meansonlyforuplinkresults
"downlink"meansonlyfordownlinkresults
"both"meansalways.
ThisparameterhasnoeffectwhenrunningcalculationwiththisAPI.
Version: 2.6.1
Type:String
COCHANNELONLY
WhenCOCHANNELONLYissettoTrue,INTERFERENCEWIDTHis
ignored.
Version: 2.8.1
Type:Boolean
Atoll3.2.1TaskAutomationGuide
Chapter13:DocumentCommands
AT321_TAG_E1
DefaultParameters
ThedefaultvalueslistedbelowarethedefaultvaluessetinAtoll.Ifthesehavebeenmodified,thenewdefaultvalueswillbe
usedinstead.
Name
DefaultValue
Links
Arrayoflinksname
Interference
False
QualityModel
QualityObjective0
QualityObjective1
QualityObjective2
QualityObjective3
AvailabilityObjective0
AvailabilityObjective1
AvailabilityObjective2
AvailabilityObjective3
RainMod
RBER
1e12
ALFA1
10
ALFA2
RefDelayM
6.3
RefDelayNM
6.3
EquipPercent
33
RainPercent
33
kMoy
1.33
kMin
NULL
UseAtpc
False
Rec530Simple
True
IgnoreXPD
True
IgnorePR
False
OneBER
BER1
1e3
BER2
1e6
Rec838
CALC_LINK_PORTS
"selected"
CALC_WITH_NOI
True
InterferenceDistanceMax
50000
InterferenceDropMin
0.3
InterferenceCalcGo
True
InterferenceCalcReturn
True
207
Atoll3.2.1TaskAutomationGuide
Chapter13:DocumentCommands
Forsk2014
Name
DefaultValue
InterferenceCalcUplink
True
InterferenceCalcDownlink
True
InterferenceRainSurfCorrelation
100
InterferenceAutoWeight
50
InterferenceUseAtpc
False
InterferenceWidth
250
InterferenceOverShoot
INTERF_DETAIL
"Both"
AnalysisResultsWithoutInterferenceCalculation
208
Name
Description
Attributes
LINKNAME
Name(primarykey)ofthelinkwhoseresultsaregiven.
Version: 2.6.1
Type:String
BAND
Name(primarykey)ofthefrequencybandofthelink.
Version: 2.6.1
Type:String
LENGTH
LengthofthelinkcalculatedalongtheGreatCircle(withlatitude,
longitudeandheights).
Thisvalueisdisplayedasreadonlyinthefirstpageoflinks
propertiesbutisnotsavedindatabase.
Version: 2.6.1
Type:Single
WAY
Wayofthelinkwhichisconcernedwiththisresult.
"AB"means"go"(=SiteAtowardSiteB)
"BA"means"return"(=SiteBtowardSiteA)
Version: 2.6.1
Type:String
SUBBAND
Name(primarykey)ofthesubbandofthelinkwiththesuffix"[]"or
"[+]"dependingonthehalfsubbandofthelink.
"[]"meanslowestpart
"[+]"meanshighestpart.
Canbenullifthelinkhasmanualfrequencies.
Version: 2.6.1
Type:String
CHANNEL
Thecalculatedchannelnumber.
Ifthelinkhasmanualfrequency,channelnumberis"1".
Version: 2.6.1
Type:String
POLAR
Stringwhichcontainseither"H"forhorizontalpolarization,either
"V"forverticalpolarization.
Thisvaluecanbedeterminedbythelinksproperties(ifnoportsare
defined)orbytheportsconfigurationifany.
Version: 2.6.1
Type:String
SITE_TX
Name(primarykey)ofthetransmittingsiteofthelinkbeing
calculated(siteAisthewayis"AB",siteBifthewayif"BA").
Version: 2.6.1
Type:String
ANT_TX
Name(primarykey)ofthetransmittingantennaofthelink.
(antennaAisthewayis"AB",antennaBifthewayif"BA").
Version: 2.6.1
Type:String
HEIGHT_TX
Valueoftheheightoftransmittingantenna(inmeters).
Version: 2.6.1
Type:Single
AZIMUTH_TX
Valueoftheazimuthofthetransmittingantenna.(indegrees).This
valueiscalculated,notdisplayedinthelinksproperties,norsavedin
database.Ittakesintoaccounttheantennamisalignmentandthe
directionofthereceiver.(latitude,longitudeandheight).
Version: 2.6.1
Type:Single
TILT_TX
Valueofthetiltofthetransmittingantenna.(indegrees).Thisvalue
iscalculated,notdisplayedinthelinksproperties,norsavedin
database.Ittakesintoaccounttheantennamisalignmentandthe
directionofthereceiver.(latitude,longitudeandheight).
Version: 2.6.1
Type:Single
Atoll3.2.1TaskAutomationGuide
Chapter13:DocumentCommands
AT321_TAG_E1
Name
Description
Attributes
ANTGAIN_TX
Valueofthegainofthetransmittingantenna(indB).Thisvalueis
displayedintheantennaproperties.
Version: 2.6.1
Type:Single
SITE_RX
Name(primarykey)ofthereceivingsiteofthelinkbeingcalculated
(siteBisthewayis"AB",siteAifthewayif"BA").
Version: 2.6.1
Type:String
ANT_RX
Name(primarykey)ofthereceivingantennaofthelink.(antennaB
isthewayis"AB",antennaAifthewayif"BA").
Version: 2.6.1
Type:String
HEIGHT_RX
Valueoftheheightofreceivingantenna(inmeters).
Version: 2.6.1
Type:Single
AZIMUTH_RX
Valueoftheazimuthofthereceivingantenna.(indegrees).This
valueiscalculated,notdisplayedinthelinksproperties,norsavedin
database.Ittakesintoaccounttheantennamisalignmentandthe
directionofthereceiver.(Latitude,longitudeandheight).
Version: 2.6.1
Type:Single
TILT_RX
Valueofthetiltofthereceivingantenna.(indegrees).Thisvalueis
calculated,notdisplayedinthelinksproperties,norsavedin
database.Ittakesintoaccounttheantennamisalignmentandthe
directionofthereceiver.(Latitude,longitudeandheight).
Version: 2.6.1
Type:Single
ANTGAIN_RX
Valueofthegainofthereceivingantenna(indB).Thisvalueis
displayedintheantennaproperties.
Version: 2.6.1
Type:Single
EQ_TX
Name(primarykey)ofthetransmittingequipment.(equipmentAis
thewayis"AB",equipmentBifthewayif"BA").
Version: 2.6.1
Type:String
POWER_NOM
Valueofthenominaltransmittedpower,usedifATPCisnottaken
intoaccount.
Version: 2.6.1
Type:Single
POWER_COORD
Valueofthecoordinatetransmittedpower,usedifATPCistaken
intoaccount.
Version: 2.6.1
Type:Single
SYS_CFG
Valuethesystemconfigurationoftheequipment.Stringformatted
as:
"n+m"wherenisanintegerwhichcorrespondstothemain
channelsnumber,and"m"anintergerwhichcorrespondstothestad
bychannelsnumber.Ex:"1+1","2+0"
Version: 2.6.1
Type:String
CAPA
Valuethecapacityoftheequipment.Stringisformattedwiththe
numberoftrunks(dependingonthedigitalhierarchy)andthetrunk
name.
Example:"E1"or"3xE1"or"2xSTM16"dependingforifthe
numberoftrunksismorethanoneornot.
Version: 2.6.1
Type:String
TX_LOSS
Valueofthetotallossesonthetransmitterside:Sharedlosses,
Connectionlosses,Shieldingfactor,portlosses(filter+attenuation),
waveguidelosses.
Version: 2.6.1
Type:Single
FSL
Valueofthefreespacelosscalculatedbetweentransmitterand
receiver.
Version: 2.6.1
Type:Single
LA
Valueoftheattenuationduetodryairabsorption.
Version: 2.6.1
Type:Single
LV
Valueoftheattenuationduetovaporabsorption.
Version: 2.6.1
Type:Single
LD
Valueofthetotaldiffractionthroughtheprofilebetweenthe
transmitterandthereceiver.
Version: 2.6.1
Type:Single
LVEG
Valueofthevegetationlossalongtheprofile.
Version: 2.6.1
Type:Single
LBS
Valueofthetroposphericlossalongtheprofile.
Version: 2.6.1
Type:Single
209
Atoll3.2.1TaskAutomationGuide
Chapter13:DocumentCommands
210
Forsk2014
Name
Description
Attributes
LTOT
Valueofthetotalpropagationlossalongtheprofile.(Remember
thatvegetationlossisneveradded).
Version: 2.6.1
Type:Single
EQ_RX
Name(primarykey)ofthereceivingequipment.(equipmentBisthe
wayis"AB",equipmentAifthewayif"BA").
Version: 2.6.1
Type:String
RX_LOSS
Valueofthetotallossesonthereceiverside:Sharedlosses,
Connectionlosses,Shieldingfactor,portlosses(filter+attenuation),
waveguidelosses.
Version: 2.6.1
Type:Single
RX_THRESOLD
Valueofthereceiverthreshold(dBm)definedasthesensitivityof
thereceiverfortheBER1value.
Version: 2.6.1
Type:Single
DECOUPLING
Valueofthetotaldecoupling(dB):lossesduecopolarpatternsof
therequestedpolarizationfortransmitterandreceiverantenna.
(Generallynullifantennasarealigned.)
Version: 2.6.1
Type:Single
XPD
Differencebetweenthecrosspolarvalueofthereceiverantenna
anditscopolarvalue(dB).
Version: 2.6.1
Type:Single
XPI
Differencebetweenthecrosspolarvalueofthetransmitterantenna
anditscopolarvalue(dB).
Version: 2.6.1
Type:Single
RX_LEVEL
Wantedsignallevel(dBm)Takesintoaccountthetransmitted
power,transmitterandreceiverlosses,totalpropagationlossesand
decoupling.
Version: 2.6.1
Type:Single
FADE_MARGIN
Calculatedfademargin(uniformmargin)whichtakesintoaccount
thereceivedsignalleveletthereceiverthreshold.
Version: 2.6.1
Type:String
PNS
Percentofoutageduetouniformfadings.
Version: 2.6.1
Type:Single
PS
Percentofoutageduetoselectivefadings.
Version: 2.6.1
Type:Single
pXPD
Percentofoutageduetocrosspolardiscriminationfadings.
Version: 2.6.1
Type:Single
PT
Percentofoutagewhichdeterminedthequalityofthelink(i.e
duringclearairconditions).
Version: 2.6.1
Type:Single
SESR
ProbabilityofSESRoutage.
Version: 2.6.1
Type:Single
BBER
ProbabilityofBBERoutage.
Version: 2.6.1
Type:Single
ESR
ProbabilityofESRoutage.
Version: 2.6.1
Type:Single
PR
Percentoffadingsduetoenhancements.
Version: 2.6.1
Type:Single
P0
Percentofmultipathoccurrence.
Version: 2.6.1
Type:Single
PP
Percentoffadingsduetorainfortheworstmonth.
Version: 2.6.1
Type:Single
PPA
Percentoffadingsduetorainforanaverageyear.
Version: 2.6.1
Type:Single
PXPD
Percentofrainfadingsduetocrosspolardiscrimination.
Version: 2.6.1
Type:Single
Atoll3.2.1TaskAutomationGuide
Chapter13:DocumentCommands
AT321_TAG_E1
Name
Description
Attributes
PPT
Totalpercentofunavailabilityforanaverageyear.
Version: 2.6.1
Type:Single
PFAILURES
Percentoffadingsduetoequipmentfailures.
Version: 2.6.1
Type:Single
RAIN_SESR
ProbabilityofrainSESRoutage.
Version: 2.6.1
Type:Single
RAIN_BBER
ProbabilityofrainBBERoutage.
Version: 2.6.1
Type:Single
RAIN_ESR
ProbabilityofRainESRoutage.
Version: 2.6.1
Type:Single
PASSIVE_GAIN
Totalgain(dB)ofthepassiverepeaters.
Version: 2.6.1
Type:Single
AFF_RAIN
Totalrainattenuation(dB)alongthepath.
Version: 2.6.1
Type:Single
SEC_M_Q
Totaltimeofoutageduringclearairfortheworstmonth.Valueis
formattedisunit(hour,mn,sec).Ex:"6sec","19mn27sec".
Version: 2.6.1
Type:String
OBJ_M_Q
Qualityobjectiveduringclearairfortheworstmonth.Valueis
formattedisunit(hour,mn,sec)
Version: 2.6.1
Type:String
SEC_Y_Q
Totaltimeofoutageduringclearairforanaverageyearmonth.
Valueisformattedisunit(hour,mn,sec)
Version: 2.6.1
Type:String
SEC_M_RAIN
Totaltimeofoutageduringrainconditionfortheworstmonth.
Valueisformattedisunit(hour,mn,sec).Ex:"6sec","19mn27sec"
Version: 2.6.1
Type:String
OBJ_M_RAIN
Qualityobjectiveduringrainconditionfortheworstmonth.Valueis
formattedisunit(hour,mn,sec)
Version: 2.6.1
Type:String
SEC_Y_RAIN
Totaltimeofoutageduringrainconditionforanaverageyear
month.Valueisformattedisunit(hour,mn,sec)
Version: 2.6.1
Type:String
STATUS_Q
Statusofthelinkforquality.Takesintoaccounteachprobabilityand
correspondingobjectiveforSESR,ESRandBBER,accordingtothe
equipmenthierarchytoo.
Thestatuscanhavefollowingvalues:"OK";"NotRespected";"Not
Calculated";"NotDefined";
Version: 2.6.1
Type:String
STATUS_A
Statusofthelinkforavalability.Takesintoaccounteachprobability
andcorrespondingobjectiveforSESR,ESRandBBER,accordingto
theequipmenthierarchytoo.
Thestatuscanhavefollowingvalues:"OK";"NotRespected";"Not
Calculated";"NotDefined";
Version: 2.6.1
Type:String
CFM
Valueofthecompositefademargin(dB)whichtakesintoaccountall
themargins;CorrespondstotheSESRprobability.
Version: 2.6.1
Type:String
REQ_CFM_Q
Valueofthecompositefademargin(dB)calculatedfromthequality
objectivessetforthelink.
Version: 2.6.1
Type:String
REQ_TFM
Valueoftheuniformmargin(dB)calculatedfromthequality
objectivessetforthelink.Correspondstothenonselectiveoutage
probability.
Version: 2.6.1
Type:String
REQ_CFM_A
Valueofthecompositefademargin(dB)calculatedfromthe
availabilitysetforthelink.
Version: 2.6.1
Type:String
TX_PORT
Transmissionport.
Version: 3.1.0
Type:String
211
Atoll3.2.1TaskAutomationGuide
Chapter13:DocumentCommands
Forsk2014
Name
Description
Attributes
RX_PORT
Receptionport.
Version: 3.1.0
Type:String
Name
Description
Attributes
LINKNAME
Name(primarykey)ofthelinkwhoseresultsaregiven.
Version: 2.6.1
Type:String
WAY
Wayofthelinkwhichisconcernedwiththisresult.
"AB"means"go"(=SiteAtowardSiteB)
"BA"means"return"(=SiteBtowardSiteA)
Version: 2.6.1
Type:String
CHANNEL_IRX
Calculatedinterferedchannelnumber.
Ifthelinkhasmanualfrequency,channelnumberis"1".
Version: 2.6.1
Type:String
SUBBAND
Name(primarykey)ofthesubbandofthelinkwiththesuffixe"[]"
or"[+]"dependingonthehalfsubbandofthelink.
"[]"meanslowestpart
"[+]"meanshighestpart.
Canbenullifthelinkhasmanualfrequencies.
Version: 2.6.1
Type:String
Wantedsignallevel(dBm)Takesintoaccountthetransmitted
power,transmitterandreceiverlosses,totalpropagationlossesand
decoupling.SamevalueasRX_LEVELwhenrunninganalysiswithout
interference.
Version: 2.6.1
Type:Single
FLAT_MARGIN
Valueoftheuniformmargin(dB)calculatedfromthewantedsignal
levelandthereceiverthreshold.
Version: 2.6.1
Type:Single
Aggregationofalltheinterferences(dBm)receivedfromotherlinks
andreceiverthermalnoise(FKTB).
Version: 2.6.1
Type:Single
MARGIN_REDUCT
Valueofthedifferencesbetweenmarginwithoutinterferenceand
marginwithinterferences.
Version: 2.6.1
Type:String
C_OVER_I
ValueofC/I(dB)whereCisthewantedsignallevelandIthetotal
interferencelevel.
Version: 2.6.1
Type:Single
IRAIN
Valueofthetotalinterferencelevelduringrainconditionwhichcan
bedifferentfromthe"general"interferenceleveldependingon
correlationbetweenlinks.
Version: 2.6.1
Type:Single
MARGIN_REDUCT_RAIN
Valueofthedifferencesbetweenmarginwithoutraininterference
andmarginwithinterferences.
Version: 2.6.1
Type:String
EFF_MARGIN
Valueofthemargincalculatedfromthereceiverthresholdandthe
receivedlevelwheninterferencearetakenintoaccount.
Version: 2.6.1
Type:Single
BER
ValueoftheBERwithwhichthecurrentanalysisisrun.
Version: 2.6.1
Type:Single
QUALITY
Percentofoutagewhichdeterminedthequalityofthelink.(i.e
duringclearairconditions,andwithinterference).
Version: 2.6.1
Type:Single
AVAIL
Percentoffadingsduetorainfortheworstmonth,when
interferencearetakenintoaccount.
Version: 2.6.1
Type:Single
SEC_M_Q
Totaltimeofoutagewithinterferenceduringclearairfortheworst
month.Valueisformattedisunit(hour,mn,sec).Ex:"6sec","19mn
27sec"
Version: 2.6.1
Type:String
OBJ_M_Q
Qualityobjectiveduringclearairfortheworstmonth.Valueis
formattedisunit(hour,mn,sec)
Version: 2.6.1
Type:String
AnalysisResultsWithInterferenceCalculation
212
Atoll3.2.1TaskAutomationGuide
Chapter13:DocumentCommands
AT321_TAG_E1
Name
Description
Attributes
SEC_Y_Q
Totaltimeofoutagewithinterferenceduringclearairforanaverage
yearmonth.Valueisformattedisunit(hour,mn,sec)
Version: 2.6.1
Type:String
SEC_M_RAIN
Totaltimeofoutagewithinterferenceduringrainconditionforthe
worstmonth.Valueisformattedisunit(hour,mn,sec).Ex:"6sec",
"19mn27sec"
Version: 2.6.1
Type:String
OBJ_M_RAIN
Qualityobjectiveduringrainconditionfortheworstmonth.Valueis
formattedisunit(hour,mn,sec)
Version: 2.6.1
Type:String
SEC_Y_RAIN
Totaltimeofoutagewithinterferenceduringrainconditionforan
averageyearmonth.Valueisformattedisunit(hour,mn,sec)
Version: 2.6.1
Type:String
STATUS_Q
Statusofthelinkforquality.Takesintoaccounteachprobabilityand
correspondingobjectiveforSESR,ESRandBBER,accordingtothe
equipmenthierarchytoo.
Thestatuscanhavefollowingvalues:"OK";"NotRespected";"Not
Calculated";"NotDefined";
Version: 2.6.1
Type:String
STATUS_A
Statusofthelinkforavalability.Takesintoaccounteachprobability
andcorrespondingobjectiveforSESR,ESRandBBER,accordingto
theequipmenthierarchytoo.
Thestatuscanhavefollowingvalues:"OK";"NotRespected";"Not
Calculated";"NotDefined";
Version: 2.6.1
Type:String
PORT_IRX
InterferencedPort
Version: 3.1.0
Type:Single
Name
Description
Attributes
REGION
Theregiontoexport.Availablevaluesare:
0:TheregiontoexportisspecifiedbySELECTIONXMIN,
SELECTIONXMAX,SELECTIONYMIN,andSELECTIONYMAXinput
parameters.
1:Theregiontoexportisthegeographicexportzone.
2:Theregiontoexportistheprintingzone.
Version: 3.1.0
Type:Integer
SELECTIONXMIN
Thewestcoordinateoftheregiontoexport,expressedinmeterin
theprojectioncoordinatesystemofthedocument.
OnlyusedwhentheREGIONinputparameterissetto0.
Version: 3.1.0
Type:Double
SELECTIONXMAX
Theeastcoordinateoftheregiontoexport,expressedinmeterin
theprojectioncoordinatesystemofthedocument.
OnlyusedwhentheREGIONinputparameterissetto0.
Version: 3.1.0
Type:Double
SELECTIONYMIN
Thesouthcoordinateoftheregiontoexport,expressedinmeterin
theprojectioncoordinatesystemofthedocument.
OnlyusedwhentheREGIONinputparameterissetto0.
Version: 3.1.0
Type:Double
SELECTIONYMAX
Thenorthcoordinateoftheregiontoexport,expressedinmeterin
theprojectioncoordinatesystemofthedocument.
OnlyusedwhentheREGIONinputparameterissetto0.
Version: 3.1.0
Type:Double
13.22 EXPORTMAPWINDOW
Exportsaregionofthemapwindowasanimage.
Version
3.1.0
InputParameters
213
Atoll3.2.1TaskAutomationGuide
Chapter13:DocumentCommands
Forsk2014
Name
Description
Attributes
PATH
Theabsolutepathofthefilewherethemapwindowimageis
exported.
Version: 3.1.0
Type:String
FORMAT
Thefileformatusedtoexportthemapwindowimage.Available
valuesare:
BMP:BMPfileformat
PNG:PNGfileformat
ARCVIEWGRIDASCII:ArcViewgridfileformat
TIF:TIFFfileformat
BIL:BILfileformat
JP2:JPEG2000fileformat
Version: 3.1.0
Type:String
PIXELSIZE
Pixelsize(meters),usedtoexportthemapwindowimage.
Whenthevaluespecifiediszero(0),thenSCALEandRESOLUTION
inputparametersareusedtodeterminethepixelsize.
Version: 2.8.1
Type:Integer
SCALE
Scaleofthemapwindowusedtoexportthemapwindowimage.
OnlyusedwhenthePIXELSIZEinputparameterissetto0.
Version: 3.1.0
Type:Integer
RESOLUTION
Resolutionofthemapwindowusedtoexportthemapwindow
image,indotperinch.
OnlyusedwhenthePIXELSIZEinputparameterissetto0.
Version: 3.1.0
Type:Integer
INCLUDERULERS
Booleanvalueusedtospecifywhethertoincluderulersinthe
exportedimage,ornot.
OnlyusedwhenthePIXELSIZEinputparameterissetto0.
Version: 3.1.0
Type:Boolean
INCLUDESCALE
Booleanvalueusedtospecifywhethertoincludethescaleinthe
exportedimage,ornot.
Version: 3.2.1
Type:Boolean
DefaultParameters
None.GetCommandDefaultsforthecommandEXPORTMAPWINDOWreturnsanemptyPropertyContainerobject.
Results
None.ThemapwindowimageisexportedtothefilespecifiedbythePATHinputparameter.
13.23 IMPORTPLANETDATAFILE
Importsaplanetdatafile.
Version
3.1.0
InputParameters
214
Name
Description
Attributes
PATH
Theabsolutepathoftheplanetdatafiletoimport.
Version: 3.1.0
Type:String
EMBED
Whethertoembeddata,ornot.
Version: 3.1.0
Type:Boolean
Atoll3.2.1TaskAutomationGuide
Chapter13:DocumentCommands
AT321_TAG_E1
Name
Description
Attributes
TYPE
Thetypeoftheplanetdatafiletoimport.
Availablevaluesare:
0:Digitalterrainmodel
1:Digitalheightmodel
2:Clutterclasses
3:Environmentbasedtrafficmap
4:Planetvectors
5:Planettextdata
6:Images
7:Antennas
8:Microwaveantennas
Version: 3.1.0
Type:Integer
DefaultParameters
None.GetCommandDefaultsforthecommandIMPORTPLANETDATAFILEreturnsanemptyPropertyContainerobject.
Results
None.Theplanetdataisimported.
13.24 EXPORTMWLINKANALYSISPROFILEPICTURE
ExportsamicrowavelinkanalysisprofilepicturetoaWindowsbitmapfile.
Version
3.1.0
InputParameters
Name
Description
Attributes
LINKNAME
Nameofthelink.
Version: 3.1.0
Type:String
LINKTYPE
Linktype.Availablevaluesare:
0:A>B
1:B>A
Version: 3.1.0
Type:Integer
PICTUREWIDTH
Picturewidth,inpixels.
Version: 3.1.0
Type:Integer
PICTUREHEIGHT
Pictureheight,inpixels.
Version: 3.1.0
Type:Integer
FILEPATH
TheabsolutepathoftheWindowsbitmapfilewherethelinkanalysis
pictureisexported.
Version: 3.1.0
Type:String
DefaultParameters
None.GetCommandDefaults for the command EXPORTMWLINKANALYSISPROFILEPICTURE returns an empty PropertyCon
tainerobject.
Results
None.ThepictureofthelinkprofileisexportedtothefilespecifiedbyFILEPATHinputparameter.
13.25 GETPOWERMODE
Retreivesthedocumentcurrentpowermode.
ThiscommandisonlyavailableforUMTSorLTEtechnologies.
215
Atoll3.2.1TaskAutomationGuide
Chapter13:DocumentCommands
Forsk2014
Version
3.1.0
InputParameters
Name
Description
Attributes
TECHNOLOGY
ForsingleRATdocuments,thisparameterisnotused.FormultiRAT
parameter,astringusedtospecifythetechnology.Availablevalues
are:
"UMTS",
"LTE"
Version: 3.1.0
Type:String
DefaultParameters
None.GetCommandDefaultsforthecommandGETPOWERMODEreturnsanemptyPropertyContainerobject.
Results
Name
Description
Attributes
POWERMODE
Thepowermode.Availablevaluesare:
0:default
1:EIRPiscalculatedusingthemaxpower
Version: 3.1.0
Type:Integer
13.26 SETPOWERMODE
Setsthedocumentpowermode.
ThiscommandisonlyavailableforUMTSorLTEtechnologies.
Version
3.1.0
InputParameters
Name
Description
Attributes
TECHNOLOGY
ForsingleRATdocuments,thisparameterisnotused.FormultiRAT
parameter,astringusedtospecifythetechnology.Availablevalues
are:
"UMTS",
"LTE"
Version: 3.1.0
Type:String
POWERMODE
Thepowermode.Availablevaluesare:
0:default
1:EIRPiscalculatedusingthemaxpower
Version: 3.1.0
Type:Integer
DefaultParameters
None.GetCommandDefaultsforthecommandSETPOWERMODEreturnsanemptyPropertyContainerobject.
Results
None.Thedocumentpowermodeischanged.
13.27 APPENDVECTORDATACOLUMN
Thiscommandaddsanewcolumntoavectordatatable.
Version
3.1.1
216
Atoll3.2.1TaskAutomationGuide
Chapter13:DocumentCommands
AT321_TAG_E1
InputParameters
Name
Description
Attributes
CHILDFOLDER
TheCHILDFOLDERinputparameterisusedtospecifyavectordata
table.TheChildFolderobjectspecifiedmustsupportthe
VECTORDATAproperty.
Version: 3.1.1
Type:ChildFolder
object
NAME
TheNAMEinputparameterisusedtospecifythenameofthenew
columntoaddtothevectordatatable.Thevalueiscaseinsensitive
andmustnotincludespacesanddotcharacters.
Version: 3.1.1
Type:String
LEGEND
TheLEGENDinputparameterisusedtospecifythedisplaynameof
thenewcolumntoaddtothevectordatatable.Thevalueiscase
sensitiveandspacecharactersareallowed.
Version: 3.1.1
Type:String
TYPE
TheTYPEinputparameterisusedtospecifythedatatypeofthenew
columntoaddtothevectordatatable.Validvaluesare:
0=Text
1=Shortinteger
2=Longinteger
3=Single
4=Double
5=True/False
6=Date/Time
7=Currency
Version: 3.1.1
Type:Integer
SIZE
TheSIZEinputparameterisusedtospecifythesize,inbytes,fora
columnoftype0(Text).
TheSIZEinputparameterisspecifictothetextdatatype.
Version: 3.1.1
Type:Integer
DEFAULT
TheDEFAULTinputparameterisusedtospecifythedefaultvalueof
thenewcolumn.Thedefaultvalueisthecolumnvaluefornewrows,
whenthecolumnvalueisnotsetexplicitly.WhentheDEFAULTinput
parameterisnotspecified,thedefaultvalueforthenewcolumnis
Null(VT_NULL).ThetypeoftheDEFAULTinputparametervalue
mustmatchthedatatypeofthenewcolumn,asspecifiedbythe
TYPEinputparameter.
Version: 3.1.1
Type:Null,String,
Integer,Boolean,
Single,Double,
Currency,orDate
CHOICELIST
TheCHOICELISTinputparameterisusedtospecifythelistofpossible
valuesforanewcolumnoftype0(Text).
TheCHOICELISTinputparameterisspecifictotextcolumns.
Pleasenotethattheactualcolumnvalueisnotrestrictedtothe
valuesdefinedinthechoicelist.TheCHOICELISTparametermaybe
usedbyAtolltodisplaypreferredvaluestotheuser,forinstanceina
comboboxcontrol.
Version: 3.1.1
Type:ArrayofStrings
DefaultParameters
None.
Results
None.Uponsuccessfulcompletionthenewcolumnisaddedtothetable.
13.28 LOADSAVEPRINTSETUP
Thiscommandloadsorsavestheprintsetupconfiguration.
Version
3.1.1
217
Atoll3.2.1TaskAutomationGuide
Chapter13:DocumentCommands
Forsk2014
InputParameters
Name
Description
Attributes
DIRECTION
TheDIRECTIONinputparameterisusedtospecifywhethertoloador
savetheprintsetupconfiguration.
Toloadtheprintsetupconfiguration,specifythevalue1.
Tosavetheprintsetupconfiguration,specifythevalue0.
Version: 3.1.1
Type:Integer
PRINTERNAME
ThePRINTERNAMEinputparameterisusedtospecifythedefault
printertouseintheprintsetupconfiguration.
Thisinputparameterisnotusedwhensavingtheprintsetup
configuration.
Version: 3.1.1
Type:String
CFGPATH
Whenloadingtheprintsetupconfiguration,theCFGPATHinput
parameterisusedtospecifythefileusedtoloadtheprintsetup
configuration.
Whensavingtheprintsetupconfiguration,theCFGPATHinput
parameterisusedtospecifythefileusedtosavetheprintsetup
configuration.
Version: 3.1.1
Type:String
DefaultParameters
None.
Results
Name
Description
Attributes
PRINTERNAME
ThePRINTERNAMEoutput
parameterisusedtoreturnthedefaultprinterused
inttheprintsetupconfigurationfile.
.
Version: 3.1.1
Type:String
13.29 CALCULATEPATHLOSS
Performspathlossmatrixcalculationonatransmitterfolder.
Version
3.2.0
InputParameters
Name
Description
Attributes
TRANSMITTERFOLDER
Asubfolderofthetransmittersfolder,orthetransmittersfolder
itself.
Version: 2.6.1
Type:ChildFolder
object
FORCECALCULATION
WhenTrue,thecalculationisforcedevenfortransmittershaving
availablevalidresults.When
False,thecalculationismadeonlyfortransmittershaving
unavailableorinvalidresults.
Version: 3.2.0
Type:Boolean
BLOCKING
Thebooleanvalueusedtospecifywhetherthecalculationswill
occurinthebackground
(False),orifthemethodshouldwaitforthecalculationstofinish
beforereturning(True).
Version: 3.2.0
Type:Boolean
FILTERED
WhenFalse,thecalculationismadeforallactivetransmittersinthe
transmitterfolder.WhenTrue,only
filteredtransmittersarecalculated
Version: 3.2.0
Type:Boolean
DefaultParameters
None.GetCommandDefaultsforthecommandCALCULATEPATHLOSSreturnsanemptyPropertyContainerobject.
218
Atoll3.2.1TaskAutomationGuide
Chapter13:DocumentCommands
AT321_TAG_E1
13.30 MWLinksCustomExport
Performsmicrowavelinkscustomexport.
Version
3.2.0
InputParameters
Name
Description
Attributes
EXPORTPATH
Fullpathtothefolderwherelinkreportsareexported.
Version: 2.6.1
Type:String
TEMPLATEFILEPATH
Fullpathtothecustomtemplateusedtoperformtheexport.
Version: 3.2.0
Type:String
LINKSFOLDER
Themicrowavelinksfoldercontaininglinkstoexporttothe
EXPORTPATHfolder,usingtheTEMPLATEFILEPATHcustom
template.
Version: 3.2.0
Type:ChildFolder
object
DefaultParameters
None.GetCommandDefaultsforthecommandMWLinksCustomExportreturnsanemptyPropertyContainerobject.
219
Atoll3.2.1TaskAutomationGuide
Chapter13:DocumentCommands
220
Forsk2014
Chapter14
Enumerations,
Structures,and
Interfaces
Atoll3.2.1TaskAutomationGuide
222
Forsk2014
Atoll3.2.1TaskAutomationGuide
Chapter14:Enumerations,Structures,andInterfaces
AT321_TAG_E1
14 Enumerations,Structures,andInterfaces
14.1 Enumerations
Enumerationsareusedtospecifyconstants.Twocategoriesofenumerationsaredefinedhereafter.
ThefirstcategoryreferstoallenumerationsdefinedintheAtolltypelibrary.AllofthemareprefixedwithAto.
ThesecondcategoryreferstoallenumerationsdefinedinFSKGISLiblibrary.Allofthemareprefixedwithfg.
14.1.1 AtollTypeLibraryEnumerations
14.1.1.1 AtoSaveStatus
Constant
Value
Description
atoSaveSucceeded
Documenthasbeensuccessfullysaved.
atoSaveCanceled
Changesinthedocumenthasbeencancelledbytheuser.
Constant
Value
Description
atoSaveNo
Documentisclosedwithoutbeingsaved.
atoSaveYes
Documentissavedbeforebeingclosed.
atoSavePrompt
Theuserispromptedwhetherthedocumentmustbesavedbefore
closed.
Constant
Value
Description
atoCancelChanges
Allchangesarecancelledbeforethedocumentisrefreshedfromthe
database.
atoSkipChanges
Onlyrefreshesdatathathavenotbeenmodified.
Constant
Value
Description
atoArchiveSaveSucceeded
Archivinghassucceededwithoutconflicts.
atoArchiveCanceled
Archivinghasbeencancelled,eitherbytheuserorbecauseconflicts
occurred.
Constant
Value
Description
atoMaximized
Maximized(enlargedtomaximumsize).
atoNormal
Normal(Default).
atoMinimized
Minimized(minimizedtoaniconinthetaskbar).
14.1.1.2 AtoSaveChanges
14.1.1.3 AtoRefreshPriority
14.1.1.4 AtoArchiveStatus
14.1.1.5 AtoWindowStatus
223
Atoll3.2.1TaskAutomationGuide
Chapter14:Enumerations,Structures,andInterfaces
Forsk2014
14.1.1.6 AtoLogType
Constant
Value
Description
atoInfo
Information.
atoError
Error.
atoWarning
Warning.
Constant
Value
Description
atoEQ
(Equal)ThefirstvalueequaltosearchValissearchedfor.
atoLT
(StrictlyLowerThan)ThefirstvaluelessthansearchValissearched
for.
atoLE
(LowerorEqual)ThefirstvaluelessthanorequaltosearchValis
searchedfor.
atoGE
(GreaterorEqual)ThefirstvaluegreaterthanorequaltosearchVal
issearchedfor.
atoGT
(StrictlyGreaterThan)ThefirstvaluegreaterthansearchValis
searchedfor.
atoNE
(NotEqual)ThefirstvaluenotequaltosearchValissearchedfor.
Constant
Value
Description
atoDbm
TransmissionunitisdBm.
atoWatt
TransmissionunitisWatt.
atoKWatt
TransmissionunitiskWatt.
Constant
Value
Description
atoDbmRx
ReceptionunitisdBm.
atoDbMicroVolt
ReceptionunitisdBV.
atoDbMicroVoltMeter
ReceptionunitisdBV/meter.
Constant
Value
Description
atoM
Distanceunitismeter.
atoKm
Distanceunitiskilometer.
atoMiles
Distanceunitismiles.
14.1.1.7 AtoCompareOp
14.1.1.8 AtoTransmissionUnit
14.1.1.9 AtoReceptionUnit
14.1.1.10 AtoDistanceUnit
224
Atoll3.2.1TaskAutomationGuide
Chapter14:Enumerations,Structures,andInterfaces
AT321_TAG_E1
14.1.1.11 AtoRadiatedPowerUnit
Constant
Value
Description
atoRadiatedPowerEIRP
RadiatedpowerisEIRP.
atoRadiatedPowerERP
RadiatedpowerisERP.
Constant
Value
Description
atoAntennaGainDbi
AntennagainunitisdBi.
atoAntennaGainDbd
AntennagainunitisdBd.
Constant
Value
Description
atoHeightOffsetM
Heightoffsetunitismeter.
atoHeightOffsetFeet
Heightoffsetunitisfeet.
Constant
Value
Description
atoData
Atollexplorerwindowdatatab.
atoGeo
Atollexplorerwindowgeotab.
atoModule
Atollexplorerwindowmodulestab.
atoParameters
Atollexplorerwindowparameterstab.
14.1.1.12 AtoAntennaGainUnit
14.1.1.13 AtoHeightOffsetUnit
14.1.1.14 AtoRootType
14.1.1.15 AtoRowFilter
Constantstofilteronlymodified,added,ordeletedrows.
Constant
Value
Description
atoRowFilterNone
Nofilter.
atoRowFilterModifiedOrNew
Filtertoretainonlymodifiedornewrows.
atoRowFilterDeleted
Filtertoretainonlydeletedrows.
Constant
Value
Description
atoRowStatusNew
Rowhasbeenadded.
atoRowStatusModified
Rowhasbeenmodified.
atoRowStatusDeleted
Rowhasbeendeleted.
atoRowStatusUnmodified
Rowisunmodified.
14.1.1.16 AtoRowStatus
Allpossiblerowstatuses.
225
Atoll3.2.1TaskAutomationGuide
Chapter14:Enumerations,Structures,andInterfaces
Forsk2014
14.1.1.17 AtoTemperatureUnit
Constant
Value
Description
atoTempCelcius
TemperatureunitisdegreeCelsius(C).
atoTempFarenheit
TemperatureunitisdegreeFarenheit(F).
14.1.2 FSKGISLibTypeLibraryEnumerations
14.1.2.1 GeographicUnit
Constant
Value
Description
fgUnspecifiedUnit
Valuewhennothinghasbeendefined.
fgMeter
Lengthunitismeter.
fgKilometer
Lengthunitiskilometre.
fgFoot
Lengthunitisfoot.
fgLink
fgChain
fgYard
Lengthunitisyard.
fgNauticalMile
Lengthunitisnauticalmile.
fgMile
Lengthunitismile.
fgRadian
100
Longitude/Latitudeunitsareradian.
fgDegree
101
Longitude/Latitudeunitsaredegree.
fgGrad
102
Longitude/Latitudeunitsaregrads.
fgArcMinute
103
Longitude/Latitudeunitsareminutes.
fgArcSecond
104
Longitude/Latitudeunitsareseconds.
Constant
Value
Description
fgUndefinedProjection
Valuewhennothinghasbeendefined.
fgNoProjection
Thissystemhasnoprojectionmethod.
fgLambertConfConic1SP
LambertConfConic1SP.
fgLambertConfConic2SP
LambertConfConic2SP.
fgMercator
Mercator.
fgCassiniSoldner
CassiniSoldner.
fgTransverseMercator
TransverseMercator.
fgTransvMercatorSouthOriented
TransverseMercatorSouthOriented.
fgObliqueStereographic
ObliqueStereographic.
fgNewZealandMapGrid
NewZealandMapGrid.
fgHotineObliqueMercator
10
HotineObliqueMercator.
fgLabordeObliqueMercator
11
LabordeObliqueMercator.
14.1.2.2 ProjectionMethod
226
Atoll3.2.1TaskAutomationGuide
Chapter14:Enumerations,Structures,andInterfaces
AT321_TAG_E1
Constant
Value
Description
fgSwissObliqueCylindrical
12
SwissObliqueCylindrical.
fgObliqueMercator
13
ObliqueMercator.
fgUTMProjection
14
UTMProjection.
Constant
Value
Description
fgUTMZoneNumber
NumberofUTMzone.
fgLongitudeOfOrigin
Longitudeoftheoriginofthezone.
fgLatitudeOfOrigin
Latitudeoftheoriginofthezone.
fgFalseEasting
False"easting".
fgFalseNorthing
False"northing".
fgScaleFactorAtOrigin
Scalingfactorattheorigin.
fgLatitudeOf1stParallel
Latitudeofthefirstparallel.
fgAzimuthOfCentralLine
Azimuthofthecentralline.
fgLatitudeOf2ndParallel
Latitudeofthesecondparallel.
fgAngleFromRecttifiedToSkewed
Grid
Constant
Value
Description
EXTRACT_DEFAULT
Allthegeographicdatapresentinthedocumentwillbeused.
Constant
Value
Description
PIXEL_POINT
Thevalueispointwiseandisassociatedwiththecentreofagrid
mesh(cornersofa4pointgrid).
PIXEL_AREA
Thevalueissurfaceareawiseandassociatedwithameshgrid.
Constant
Value
Description
POLAR_NONE
Nopolarizationorunknownpolarization.
POLAR_HORIZ
Horizontalpolarization.
POLAR_VERT
Verticalpolarization.
14.1.2.3 ProjParameterIndices
227
Atoll3.2.1TaskAutomationGuide
Chapter14:Enumerations,Structures,andInterfaces
228
Forsk2014
AT321_TAG_E1
Atoll3.2.1TaskAutomationGuide
229
HeadOffice
7ruedesBriquetiers
31700Blagnac,France
Tel:+33562747210
Fax:+33562747211
AT321_TAG_E1
USOffice
ChinaOffice
200SouthWackerDriveSuite3100
Chicago,IL60606,USA
Tel:+13126744800
Fax:+13126744847
Suite302,3/F,WestTower,JiaduCommercialBuilding,
No.66JianzhongRoad,TianheHiTechIndustrialZone,
Guangzhou,510665,P.R.ofChina
Tel:+862085538938 Fax:+862085538285
www.forsk.com
January2014