The HostApp class is an important class for interfacing with the host application. It provides access to the host application's frame, menus, document infrastructure, job queue, and other important aspects.
// example 1: getting a list of open documents and closing
// the documents that begin with "http"
// get all the host application's open documents, which
// are returned by HostApp.getDocuments() as an array of
// HostDocument objects
var g_all_documents;
g_all_documents = HostApp.getDocuments();
for (var doc in g_all_documents)
{
// for each open document, find the location
var location;
location = g_all_documents[doc].getLocation();
// if the location starts with http, close it; note:
// this doesn't close all web documents, but only
// those that start with http; this is simply to
// demonstrate some of the functions for working with
// open host documents
if (location.substr(0,4) == "http")
HostApp.close(g_all_documents[doc]);
}
// example2: storing a list of browsed locations in a
// database table
// create a browse history object and call Application.run(),
// which starts the event loop that processes frame events
var history = new BrowseHistory();
Application.run();
// browse history class definition
class BrowseHistory
{
// class member variables for the local database and output table
var m_db = HostApp.getDatabase();
var m_table = "browse_history";
function BrowseHistory()
{
// note: this is the browse history class constructor
// and is called when a browse history object is created;
// this constructor simply connects the host application
// location changed event to the onLocationChanged function
// connect the onLocationChanged event handler to process
// location changed events
HostApp.locationChanged.connect(this, onLocationChanged);
}
function onLocationChanged(sender, evt)
{
// note: this function is called when the host application
// location changed event is fired; when this happens, this
// function checks if a browse history table exists, and if
// it doesn't, it creates one; then it adds a new row to the
// table that contains the new location along with a timestamp
// indicating when the location changed
if (!m_db.exists(m_table))
{
// if the browse history table doesn't exist, create it
m_db.execute
("
CREATE TABLE " + m_table + "
(
TITLE VARCHAR(200),
LINK VARCHAR(200),
BROWSE_DATE DATETIME(8)
);
");
// refresh the host application project tree
HostApp.refresh();
}
// find out the date and time
var dt = new Date();
var browse_date = dt.getFullYear() + "-" +
(dt.getMonth() + 1) + "-" +
dt.getDate() + " " +
dt.getHours() + ":" +
dt.getMinutes() + ":" +
dt.getSeconds();
// create a SQL statement to insert the new location into the
// browse history table, along with a timestamp indicating when
// the location changed
var sql = "INSERT INTO " + m_table +
" (TITLE, LINK, BROWSE_DATE) VALUES ('" +
evt.caption + "','" + evt.location + "','" + browse_date + "');";
// execute the SQL statement to actually add the record
// to the history
m_db.execute(sql);
}
}
True if the host application is equal or newer to the specified version number
Calling checkVersion() checks the version number specified as four parameters against the host application's version number. If the host application's version number is greater or equal to the specified version, the function returns true. Otherwise, it returns false. This is useful for scripts that rely on certain features only present in newer versions of the host app.
Returns true upon success, false otherwise.
Closes the document window represented by the specified doc parameter. If the window contains unsaved information, the user will normally be prompted as to whether the information should be saved. If this prompting is not desired, passing true in the optional force parameter will suppress this behavior.
Calling crash() will simulate a general protection fault, which will cause the program to crash. This is useful for testing script applications which have recovery mechanisms for this eventuality.
true if the operation succeeded, otherwise false if an error occurred
Creates a new database at the specified location. The type of database created is indicated by the type parameter, which is one of the values included in the DbDatabaseType enumeration.
True upon success, false otherwise
The execute() method allows the caller to execute a script, template, or executable object in the project panel. By default, the execution occurs synchronously, meaning that code execution returns immediately to the calling scope, while the executable specified by path is executed simultaneously. In the flags parameter, one or more flags may be specified which alter the behavior of the call. If the user specifies ExecuteWait, the execution will run asychronously. If the ExecuteSource flag is specified, target must contain the source code that is to be executed.
True upon success, false otherwise
The executeAndWait() method allows the caller to execute a script, template, or executable object in the project panel. The execution occurs asynchronously, meaning that code execution returns immediately to the calling scope, while the executable specified by path is executed simultaneously.
Calling exit() causes the host application to exit. The force parameter, which may optionally be specified, indicates whether the application should force closing. If exiting is forced, the application will not prompt the user to save unsaved documents. The default value for force, false, is assumed if the force parameter is not specified. In this case, the application will display prompt dialogs to save modified documents.
This method returns the active document in the system. The active document is the window that current has the user focus. If no documents are open in the system, null is returned.
The application identification tag
Returns an identification tag that corresponds to the host application.
An array of strings containing the command line parameters
This method retrieves the command line arguments that were specified upon program execution.
Returns a string containing the current location in the URL bar.
Returns the current location in the URL bar.
A DbConnection object
Returns a DbConnection object representing the application's current database connection. Using this object allows programs to access and manipulate the host application's current database project.
A string containing the current database's connection string
Returns a string containing the connection string used to connect to the current database project
Returns a HostDocument object
Each HostDocument object has an associated numeric ID. This number may be retrieved by calling HostDocument.getId(). The same document can be looked up again by utilizing HostApp.getDocumentById(). If a document with the specified ID exists, this method will return the corresponsing HostDocument object. If not, null is returned.
Returns an array of HostDocument objects
Returns an array of HostDocument objects which represent all open documents inside the program. A 'document' is a window or container which holds information in the system, such as a web control, table, report, or text editor. See HostDocument for more information on how documents can be manipulated.
Returns a string containing the frame caption
A call to HostApp.getFrameCaption() allows the script application to get the existing frame caption of the host application.
A MenuBar object. Null is returned if there is no menu.
A call to getFrameMenu() returns a MenuBar object which represents the host application's menu bar. This is useful for script applications that wish to add or remove menu items from the host application's menu hierarchy.
The host application's version number
Returns the version of the host application as a string. This string is formatted as four period-separated integers (for example, 1.2.3.4). The numbers mean, from left to right, major version number, minor version number, sub-minor version number, and build serial. The individual elements can be parsed out using the String functions.
Calling hang() will simulate an application freeze by blocking the main GUI thread. This is useful for testing script applications which have recovery mechanisms for this eventuality.
True if a gui is active, false otherwise
This method returns true if a graphical user interface is being used to run the software. False is returned if console mode is being used.
True if the software is being run as a service, false otherwise
This method returns true is the software is running as a service. If the software is run as a desktop application with a graphical user interface, the method returns false.
A valid HostDocument object upon success, null in the case of an error.
Creates a new document in the host application. The document type can specify any document type that the application supports. Possible values are "table", "web", "query", "editor", or "report"
A valid HostDocument object upon success, null in the case of an error.
Opens and browses a database table, document, or web page. For some data types, such as text files, if the file is already open, that document is instead shown. A host document object is returned. If the document could not be opened, null is returned
true if the operation succeeded, otherwise false if an error occurred
Opens a database as the host application's current database project. The database may be specified with a connection string, a path to the database, or a database connection object.
Much of the functionality of openWeb() is similar to open(). The openWeb() function, however, exposes additional functionality allowing post parameters to be specified. This is useful for filling out forms and displaying the resulting web page in a browser
During the execution of the script, if new database objects are created, removed, or modified, it might become necessary to refresh the host application's panels, most notably the project panel. This allows new database objects to be displayed in the project panel, and makes deleted ones disappear.
A string value containing the result of the web request. A null value indicates failure. An empty string likely indicates failure as well, though certain web requests may normally result in an empty string.
The sendWebRequest() method is similar to the openWeb() method, with one difference: Instead of the resulting page being opened in a browser window, it is returned to the application as a string.
By default, the host application sets its own frame caption. A call to HostApp.setFrameCaption() allows the script application to modify the frame caption of the host application.
Shows the host application's main window if the show parameter is true, and hides it if the parameter is false.
Shows the host application's job manager if the show parameter is true, and hides it if the parameter is false.