Fire Applications
Fire ApplicationsA Fire Application consists of a combination of the following:
Fire applications are compiled to a platform-independent encrypted format, interpreted at run time by the Fire Engine. This is analogous to how a Java Virtual Machine runs Java applets.
A key characteristic of Fire applications is that they can be deployed in different ways, without requiring any changes to the application code. The same application can be deployed without changes:
The key to building applications that will run in all of these different deployment scenarios, is understanding how Fire runs your applications and what is happening in the background.
The Fire Engine includes a component, the Fire (WAM) Application Manager, devoted to managing Fire Applications. The Fire (WAM) Application Manager, itself written in the Fire macro language, is responsible for:
A Fire application may present many different views of itself to the world. For example, it might present a standard view to most users, and an admin view to administration users. It may present itself differently as a component from when it is stand-alone. These application views belong to the application, and form a key part of how the application is started. An application can be started by any of its views, and the application will continue to run as long as any one of its views is open. Once all views of an application are destroyed, the Fire (WAM) Application Manager will stop the application. Once all applications are stopped, Fire itself will stop.
Depending on how your application is deployed, Fire may embed your application views into an ActiveX container, or a web-browser. The information Fire needs to do this is passed to it via parameters on the appstartcommand. Depending on the deployment scenario, determining the parameter values may be done automatically (web-browser), or it may be the responsibility of the programmer (ActiveX and stand-alone). Once the container information (if any) has been determined, the start-up sequence for applications is the same. The following diagram and explanation describes how Fire runs your applications in Standalone, Web Deployed and ActiveX Deployed modes.
In a stand-alone scenario, the user starts Fire from a command prompt (typically within a Windows batch file, or Unix shell script). The invocation command (fire) will include a parameter (-appstart) which will pass information to the Fire (WAM) Application Manager, telling it what configuration file (*.fsc or *.xml) to use and the height and width to use for the application user interface. The application may choose to ignore the height and width parameters.
An alternative way to start an application, typically during application development, is to issue the appstart command at the Fire prompt in the monitor window.
Deploying your application in a Web browser allows for Fire applications to be deployed across the Web. In a Web deployed scenario there are two system components to be downloaded from a web-server:
These 2 components are downloaded once only via a controlling html page. This controlling html page also specifies the Fire application to be downloaded and executed.
After some authorization dialogs, where the user confirms that they are "willing to trust Xmarc software", and also specifies where Fire is to reside on the user's machine, the JAM applet downloads Fire (if necessary), invokes Fire and executes an appstart command internally which starts the application. See the Web Deployed Fire section for further details.
The ActiveX deployment scenario is very similar to the web-deployed deployment scenario. In the ActiveX scenario, the programmer adds the Fire Engine ActiveX control to the visual form in their application. The container window is owned by the Fire Engine itself (which is the ActiveX control). The Fire Engine behaves just like other ActiveX controls, in that it has methods you can execute and it can raise events to the client application. (How methods are called and events are handled will vary depending on the client programming environment).
In the ActiveX scenario, it is the responsibility of the programmer to execute the appstart command to actually start the Fire Engine and Fire (WAM) Application Manager, passing parameters to get the Fire (WAM) Application Manager to start the application. The configuration file may reference a file or a URL location for the compiled Fire application, making it possible for your application to behave as a version-managed ActiveX control that is updated over an Intra/Internet.
The window that will be used for embedding is one of the parameters passed on the appstart command, and is usually the component canvas of the Fire Engine itself.
Note: You can in fact pass a window handle (Windows) or X-window id (Unix) for the embedwindow. For more information see the embedcommand in the Fire Reference Manual.
You should also note that the Fire Engine works as an OLE Automation Server (non-visual), an Insertable OLE control and an ActiveX control. Usually, a development environment client (e.g. Visual Basic) will only show one of the Xmarc Service Object controls. In some instances, the Xmarc Service Object may appear under both OLE controls and ActiveX controls. You should always try to use the ActiveX control in preference to the OLE control.
The sections above describe how the container window is created for your application and how the appstart command is executed. This section describes the appstart command and the Fire (WAM) Application Manager in more detail.
Note: appstart is not strictly a Fire command, but is in fact a stanza which invokes a WAM procedure.
The appstart command instructs the Fire (WAM) Application Manager to start an application. It takes parameters including:
There are two ways of executing the appstart command:
The Fire (WAM) Application Manager uses the parameters passed to appstart to start execution of the application. This is how it works:
1. The configuration .fsc or .xml file is located, downloaded if it is a URL, and read. The configuration file contains the following parameters:
• APPURL – A file or URL location of the compiled application (a .fsa file).
• APPNAME – The short name of the application.
• APPVERSION – The version of the application referenced by the APPURL.
• APPFORCERELOAD – Whether or not the application should be downloaded irrespective of version management information
Note: The configuration file may also contain Fire statements that will be executed as part of the start up sequence of the application. These are typically variable assignment statements used to pass information to the application.
2. If the APPURL indicates a URL (i.e. not a file), then the following version management is performed:
• If no copy of the application exists in the local Fire cache, then the .fsa is downloaded to the local Fire cache (from the APPURL file location)
• If APPFORCERELOAD is set to 1 (true) then the .fsa file is always downloaded to the local Fire cache.
• The application version information of any local Fire cache copy of the application (held in the application.ver file within the application .fsa file) is compared with the APPVERSION information supplied in the configuration file. If they disagree, then a new copy of the application is downloaded to the local Fire cache.
Once downloaded (or not), the cached application .fsa file is the one to be mounted and executed.
3. If APPURL indicates a .fsa file on the local file system, then no version management or caching is performed (APPVERSION and APPFORCERELOAD are ignored). The indicated .fsa file will be the application to be mounted and executed..
4. The application is mounted. This effectively makes files within the compiled application accessible by the Fire Engine. The APPNAME parameter is used as the root application root path to access files within the application. See ‘The Application Root Path’ below for more information about file paths within a compiled Fire application.
4. The Fire (WAM) Application Manager executes the @<APPNAME>/init.cmd file of your application. This should set up variables for any parameters that are set in the .fsc or .xml configuration file.
5. The Fire (WAM) Application Manager executes the Fire code within the configuration file (*.fsc or *.xml). This is usually the mechanism to pass any parameters to the application. For example, what database the application should connect to, or the URL it should use to locate data files. Because the configuration file is always downloaded, this is a good mechanism for passing changeable information (e.g. data-server URL names and port numbers) to web-deployed applications.
6. The Fire (WAM) Application Manager executes the @<APPNAME>/start.cmd file of your application. This should start the application itself, but should not create any windows.
7. The Fire (WAM) Application Manager executes the @<APPNAME>/appview.cmd file of your application, passing it the application view name (in stand-alone deployment models this will be blank). In the ActiveX deployment scenario, the Fire (WAM) Application Manager will associate the logical application view name with the ole canvas passed as a parameter to the appstart command. The height and width of the container are also passed.
Your Fire application is now running!
Applications running in a browser window can also be affected by user actions within the browser. For example, if the user pages back or jumps to a new URL. If a user does this then your application view HTML page will be ‘paged out’. The Fire (WAM) Application Manager will notify you that this has happened by calling the appview.cmd file, passing the container window and a visibility flag (of false) as parameters. Under Internet Explorer, when the user jumps to a new page, leaving the Fire app page, Fire will shut down.
If the user goes through many (non-application) pages, the application view HTML page will move further and further down through the ‘history’ stack of the client's browser until eventually it ‘falls off’ the stack. The client browser determines the size of the history stack. At this point, the Fire (WAM) Application Manager will notify your application that the application view has been destroyed (again, by calling appview).
Once all of the application views belonging to your application have been destroyed, the Fire (WAM) Application Manager stops your application. This is done by calling the stop.cmd file or the .fsa application.
CAUTION:
Do not call stop.cmd from within your application, as this could interfere with the operation of the Fire (WAM) Application Manager.
Once all of the applications which Fire is running have been stopped, Fire automatically shuts down. If the browser itself is shut down, then Fire destroys all the currently open views, stops all running applications, then shuts down.
At the start of this chapter, we said that a Fire application was essentially a collection of files. This allows you to decompose your application into manageable pieces that can be worked on separately, rather than putting all of your source code in one huge file.
When you are working on your own machine, you can reference other files explicitly by their fully qualified path and file name. So, for example, if your application is located in /usr/sjo/projects/wis_proj, then you could call the setup.cmd file by using exec /usr/sjo/projects/wis_proj/setup (.cmd is the default file extension). But this won’t work when you deploy your applications to other users, as their directory hierarchy won’t match your directory hierarchy (and you won’t necessarily want to give them your source code).
To enable you to develop applications which will deploy onto other users’ systems including cross-platform deployment between windows and Unix file systems, Fire uses the concept of an Application Root Path.
When you compile a Fire project, you collect all of the files belonging to a project into a single application file. This process is conceptually similar to ‘zipping’ or ‘tar-ing’ a directory tree containing multiple files and sub-directories into a single file. The Fire compiler creates a location reference for each file relative to a pseudo root directory.
The pseudo root directory name is specified by the ‘product name’ when you compile your application, and is the APPNAME parameter provided in the configuration file.
You can then use the pseudo root directory name to access files within the application.
For example, instead of using exec /usr/sjo/projects/wis_proj/setup, you can use exec @wis/setup. The compiler also encrypts your source code files. This diagram illustrates the source code project directory for the wis_proj project and the application directory once the project is compiled with a product name of wis. For more information, see Compiling Fire Applications.
Source Code
Compiled Application
Note: Notice the use of Unix-style forward-slashes in the file path names. It is highly recommended that you use the Unix file path format (i.e. forward slash characters) in preference to the Windows file path format (back slashes) in all file references within your application. Although either will work, back-slashes are also used as escape characters in strings, so using back-slashes in filename references can cause problems. If you need to determine the proper file name for the operating system on which your application is running(for example to call a system command passing a file parameter) you can always use the flocal() function. See the on-line help for the flocal function for more information.
Before you compile your application, you will commonly want to test it by running the uncompiled source code. Fire is an interpreted environment, so it fully supports this requirement, but you need to create a pseudo-root directory location for your source code (so that Fire can correctly translate @<appname>/xxx style file references into fully qualified source code file references).
Fire provides a mechanism for creating your own pseudo-root directory location and mapping it to an actual directory location so that you can run your uncompiled application source code.
When an application requests access to a file whose name which begins with an @ sign, Fire will first try to resolve the file location by checking the pseudo-root directory of the currently mounted applications. If Fire cannot resolve the pseudo-root directory in this fashion, it will replace the @ sign with a $ sign, and treat the pseudo-root directory as an environment variable. (If this fails, you will get a File not found error).
In order to run your application in development (uncompiled) mode, you simply need a .fsc or .xml configuration file with the APPURL parameter pointing to the directory where the source resides, rather than to the compiled .fsa application file.
WAM will detect that you are running source, by realising that you have indicated a directory/folder rather than a .fsa file/url. Consequently it will set up a suitable environment variable and execute the relevant macros (init.cmd and start.cmd) if they exist.
It is for this reason that APPNAME in the .fsc or .xml configuration file should be the application short name, so that @appname references within your application source can be successfully resolved.
It should go without saying that to run application source you must have all the source on your local file system. Source cannot be run remotely via a URL.
Consider an example:
Assume your application source resides in c:/myfiles/testapp, i.e. this directory will contain init.cmd, start.cmd and all your other macros and data files.
Assume your application short name will be "myapp", i.e. files within the application will be referenced as @myapp/whatever.
Create a .fsc file with the following parameters:
#APPURL='C:/myfiles/testapp' #APPNAME='myapp' #APPVERSION=1.0 # Add any parameter assignments here to be executed on startup
We would put the file into the testapp directory and name it application_src.fsc.
Start fire, either with
fire -appstart='c:/myfiles/testapp/application_src.fsc'
or without parameters, and once fire has started type into the monitor window
appstart c:/myfiles/testapp/application_src.fsc
This will start your application running.
You could have used a .xml file instead of .fsc, e.g.
<?xml version="1.0" encoding="ISO-8859-1"?>
<!-- TestApp RunTime Configuration -->
<FireApp>
<AppName>myapp</AppName>
<AppURL>c:/myfiles/testapp</AppURL>
<AppVersion>1.0</AppVersion>
<Code><![CDATA[
# Add any parameter assignments here to be executed on startup
]]></Code>
</FireApp>
Note the nice user-friendly way of adding the Fire code (raw data) to an xml file. This is beyond our control. It must have been designed by the same guy who wrote edlin.
To simulate ending your application, at the command prompt type appstop myapp. This will simulate how a browser stops the application. Do not use exec @myapp/stop.cmd because this interferes with WAM.
In a compiled application browser deployment, this would normally shut Fire down as well, but as you are running in development mode, Fire is not shut down and you are left at the command prompt, to start the application again if you wish with another appstart command.
Once you want to compile and deploy your application, you would change the APPURL statement in the .fsc or .xml file to point to your compiled .fsa application file.