Returns true if the document is read-only, false otherwise.
Parameters
[out] pVal: Address of the VARIANT_BOOL used to return the read-only status of the document.
5.8 get_Saved
Returns false if the document contains unsaved changes, true otherwise.
Parameters
[out] pVal: Address of the VARIANT_BOOL used to return whether the document contains unsaved changes or not.
5.9 get_CoordSystemProjection
Returns the projection coordinate system of a document. HRESULT get_Name(BSTR *pVal);
HRESULT get_Path(BSTR *pVal);
HRESULT get_readOnly(VARIANT_BOOL *pVal);
Parameters
[out] ppVal: Address of the IDispCoordSystem interface pointer used to return the projection coordinate system of the docu- ment.
5.10 putref_CoordSystemProjection
Sets the projection coordinate system of a document.
Parameters
[in] pVal: Address of the IDispCoordSystem interface pointer used to set the projection coordinate system of the document.
5.11 get_CoordSystemDisplay
Returns the display coordinate system of a document.
Parameters
[out] ppVal: Address of the IDispCoordSystem interface pointer used to return the display coordinate system of the document.
5.12 putref_CoordSystemDisplay
Sets the display coordinate system of a document.
Parameters
[in] pVal: Address of the IDispCoordSystem interface pointer used to set the display coordinate system of the document.
5.13 get_CoordSystemInternal
Returns the internal coordinate system of a document.
Parameters
[out] ppVal: Address of the IDispCoordSystem interface pointer used to return the internal coordinate system of the docu- ment.
Remarks
When the document is not connected to a database, the internal coordinate system is the same as the display coordinate system. When the document is connected to a database, the internal coordinate system won’t change when the display coor- dinate system is changed. When the document is connected to a database, the internal coordinate system is the display coor- dinate system that was in use when the document was archived in the database for the first time.
The coordinates of sites are defined with the internal coordinate system.
HRESULT get_CoordSystemProjection(IDispCoordSystem **ppVal);
HRESULT putref_CoordSystemProjection(IDispCoordSystem *pVal);
HRESULT get_CoordSystemDisplay(IDispCoordSystem **ppVal);
HRESULT putref_CoordSystemDisplay(IDispCoordSystem *pVal);
Atoll 3.3.2 Task Automation Guide
Chapter 5: Document Object © 2016 Forsk. All Rights Reserved.
5.14 get_TransmissionUnit
Returns the transmission power unit.
Parameters
[out] pVal: Address of the AtoTransmissionUnit enumeration value used to return the transmission power unit.
5.15 put_TransmissionUnit
Sets the transmission power unit.
Parameters
[in] aNewVal: The AtoTransmissionUnit enumeration value used to specify the transmission power unit.
5.16 get_ReceptionUnit
Returns the signal level reception unit.
Parameters
[out] pVal: Address of the AtoReceptionUnit enumeration value used to return the signal level reception unit.
5.17 put_ReceptionUnit
Sets the signal level reception unit.
Parameters
[in] aNewVal: The AtoReceptionUnit enumeration value used to specify the signal level reception unit.
5.18 get_DistanceUnit
Returns the display distance unit.
Parameters
[out] pVal: Address of the AtoDistanceUnit enumeration value used to return the display distance unit.
5.19 put_DistanceUnit
Sets the display distance unit.
HRESULT get_TransmissionUnit(enum AtoTransmissionUnit *pVal);
HRESULT put_TransmissionUnit(enum AtoTransmissionUnit aNewVal);
HRESULT get_ReceptionUnit(enum AtoReceptionUnit *pVal);
HRESULT put_ReceptionUnit(enum AtoReceptionUnit aNewVal);
Parameters
[in] aNewVal: The AtoDistanceUnit enumeration value used to specify the display distance unit.
5.20 Close
Closes a document.
Parameters
[in] saveChanges: An AtoSaveChanges enumeration value. The values are:
[out] pStatus: Address of the AtoSaveStatus enumeration value. Returned values are:
5.21 FilePrint
Sends a document to a printer. The current print settings are used.
5.22 Save
Saves a document.
Parameters
[in] pVal: A BSTR used to specify where the document will be saved. When pVal is an empty string, the document is saved in place, the action performed is the same as the Atoll "File | Save" menu command. When pVal is the full path to an ATL file, then the action performed is the same as the Atoll "File | Save as..." menu command. When pVal is the full path to a Microsoft Access database file or when pVal is an Oracle database connection string, then the action performed is the same as the Atoll "File | Database | Export..." menu command.
5.23 Refresh
Refreshes the document from a database. The document must be connected to a database. HRESULT put_DistanceUnit(enum AtoDistanceUnit aNewVal);
HRESULT Close(enum AtoSaveChanges saveChanges, enum AtoSaveStatus *pStatus);
Constant Value Description
atoSaveNo 0 Document is closed without being saved.
atoSaveYes 1 Document is saved before being closed.
atoSavePrompt 2 The user is prompted whether the document must be saved before
closed.
Constant Value Description
atoSaveSucceeded 0 Document has been successfully saved.
atoSaveCanceled 1 Changes in the document has been cancelled by the user.
HRESULT FilePrint();
Atoll 3.3.2 Task Automation Guide
Chapter 5: Document Object © 2016 Forsk. All Rights Reserved.
Parameters
[in] aPriority: The AtoRefreshPriority enumeration value used to refresh the document from the database.
5.24 Archive
Archives the document in a database. The document must be connected to a database.
Parameters
[out] pStatus: Address of the AtoArchiveStatus used to return the result of the operation.
Remarks Atoll >= 2.7.0:
When the DisplayApplicationDialogue property of the document is set to true, the standard Atoll archive dialogue will be displayed, otherwise no dialogue is displayed and all changes are archived.
5.25 Run
Starts calculations.
Parameters
[in] aAll: The VARIANT_BOOL value used to specify whether all previous results must be deleted before the calculations starts (VARIANT_TRUE), or if only invalid pathloss matrices must be calculated (VARIANT_FALSE).
Remarks
1) When aAll is set to VARIANT_TRUE, the result is the same as the Atoll "Tools | Force calculation" menu command. When
aAll is set to VARIANT_FALSE, the result is the same as the Atoll "Tools | Calculate" menu command.
2) The method returns immediately and calculations occur in the background. 3) An error is returned when it is called on a Microwave Radio Links Atoll document. The WillRun application event is thrown by this method.
5.26 SetConfig
Loads a configuration file.
Parameters
[in] bstrFileName: The BSTR used to specify the full path of the configuration file to load.
Remarks
The configuration file is a .CFG file obtained using the Atoll "User Configuration | Export..." menu command. It may contain geographic configuration and folder configurations. Please see the Atoll Administrator Manual. The configurations in the document are replaced with the configurations contained in the .CFG file. If you simply want to add some geographic data to a document, you should rather use the Import method instead.
HRESULT Refresh(enum AtoRefreshPriority aPriority);
HRESULT Archive(enum AtoArchiveStatus *pStatus);
HRESULT Run(VARIANT_BOOL aAll);
5.27 Import
Loads a file containing geographic data.
Parameters
[in] fileName: A BSTR used to specify the full path of the file to load.
Remarks
The geographic file can be:
• An .CFG file. All data from its geographic section are loaded. Please see the Atoll Administrator Manual. • Any file format supported by Atoll (.BIL, .TIF, etc).
The geographic content of the imported file (.CFG, .GEO, .BIL, .TIF, etc.) is added to the current configuration of the geographic data in the document. The existing geographic configuration is not removed.
If you want to replace the geographic configuration of a document, you should use the SetConfig function instead.
5.28 GetRecords
Returns an Atoll Tabular Data Object for a requested category of records. n
Parameters
[in] bstrTableName: A BSTR used to specify the name of the table from which the records are requested.
[in] aAll: A VARIANT_BOOL. When it is set to VARIANT_TRUE, all the records of the table are returned. When it is set to VARIANT_FALSE and when there is an Atoll document folder associated with bstrTableName, the filter set on the document folder is used to filter the returned records. If no associated folder exists, this parameter is ignored.
[out] ppRecords: Address of the ITabularData interface pointer used to return the Atoll Tabular Data Object.
Remarks
The list of available table names defined by Atoll can be found in the template (.MDB) file. Please see the Administrator
Manual for the available table names. Some other table names are available:
• PREDICTIONS: to get pathloss matrices and signal level matrices. • ZONES: to get either the calculation zone or the focus zone.
Changes introduced in Atoll version 2.7.1 and above
1) Table "REPEATERS_VIEW"
When bstrTableName is equal to “REPEATERS_VIEW”, the TabularData object returned is a join on the "TRANSMITTERS" and the "REPEATERS" table. The fields returned will be the "TRANSMITTERS" table fields and the "REPEATERS" table fields, where
HRESULT Import(const BSTR fileName);
You must ensure that no inputs are requested from the user when importing the file (for instance the file type, georeferencement parameters, etc.) when the application is not visible. HRESULT GetRecords( const BSTR bstrTableName, VARIANT_BOOL aAll, ITabularData *ppRecords );
Atoll 3.3.2 Task Automation Guide
Chapter 5: Document Object © 2016 Forsk. All Rights Reserved.
prefixed with "TX_ID." whereas the names of the fields coming from the "TRANSMITTERS" table are left unchanged. When aAll is VARIANT_FALSE, then the filter set on the “Transmitters” folder of the Atoll document is used to filter the “REPEATERS_VIEW” table records, otherwise all repeaters or remote antennas are returned. A remote antenna is a repeater whith the field “EQUIPMENT_NAME” set to VT_NULL.
2) Table "REPEATERS"
When bstrTableName is equal to “REPEATERS”, and aAll is VARIANT_FALSE, then the filter set on the “Transmitters” folder of the Atoll document is used to filter the “REPEATERS” table records, otherwise all repeaters or remote antennas are returned. A remote antenna is a repeater whith the field “EQUIPMENT_NAME” set to VT_NULL.
Changes introduced in Atoll version 3.1.1 and above
1) Table "MWLinks"
When bstrTableName is equal to “MWLinks”, the TabularData object returned has an additional column named "_LINK_LENGTH", used to access the length of Microwave links as single precision floating point values.
Example
5.29 Redraw
Refreshes all items in the document.
Remarks
It has the same effect as the icon Refresh (F5) in Atoll.
5.30 CenterMapOn
Centres map on a parameter point.
Parameters
[in] ptx, [in] pty: Pointers to double precision floating point values used to specify the coordinates of the point to centres the map view on, expressed in meters, using the document projected coordinate system.
5.31 GetRootFolder
Returns the root Atoll Child Folder Object used to enumerate all Child Folder objects belonging to one tab of the Atoll explorer window.
Dim records
’ Returns the content of the SITES table
Set records = app.ActiveDocument.GetRecords("Sites", True)
’ Returns the content of the Sites folder, taking the folder filter into ac- count
Set records = app.ActiveDocument.GetRecords("Sites", False)
HRESULT Redraw();
HRESULT CenterMapOn(double* ptx, double* pty);
Parameters
[in] aType: The AtoRootType enumeration value used to specify the Atoll explorer window tab. There is one root ChildFolder object for each tab of the Atoll explorer window.
[out] ppItem: Address of the IChildFolder interface pointer used to return the root ChildFolder object.
Example
5.32 RunPathloss
Calculates the path loss matrices with no need for any predefined studies.
Parameters
[in] allTx: When VARIANT_TRUE, the calculation is made for all active transmitters in the table. When VARIANT_FALSE, only filtered transmitters are calculated.
[in] forced: When VARIANT_TRUE, the calculation is forced even for transmitters having available valid results. When VARIANT_FALSE, the calculation is made only for transmitters having unavailable or invalid results.
Remarks
1) This method corresponds to the menu commands "Calculations | Calculate Path Loss Matrices" and "Calculations | Force Path Loss Matrix Calculation" available in the Calculations sub-menu of the Transmitters folder.
2) The method returns immediately and the calculations occur in the background. 3) An error is returned when it is called on a Microwave Radio Links Atoll document.
How to detect the end of path loss matrices calculation?
To wait for the end of background path loss matrices calculation, please use the HasRunningTask document object method. While background calculations are running, HasRunningTask returns True. As soon as HasRunningTask returns False, you can assume that background calculations are finished:
5.33 GetService
Returns a scriptable Document Service Object.
Parameters
[in] bstrName: A BSTR used to specify the name of the service. Dim geo
const atoGeo = 1
’ Returns the root ChildFolder object of the Atoll explorer "Geo" tab Set geo = app.ActiveDocument.GetRootFolder(atoGeo)
HRESULT RunPathloss(VARIANT_BOOL allTx, VARIANT_BOOL forced);
'"Wait" Loop
Do While AtollDoc.HasRunningTask WScript.Sleep 1000
Loop
Atoll 3.3.2 Task Automation Guide
Chapter 5: Document Object © 2016 Forsk. All Rights Reserved.
The available values are:
"SIGNAL" : A Result File Provider object, implementing the IResultFileProvider interface. On documents based on the GSM GPRS EDGE template:
"AFP" : A GSM Frequency Plan Allocation object, implementing the IAfpLauncher interface. "AFP_IM" : A GSM Interference Matrices object, implementing the IAfpImLauncher interface.
[out] ppProvider: Address of the IDispatch interface pointer used to return the scriptable Document Service Object.
5.34 ExportConfig
Exports a subset of the current document configuration to a file.
Parameters
[in] bstrContent: A BSTR used to specify the configuration subset to export: • "GEO" : The "Geographic Data Set" configuration is exported.
• "GEO+ZONES" : The "Geographic Data Set" and "Computation and Focus Zones" configurations are exported. • "FULL" : All available configurations are exported.
Atoll 2.7.1 and above:
bstrContent is parsed according to the format "OPTION[+OPTION]". The set of specified options are exported to bstrFile. Avail-
able options are:
Atoll 3.1.0 and above:
[in] bstrFile: A BSTR used to specify the name of the export file.
5.35 GetCommandDefaults
Returns current default parameters specific to a command.
HRESULT ExportConfig(const BSTR bstrContent, const BSTR bstrFile);
OPTION name Description
GEO Geographic Data Set
ZONES Computation and Focus Zones
STUDIES Prediction List
OPTION name Description
FOLDERS Folder Configuration
MACROS Macros
AFP AFP Configuration
ANP Automatic Neighbour Allocation Parameters
MW Microwave Link Parameters
PNO Automatic PN Offset Allocation Parameters
SCP Automatic Scrambling Code Allocation Parameters
HRESULT GetCommandDefaults( const BSTR bstrCommandName,
Parameters
[in] bstrCommandName: A BSTR used to specify the command.
[out] ppParameters: Address of the IPropertyContainer interface pointer used to return the defaults parameters for the
bstrCommandName command.
5.36 InvokeCommand
Invokes a command.
Parameters
[in] bstrCommandName: A BSTR used to specify the command.
[in] pParameters: The IPropertyContainer interface pointer used to specify the Property Container object holding the param- eters needed to carry out the command.
• If set to NULL, default parameters for the command will be used. ppResults: Results of the command invokation.
• *ppResults will be set to NULL if the command has no results.
5.37 get_RadiatedPowerUnit
Returns the current radiated power unit.
Parameters
[out] pVal: Address of the AtoRadiatedPowerUnit enumeration value used to return the radiated power unit.
5.38 put_RadiatedPowerUnit
Sets the current radiated power unit.
Parameters
[in] aNewVal: The AtoRadiatedPowerUnit enumeration value used to specify the radiated power unit.
5.39 get_AntennaGainUnit
IPropertyContainer **ppParameters ); HRESULT InvokeCommand( const BSTR bstrCommandName, IPropertyContainer *pParameters, IPropertyContainer **ppResults );HRESULT get_RadiatedPowerUnit(enum AtoRadiatedPowerUnit *pVal);
Atoll 3.3.2 Task Automation Guide
Chapter 5: Document Object © 2016 Forsk. All Rights Reserved.
Parameters
[out] pVal: Address of the AtoAntennaGainUnit enumeration value used to return the antenna gain unit.
5.40 put_AntennaGainUnit
Sets the current antenna gain unit.
Parameters
[in] aNewVal: The AtoAntennaGainUnit enumeration value used to specify the antenna gain unit.
5.41 get_HeightOffsetUnit
Returns the current height offset unit.
Parameters
[out] pVal: Address of the AtoHeightOffsetUnit enumeration value used to return the height offset unit.
5.42 put_HeightOffsetUnit
Sets the current height offset unit.
Parameters
[in] aNewVal: The AtoHeightOffsetUnit enumeration value used to specify the height offset unit.
5.43 get_DatabaseConnectionString
Returns the database connection string.
Parameters
[out] pVal: Address of the BSTR used to return the database connection string.
Remarks
An error is returned when the document is not connected to a database.
5.44 HasRunningTask
Returns true when there is some calculation in progress.
HRESULT get_AntennaGainUnit(enum AtoAntennaGainUnit *pVal);
HRESULT put_AntennaGainUnit(enum AtoAntennaGainUnit aNewVal);
HRESULT get_HeightOffsetUnit(enum AtoHeightOffsetUnit *pVal);
HRESULT put_HeightOffsetUnit(enum AtoHeightOffsetUnit aNewVal);
HRESULT get_DatabaseConnectionString(BSTR *pVal);
Parameters
[out] pVal: Address of the VARIANT_BOOL used to return whether there is some calculation in progress or not.
Remarks
When some calculation is in progress, it is impossible to start new ones.
5.45 RunEx
Start calculations.
Parameters
[in] aAll: The VARIANT_BOOL value used to specify whether all previous results must be deleted before the calculations starts (VARIANT_TRUE), or if only invalid pathloss matrices must be calculated (VARIANT_FALSE).
[in] vBlocking: The VARIANT_BOOL value used to specify whether the calculations will occur in the background (VARIANT_FALSE), or if the method should wait for the calculations to finish before returning (VARIANT_TRUE).
Remarks
1) When aAll is set to VARIANT_TRUE, the result is the same as the Atoll "Tools | Force calculation" menu command. When
aAll is set to VARIANT_FALSE, the result is the same as the Atoll "Tools | Calculate" menu command.
2) An error is returned when it is called on a Microwave Radio Links Atoll document. The WillRun application event is thrown by this method.
When vbBlocking is set to VARIANT_TRUE, the RunComplete application event is thrown by this method before it returns.
5.46 get_DatabaseSchemaString
Returns the database schema string.
Parameters
[out] pVal: Address of the BSTR used to return the database schema string.
Remarks
An error is returned when the document is not connected.
The database schema string is returned using the exact same syntax described for the OpenFromDatabase method.