Returns the full path to the Atoll Initialisation File.
Parameters
[out] pVal: Address of the BSTR used to return the full path to the Atoll Initialisation File.
Remarks
The Atoll Initialisation File is usually named "Atoll.ini" and it is located in the directory where Atoll was installed.
Please note that for performance reasons, some options read from the Initialisation File by Atoll are cached for subsequent usage. After the path to the Initialisation File has been changed, and in order for some options to be used, it is necessary to quit Atoll and start it again. Therefore, it is recommended to change the full path to the Initialisation File as soon as the Atoll Application Object has been created.
Please refer to the Atoll Administrator Manual for the list of available options.
3.21 put_IniFileFullPath
Sets the full path to the Atoll Initialisation File.
Parameters
[in] bstrFile: A BSTR used to specify the full path to the Atoll Initialisation File.
Remarks
The Atoll Initialisation File is usually named "Atoll.ini" and it is located in the directory where Atoll was installed.
Please note that for performance reasons, some options read from the Initialisation File by Atoll are cached for subsequent usage. After the path to the Initialisation File has been changed, and in order for some options to be used, it is necessary to quit Atoll and start it again. Therefore, it is recommended to change the full path to the Initialisation File as soon as the Atoll Application Object has been created.
Please refer to the Atoll Administrator Manual for the list of available options.
3.22 GetOption
Returns an option read from the Atoll Initialisation File.
Parameters
[in] bstrSection: A BSTR used to specify the name of an Atoll Initialisation File section. [in] bstrOption: A BSTR used to specify the name of an Atoll Initialisation File option.
[out] pVal : Address of the VARIANT used to return the option value. The type of the VARIANT returned is VT_NULL when the option bstrOption is not found under the section bstrSection in the Initialisation File. The type of the returned VARIANT is VT_I4 when the option bstrOption is an integer, otherwise the type of the VARIANT returned is VT_BSTR. If bstrOption is left empty, pVal will be used to return the entire section whose name is specified in bstrSection.
HRESULT get_IniFileFullPath(BSTR *pVal);
HRESULT put_IniFileFullPath(BSTR bstrFile);
Remarks
Please refer to the Atoll Administrator Manual for the list of available sections and options.
3.23 SetOption
Sets an option in the Atoll Initialisation File.
Parameters
[in] bstrSection: A BSTR used to specify the name of an Atoll Initialisation File section. [in] bstrOption: A BSTR used to specify the name of an Atoll Initialisation File option. [in] varValue: A VARIANT used to specify the option value to write to the Initialisation File.
Remarks
The caller must have write access permission to the Initialisation File.
Please note that for performance reasons, some options read from the Initialisation File by Atoll are cached for subsequent usage. Therefore, it is recommended to set options as soon as the Atoll Application Object has been created.
Please refer to the Atoll Administrator Manual for the list of available sections and options.
3.24 Sleep
Suspends the application apartment execution.
Parameters
[in] lMilliseconds : A long integer used to specify the time, in milliseconds, to sleep.
Example
Remarks
Application events can still be processed while the application apartment execution is suspended.
Application Version
2.8.1
3.25 SetAddinInfoEx
Reserved for future use.
HRESULT SetOption(BSTR bstrSection, BSTR bstrOption, VARIANT varValue);
HRESULT Sleep(long lMilliseconds);
’Sleep 5 seconds Atoll.Sleep 5000 HRESULT SetAddinInfoEx( LONGLONG hInstance, LPDISPATCH dispatch, long idr, long cookie );
Atoll 3.3.2 Task Automation Guide
Chapter 3: Application Object © 2016 Forsk. All Rights Reserved.
Parameters
3.26 put_OLENotRespondingDialog
Enables or disables OLE not responding dialog.
Parameters
[in] newVal: A VARIANT_BOOL used to specify whether the OLE not responding dialog is enabled (VARIANT_TRUE), or disabled (VARIANT_FALSE).
3.27 put_OLEBusyDialog
Enables or disables OLE busy dialog.
Parameters
[in] newVal: A VARIANT_BOOL used to specify whether the OLE busy dialog is enabled (VARIANT_TRUE), or disabled (VARIANT_FALSE).
3.28 put_OLEMessagePendingDelay
Sets the OLE message pending delay.
Parameters
[in] newVal: A LONG integer used to specify the OLE message pending delay.
3.29 get_PID
Returns the Windows Process ID of the Atoll session.
Parameters
[out] pVal: Address of the long integer used to return the process ID of the Atoll session.
3.30 Application Events
Events related to the application are fired: • Before the application shuts down, • When a document has just been opened, • Before a document is closed,
• Before a document is saved, • When a document has been saved,
• When a new document has just been created, • Before a document is refreshed from database, • When a document has been refreshed from database, • Before a document is archived in database,
HRESULT put_OLENotRespondingDialog(VARIANT_BOOL newVal);
HRESULT put_OLEBusyDialog(VARIANT_BOOL newVal);
HRESULT put_OLEMessagePendingDelay(LONG newVal);
• When a document has been archived in database, • When a calculation is requested,
• When a Microwave calculation is requested, • After a calculation has completed, • When a licence is acquired, • When a licence is released,
• Before a new document is created from an existing database.
3.30.1 WillQuitApp
Event fired when the user wants to exit an Atoll session. It occurs just before all add-ins are disconnected and after all docu- ments have been closed.
Parameters
[out] evtStatus: A VARIANT_BOOL pointer used to return whether Atoll is allowed to quit (VARIANT_TRUE) or not (VARIANT_FALSE).
3.30.2 DocumentOpenComplete
Event fired when a document has been opened.
Parameters
[in] document: The IDocument interface pointer of the document object which has been opened.
3.30.3 WillCloseDocument
Event fired when the user wants to close a document. It occurs just before the document closes, i.e., after all confirmations requested by Atoll have been answered (stop running tasks, save changes, etc...).
Parameters
[in] document: The IDocument interface pointer of the document object being closed.
[out] evtStatus: A VARIANT_BOOL pointer used to return whether the document is allowed to be closed (VARIANT_TRUE) or not (VARIANT_FALSE).
3.30.4 WillSaveDocument
Event fired when the user wants to save a document. It occurs just before the document file is saved but after a valid file name is set.
Parameters
[in] document: The IDocument interface pointer of the document object being saved.
[out] evtStatus: A VARIANT_BOOL pointer used to return when the document is allowed to be saved (VARIANT_TRUE) or not (VARIANT_FALSE).
3.30.5 DocumentSaveComplete
HRESULT WillQuitApp(VARIANT_BOOL* evtStatus);
HRESULT DocumentOpenComplete(IDocument* document);
HRESULT WillCloseDocument(IDocument* document, VARIANT_BOOL* evtStatus);
Atoll 3.3.2 Task Automation Guide
Chapter 3: Application Object © 2016 Forsk. All Rights Reserved.
Parameters
[in] document: The IDocument interface pointer of the document which has been successfully saved.
3.30.6 DocumentNewComplete
Event fired when a new document has been created.
Parameters
[in] document: The IDocument interface pointer of the document which has been created.
3.30.7 WillRefreshDocument
Event fired when the user wants to refresh a document from database. It occurs just before the connection with the database is checked.
Parameters
[in] document: The IDocument interface pointer of the document being refreshed.
[out] evtStatus: A VARIANT_BOOL pointer used to return whether the document is allowed to be refreshed (VARIANT_TRUE) or not (VARIANT_FALSE).
3.30.8 RefreshDocumentComplete
Event fired when a document has been refreshed from database.
Parameters
[in] document: The IDocument interface pointer of the document which has been refreshed.
3.30.9 WillArchiveDocument
Event fired when the user wants to archive a document to the database. It occurs just after the connection with the database is set up and after Atoll has checked if any changes have to be archived. If nothing requires archiving, this event is not fired.
Parameters
[in] document: The IDocument interface pointer of the document being archived.
[out] evtStatus: A VARIANT_BOOL pointer used to return whether the document is allowed to be archived (VARIANT_TRUE) or not (VARIANT_FALSE).
3.30.10 ArchiveDocumentComplete
Event fired when the document has been archived in database. It occurs just before the connection with the database is broken.
HRESULT DocumentSaveComplete (IDocument* document);
HRESULT DocumentNewComplete(IDocument* document);
HRESULT WillRefreshDocument(IDocument* document, VARIANT_BOOL* evtStatus);
HRESULT RefreshDocumentComplete(IDocument* document);
Parameters
[in] document: The IDocument interface pointer of the document which has been archived.
3.30.11 WillRun
Event fired when the user wants to start a calculation. If all is set to VARIANT_TRUE, this event occurs after the user has confirmed that all previous calculations must be deleted.
Parameters
[in] document: The IDocument interface pointer of the document on which calculation is requested.
[in] all: A VARIANT_BOOL value used to specify whether the user has requested "Calculate All (Ctrl+F7)" (VARIANT_TRUE) or "Calculate (F7)" (VARIANT_FALSE).
[out] evtStatus: A VARIANT_BOOL pointer used to return whether calculation is allowed to run against the document (VARIANT_TRUE) or not (VARIANT_FALSE).
3.30.12 RunComplete
Event fired when the calculation has finished. It occurs after all tasks have completed.
Parameters
[in] document: The IDocument interface pointer of the document.
[in] succeeded: The VARIANT_BOOL used to specify whether calculation has succeeded (VARIANT_TRUE) or not (VARIANT_FALSE).
Remarks
For documents based on the 3GPP Multi-RAT template, there may be several RunComplete events in response to one calcu- lation task. For instance, the path loss matrices calculation might result in 3 RunComplete events, one for LTE, one for UMTS, and one for GSM matrices.
3.30.13 LicenceAcquireComplete
This feature enables the user to log Atoll licence token usage from an add-in. Licence token consumption is available globally for all Atoll instances running on one licence server using a dedicated application (monitor.exe).
External licence tokens are not tracked by this event. Licence events for the Measurements module (Measures) is available for auto-connected add-ins only.
Fired when one licence token is acquired.
HRESULT ArchiveDocumentComplete(IDocument* document);
HRESULT WillRun(
IDocument* document, VARIANT_BOOL all, VARIANT_BOOL* evtStatus );
HRESULT RunComplete(IDocument* document, VARIANT_BOOL succeeded);
HRESULT LicenceAcquireComplete( IDocument *pDocument,
Atoll 3.3.2 Task Automation Guide
Chapter 3: Application Object © 2016 Forsk. All Rights Reserved.
Parameters
[in] pDocument: The IDocument interface pointer of the document that needed one licence token. [in] lModuleID: The long integer used to specify the ID of the licence token that has just been acquired.
Remarks
lModuleID will be one of these constant values:
• LICENCE_GSMTDMA • LICENCE_MW • LICENCE_MEASURES • LICENCE_AFP • LICENCE_PACK3G • LICENCE_UMTS • LICENCE_CDMA • LICENCE_TDSCDMA • LICENCE_WIMAX • LICENCE_LTE
• For LICENCE_MEASURES token, pDocument will be NULL. Module identifiers used when licence application events are fired:
3.30.14 LicenceReleaseComplete
This feature enables the user to log Atoll licence token usage from an add-in. Licence token consumption is available globally for all Atoll instances running on one licence server using a dedicated application (monitor.exe).
External licence tokens are not tracked by this event. Licence events for the Measurements (Measures) module will be avail- able for autoconnected add-ins only.
Fired when one licence token is released. long lModuleID
);
const long LICENCE_GSMTDMA = 2; const long LICENCE_MW = 4; const long LICENCE_MEASURES = 8; const long LICENCE_AFP = 16; const long LICENCE_PACK3G = 32; const long LICENCE_UMTS = 64; const long LICENCE_CDMA = 128; const long LICENCE_TDSCDMA = 256; const long LICENCE_WIMAX = 512; const long LICENCE_LTE = 2048;
HRESULT LicenceReleaseComplete( IDocument *pDocument,
long lModuleID );
Parameters
[in] pDocument: The IDocument interface pointer of the document that just released the licence token. [in] lModuleID: The long integer used to specify the ID of the licence token that has just been released.
Remarks
lModuleID will be one of these constant values:
• LICENCE_GSMTDMA • LICENCE_MW • LICENCE_PACK3G • LICENCE_UMTS • LICENCE_CDMA • LICENCE_TDSCDMA • LICENCE_WIMAX • LICENCE_LTE
3.30.15 WillNewDocumentFromDatabase
3.2.0Fired just before a new document is created from an existing database.
Parameters
[in] connexion: The database connexion string. [in] schema: The database schema.
[out] evtStatus: A VARIANT_BOOL pointer used to return whether the creation of the new document from the database iden- tified by the connexion and schema parameters is allowed (VARIANT_TRUE) or not (VARIANT_FALSE).
3.30.16 WillRunMicrowave
Event fired when the user wants to start a Microwave calculation.
Parameters
[in] document: The IDocument interface pointer of the document on which Microwave calculation is requested.
[in] all: A VARIANT_BOOL value used to specify whether the user has requested "Calculate All (Ctrl+F7)" (VARIANT_TRUE) or "Calculate (F7)" (VARIANT_FALSE).
[out] evtStatus: A VARIANT_BOOL pointer used to return whether Microwave calculation is allowed to run against the docu- ment (VARIANT_TRUE) or not (VARIANT_FALSE).
HRESULT WillNewDocumentFromDatabase( BSTR connexion, BSTR schema, VARIANT_BOOL *pEvtStatus ); HRESULT WillRunMicrowave( IDocument* document, VARIANT_BOOL all, VARIANT_BOOL* evtStatus );
Atoll 3.3.2 Task Automation Guide
Chapter 4
Documents
Object
Atoll 3.3.2 Task Automation Guide
4 Documents Object
The Documents object is used to create a new document or to iterate through open documents in an Atoll session. The Documents object provides the following properties and methods: