Quick Start - Adding New Applications

In order to have the GAS deliver an application, you need to provide the application's configuration details to the GAS.

Topics

Understanding application configuration

Creating an application group

Creating an application configuration file

Adding an application directly to the GAS configuration file

Configuring database environment variables for an application

Using a script to set the application's environment

Specifying an images directory for an application

Understanding Application Configuration

Before you start, you should have successfully installed the Genero Application Server and validated your installation. See Installation for more details.

Once you've verified that you can display the demo application with the desired front-end client, you then add your own custom applications to the configuration. While there are several ways to specify application configuration, this topic will outline the best practices for adding your application configuration details to the GAS configuration.

To add applications:

Step 1: Identify (or create) an abstract application

An abstract application is an application definition that defines the various configuration settings (known as components) that the Genero Application Server needs to run an application. In other words, the purpose of an abstract application is to provide default components / configuration details that can be inherited by other applications. These components can include defining resources, environment variables, timeout settings, themes, and more. An abstract application cannot be directly executed.

By default, abstract applications have been defined for you in the GAS configuration file (default as.xcf) for each of the various front-end clients. For example, an abstract application named "defaultgwc" has been defined for you for use with the Genero Web Client. You can use this default abstract application, or you can create a new abstract application.

Abstract applications must be defined in the GAS configuration file. After updating the GAS configuration file, the GAS must be restarted.

An abstract application is used to define a configuration set shared by multiple applications. Internal and external applications will inherit an abstract application's configuration via the Parent attribute of their APPLICATION tag.

An abstract application is defined in the same way an internal or external application is defined, except it has an extra attribute set in its APPLICATION tag, where Abstract="TRUE".

When you define the configuration for a specific application, you can override the settings you inherit from the abstract application.

Step 2: Create an application group

A GROUP defines a directory that contains application-specific configuration files. Groups must be defined in the GAS configuration file.

By creating a group, you can add new application configuration files in the group directory, and the applications are instantly available to the GAS without having to restart the application server.

Instructions for creating an application group are provided below.

Step 3: Create the external application configuration file

To add a configuration file for an application, you create a new file within the group directory. The name of the file should match the name of the application, and have an XCF suffix. For example, if the application name was "app1", then you would create a configuration file named "app1.xcf". In this file, you specify a parent application - the abstract application from which this application will inherit its default settings.

These files are known as external application configuration files. You could also add the same information to the GAS configuration file; however you have to restart the GAS whenever you modified the GAS configuration file. By using groups and external application configuration files, you've provided flexibility in growing the number of applications delivered by the GAS without having to worry about the impact of restarting the GAS.

NOTE: When an application is defined within the GAS configuration file, it is known as an internal application. When an application is defined in a separate application configuration file, it is referred to as an external application, and its configuration file is known as an external application configuration file.

Instructions on creating an external application configuration file are provided below.

Creating an Application Group

The GROUP element defines an alias for a directory containing one or more external application configuration files. The alias is then used in the application URL, letting the GAS know in which directory to find the external application configuration file.

You can use application groups to organize your applications into logical groups or a hierarchy.

Consider the following application URL:

  http://<server>/cgi-bin/fglccgi/wa/r/accounting/app1

In this URL, both a group ("accounting") and an application name ("app1") are specified. The Genero Application Server, on receiving this application request, uses the group alias to identify the directory holding the external application configuration file.

  <GROUP Id="accounting">/path/config/accounting</GROUP>

Within this directory, the Genero Application Server would expect to file a file whose name matches the name of the application with an .xcf suffix. In this example, the Genero Application Server would be looking for a file named "app1.xcf".

Syntax

  <GROUP Id="groupId"> path </GROUP>

Notes

groupId is the alias.
path is the physical path to the directory.

Examples

  <GROUP Id="demo">$(res.path.demo.app)</GROUP>

This example assigns the alias demo to the directory containing the external application configuration files for demo applications. The path is defined using a RESOURCE $(res.path.demo.app). By wisely using RESOURCE elements, you can set your configuration where a change to the directory structure only requires a change to a single RESOURCE element in the configuration file.

To access an application defined externally and contained within this group, you would enter an application URL that includes the alias in its path:

  http://server/cgi-bin/fglccgi/wa/r/demo/CardStep1

Based on this URL, the Genero Application Server expects to find the configuration file CardStep1.xcf within the directory specified for the demo group.

The default group

The Genero Application Server configuration file provides a default group, defined using the name _default. When an external application configuration file is added to this group, the application URL can omit using a group name and simply reference the application.

For example, the GAS installs with demo applications for use with the GWC, to include an application that demonstrates Edit fields. You access the application by entering:

http://server/cgi-bin/fglccgi/wa/r/Edit

The application URL does not specify a group, and the Edit application is not defined internally. It must therefore be defined in an external application configuration file, located in the directory defined for the _default alias.

<GROUP Id="_default">$(res.path.app)</GROUP>

The RESOURCE $(res.path.app) resolves to $FGLASDIR/app, where you find a file named Edit.xcf. This is the Edit application's external application configuration file.

Back to the top

Creating an Application Configuration File

The APPLICATION element defines an application environment. Within this element, you can define local resources, change the execution environment, the timeout settings and the picture and output settings. You can refer to previously defined components by using the tag attribute Using.

Syntax

<APPLICATION Id="appId" [ Abstract="{ TRUE | FALSE }" ] [ Parent="pAppId" ] >
   [ resource ] [...]
   [ <EXECUTION [ Using=" exCompId " ] > execution </EXECUTION> ] 
   [ <TIMEOUT [ Using=" timeCompId " ] > timeout </TIMEOUT> ] 
   [ <PICTURE [ Using=" picCompId " ] > picture </PICTURE> ] 
   [ <OUTPUT Rule="UseGWC">
       <MAP Id="DUA_GWC" Allowed=" { TRUE | FALSE } " >
            [ <THEME [ Using=" themeCompId " ] > theme </THEME> ] 
        </MAP>
     </OUTPUT> ] 
</APPLICATION>

Notes

appId is the application identifier
pAppId is the parent application identifier
An abstract application is used to share common configuration between multiple child applications. An abstract application can't be instantiated.
resource is a local RESOURCE definition
exCompId, timeCompId, picCompId and themeCompId are components identifiers
the content of execution, timeout, picture and theme is the same as the content of their respective components

Example 1

The simplest external application configuration file only needs to specify a parent application and the path to the compiled application files. In this example, the application inherits the configuration settings of the parent application. This XML would be saved in a file named appname.xcf, where appname is the name of the application.

The following XML defines the Edit application in an external application configuration file Edit.xcf.

01 <APPLICATION Parent="defaultgwc">
02   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
03   xsi:noNamespaceSchemaLocation="http://www.4js.com/ns/gas/2.11/cfextwa.xsd">
04  <EXECUTION>
05    <PATH>$(res.path.fgldir.demo)/Widgets</PATH>
06  </EXECUTION>
07 </APPLICATION>

Notes

The name of the application is the name of the .xcf file. The Id attribute of <APPLICATION> tag is omitted for external applications; even if included, its value is not read. Instead, the GAS uses the name of the configuration file to match to the value of the Id attribute.
In the example above, the Id of the application is Edit.
The external application configuration file is re-read at each application launch. There is no need to restart GAS after modifying an external configuration file.
The directory where the GAS searches for the external application configuration file is defined in as.xcf by the tag <GROUP Id="_default">directory</GROUP>. The default after installation is $FGLASDIR/app.
The Parent application is defined as "defaultgwc". This means that the application will inherit the configuration settings defined for the default GWC (defaultgwc) application, which is an abstract application defined in the GAS configuration file.
The path to the application executables is defined by the PATH component.
No MODULE element is needed when the external configuration file shares the same name as the application. When there is no defining <MODULE> tag in the application configuration, the module taken by default is the name of the application.

Limitations

An external application cannot be an Abstract application.
An external application can only inherit from an internal application.

Example 2

While an application inherits its base configuration from the parent application, additional configuration elements can be added and existing configuration elements can be overwritten. This next example of a hypothetical external application configuration file, tutorialStep1.xcf, which would be found in the demo directory.

01 <APPLICATION Parent="demo-tut-abstract">
02   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
03   xsi:noNamespaceSchemaLocation="http://www.4js.com/ns/gas/2.11/cfextwa.xsd">
04   <!-- Define a resource to the template HTML file -->
05   <RESOURCE Id="res.template.tutorial" Source="INTERNAL">$(res.path.demo.dem-tut)/web/tutorial/tutorialStep1.html</RESOURCE>
06   <EXECUTION>
07     <PATH>$(res.path.demo.dem-tut)/src</PATH>
08     <MODULE>tutStep1.42r</MODULE>
09   </EXECUTION>
10   <!-- Override default rendering template -->
11   <OUTPUT>
12     <MAP Id="DUA_AJAX">
13       <THEME>
14         <TEMPLATE Id="_default">$(res.template.tutorial)</TEMPLATE>
15       </THEME> 
16     </MAP>
17   </OUTPUT> 
18 </APPLICATION>

Notes

Line 01 specifies the parent application as "demo-tut-abstract". Unless a value is overwritten locally in the application configuration, the child application inherits the configuration elements defined by the parent application.
Line 05 defines a local RESOURCE. This resource maps to a template file.
Lines 07-08 provide the path and file name of the program executable. It is common to exclude the MODULE element when the executable name matches the application name as provided in the URL. In this example, if the external application configuration file had been named "tutStep1.xcf", then the MODULE element specifying the program executable as "tutStep1.42r" could have been excluded.
Line 12 defines the OutputMap as "DUA_GWC".
Line 14 overrides the _default template with the template defined by the $(res.template.tutorial) resource in Line 04.

For additional information on the APPLICATION element and its child elements, see Application List Reference.

To summarize, applications are typically defined using external application configuration files, which are recognized as soon as they are added to a GROUP directory.

Back to the top

Adding Applications to the GAS Configuration File

While it is recommended that you add new applications using application groups and external application configuration files, you have the option of adding your application's configuration details directly in the GAS configuration file. Modifications to this file are recognized only after the application server is restarted.

Both GROUP and APPLICATION configuration takes place within the APPLICATION_LIST element in the Genero Application Server configuration file.

<APPLICATION_LIST>
  [ group | application ] [...]
</APPLICATION_LIST>

To provide the application configuration within the Genero Application Server configuration file, you add an APPLICATION element and use the Id attribute to specify the application name. It is this application name that is then used within the application URL.

Consider the following URL:

http://<server>/cgi-bin/fglccgi/wa/r/app1

If the application is defined internally, you would expect to find an APPLICATION element with an Id that matches the application name provided in the URL:

<APPLICATION Id="app1" Abstract="FALSE" Parent="defaultgwc"> ... </APPLICATION>

The elements you can define between the APPLICATION tags is the same as for those applications defined externally. For details, see Creating an Application Configuration File.

Example in as.xcf defining 'gwc-demo' application

01 <?xml version="1.0" encoding="ISO-8859-6"?>
02 <?fjsApplicationServerConfiguration Version="1.30"?>
03 <CONFIGURATION>
...
181 <APPLICATION_LIST>
...
222   <!--Sample application for GWC-->
223   <APPLICATION Id="gwc-demo" Parent="defaultgwc">
224     <EXECUTION>
225       <PATH>$(res.path.fgldir.demo)</PATH>
226       <MODULE>demo.42r</MODULE>
227     </EXECUTION>
228   </APPLICATION>
...
234 <APPLICATION_LIST>
...
235 <CONFIGURATION>

Notes

The above example shows the minimum information required to define an application in the application server configuration file.

The application is defined within the APPLICATION tags. The attributes shown in the example are only a few of the attributes allowed within the APPLICATION tags. For a more complete list of application tags, see the Application List Reference.
The Id tag specifies the name of the application. It is this name that is referenced in the URI.
The Parent tag identifies the parent application. This may be an executable or abstract application. This application inherits the attribute values set for the parent application. For those attributes that are assigned a value both in the parent application definition and within this application's definition, the value set for the application overrides the value set for the parent.
The EXECUTION section contains additional tags providing information needed to execute the correct application.
The PATH attribute defines the directory containing the module to be executed. It is typical to list a resource that maps to the directory than the actual directory.
The MODULE attribute identifies the module to execute. Note that the extension is used.

Warning: After making changes to the internal application configuration file, the application server (gasd) must be restarted for the changes to take effect.

Back to the top

Configuring the Database Environment

You may need to set database-related environment variables for your application to work correctly. Environment variables are set within the EXECUTION element of an application's configuration.

Syntax

  <ENVIRONMENT_VARIABLE Id="env_var">env_value</ENVIRONMENT_VARIABLE>

Notes

env_var is the environment variable name.
env_value is the value used to set the variable name.

Example (using Informix)

<APPLICATION Id="myapp" Parent="defaultgwc">
  <EXECUTION>
    <ENVIRONMENT_VARIABLE Id="INFORMIXDIR">ifx_path</ENVIRONMENT_VARIABLE>
    <ENVIRONMENT_VARIABLE Id="INFORMIXSERVER">ifx_server</ENVIRONMENT_VARIABLE>
    <ENVIRONMENT_VARIABLE Id="LD_LIBRARY_PATH">library_path</ENVIRONMENT_VARIABLE>
    <PATH>/home/myapp/bin</PATH>
    <MODULE>app.42r</MODULE>
  </EXECUTION>
</APPLICATION>

Notes

Replace ifx_path with the value of the INFORMIXDIR environment variable.
Replace ifx_server with the value of the INFORMIXSERVER environment variable.
Replace library_path with the value of the LD_LIBRARY_PATH environment variable.

Back to the top

Using a Script to set the Environment

Rather than specifying the environment variables with ENVIRONMENT_VARIABLE elements, you can provide an application configuration that calls a script, where the script sets the execution environment.

Example

<?xml version="1.0"?> 
<APPLICATION Parent="defaultgwc" 
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
 xsi:noNamespaceSchemaLocation="http://www.4js.com/ns/gas/2.10/cfextwa.xsd"> 
  <EXECUTION> 
    <PATH>/home/f4gl/gep/configfiles/officestoredemo</PATH> 
    <DVM>/bin/sh</DVM> 
    <MODULE>gdc-kiosk.sh</MODULE> 
  </EXECUTION> 
</APPLICATION>

Notes:

PATH is where the script is stored.
DVM is the command to execute the script.
MODULE is the script file.

Back to the top

Specifying an Application's Images Directory

By default, the GAS looks for images in $FGLASDIR/pic. You can add your images to this directory or you can specify your own image directory. To define your own directory of images, you first define an alias for the directory in the Genero Application Server configuration file, and then reference the alias in the application configuration.

Defining an Alias

An alias is like any Web Server alias. This maps a URL path to the server directory. For example:

<INTERFACE_TO_CONNECTOR>
  ...
  <DOCUMENT_ROOT>$(res.path.docroot)</DOCUMENT_ROOT>
  <ALIAS Id="/images">/home/app/images</ALIAS>
  ...
<INTERFACE_TO_CONNECTOR>

In this example, the alias /images is mapped to the directory /home/app/images.

After you have added the alias to the GAS configuration file, you must restart the GAS daemon. Remember, you must restart the Genero Application Server daemon (gasd) whenever you make any changes to the GAS configuration file, as this file is read at start-up.

Once the GAS restarts, you can access an image with the URL:

  http://<app_server>:6394/images/img.png

(This example assumes the img.png file is in directory /home/app/images.)

Referencing the Alias in the application configuration

Having defined the alias, you reference the alias within the application configuration.

Syntax

  <PICTURE>
    <PATH>$(connector.uri)alias</PATH>
  </PICTURE>

Notes

alias is the alias previously defined in the INTERFACE_TO_CONNECTOR element.
$(connector.uri) allows for pictures stored on the application server to be available to the Web server.

Example

<APPLICATION Id="myapp" Parent="defaultgwc">
  <EXECUTION>
    <PATH>/home/myapp/bin</PATH>
    <MODULE>app.42r</MODULE>
  </EXECUTION>
  <PICTURE>
    <PATH>$(connector.uri)/images</PATH>
  </PICTURE>
</APPLICATION>

For more details on application configuration, see also:

Back to the top