Keeping Your Genero Installation Intact

When installing and configuring Genero it can be tempting to do your configuration via modifying the installed files.  I am not a fan of this method.  The reason why is when investigating issues it can be difficult to determine what has happened.  What we find is that you have modified the installed file in one installation and not another, or you forgot that you made the modification and then don’t tell us when raising your support case.  In this article I will make you aware of some environment variables, code, and command line arguments you can use so that the installed files remain as we delivered them.

FGLLICENSE

When using Four Js License Manager, one configuration option is to directly modify the file FGLDIR/etc/fgllicense.   You don’t have to modify this file, if the environment variable FGLLICENSE is defined, it can be used to point to your own copy of FGLDIR/etc/fgllicense stored outside of our product directories.

FGLPROFILE

The file FGLDIR/etc/fglprofile, the fglprofile file as it is known can be used to configure some runtime options.  If the environment variable FGLPROFILE is defined, it can be used to point to your copy of FGLDIR/etc/fglprofile stored outside of our product directories.

FGLIMAGEPATH

The environment variable FGLIMAGEPATH contains the list of directory paths the runtime will use to search for image files.  If not specified, one of the default entries, it uses is FGLDIR/lib/image2font.txt which contains the font glyph mapping information to the centralised images shipped with Genero.

If you have any need to edit this file,  rather than editing it directly, you can create your own copy of it and then edit it.  This requires you to reference your copy in FGLIMAGEPATH.

A typical reason for doing this is to add colour to our default images, or to specify alternate names for images, or to use another set of font glyphs.

CALL ui.Interface.loadStyles()

With Presentation Styles, if your Genero application does not specify a stylesheet, the default stylesheet used is FGLDIR/lib/default.4st as specified here.  A temptation then is to directly modify FGLDIR/lib/default.4st with your stylesheet requirements.

To avoid modifying  FGLDIR/lib/default.4st, what you can do is create your own stylesheet and load it as part of your program initialisation with the ui.Interface.loadStyles method.  This method will use FGLRESOURCEPATH when determining where to look for this file.  Typically you will set FGLRESOURCEPATH to point to your own directories and have a simple filename in the ui.Interface.loadStyles call

export FGLRESOURCEPATH = /my_app_dir

CALL ui.Interface.loadStyles("mystyles.4st")

where mystyles.4st is in /my_app_dir.

CALL ui.Interface.loadActionDefaults()  

Action Defaults and Stylesheets have similar loading methods.  The default set of action defaults used is taken from FGLDIR/lib/default.4ad as specified here.   A temptation then is to directly modify FGLDIR/lib/default.4ad with your action defaults.

To avoid modifying  FGLDIR/lib/default.4ad, what you can do is create your own action defaults file  and load it as part of your program initialisation with the ui.Interface.loadActionDefaults method. This method will use FGLRESOURCEPATH when determining where to look for this file.  Typically you will set FGLRESOURCEPATH to point to your own directories and have a simple filename in the ui.Interface.loadActionDefaults call similar to what you would do for Presentation Styles.  There is one difference though in that you can override Action Defaults at the Form level but that does not typically involve touching installed files.

GAS -f, -E command line arguments

When a Genero Application Server dispatcher (httpdispatch, fastcgidispatch , isapidispatch) is started, if no option is specified it will read its configuration information from the default GAS configuration file FGLASDIR/etc/as.xcf.

Rather than modifying, FGLASDIR/etc/as.xcf, you can maintain your own configuration file and reference it with the use of the -f argument when the dispatch process is launched.  So instead of simply executing httpdispatch which would read FGLASDIR/etc/as.xcf,  you would do something like httpdispatch -f mydir/myas.xcf which will read your modified file.

The -E option is also available to avoid making multiple copies of this as.xcf file that might perhaps only have a small number of changes.  What the -E option does is override a resource entry specified in the .xcf file.

An example usage might be in a scenario where you have two dispatchers running on the same server.  You can use -E to override the resource entries that need to be unique for each instance e.g. -E res.ic.server.port = 6395 -E res.ic.admin.port = 6295 -E res.appdata.path = "/my_appdata_95"

If you have a lot of resource entires to override, you might include these in a file and use the @filename argument as noted here.

PATH, FGLLDPATH, FGLRESOURCEPATH, Web Service .xcf

Within Genero installation we provide a number of programs to perform specified tasks.  We also provide the source for these programs.  It can be tempting where these programs do not do something quite what you are after to go and modify the source for these programs, and recompile them inside the Genero installation directory.

If you do do this, then what you should be doing is leaving these installed source files and programs untouched, copy the source files, and make your own copy of the Genero programs, and include them in with the rest of your Genero applications.  Use the environment variables PATH, FGLLDPATH, FGLRESOURCEPATH so that your copy of these programs and files is found before our copy of these programs and files with the same name.

Example of such programs and potential modifications might include

• Genero programs and files found in FGLDIR/lib, where the source is in FGLDIR/src.
• Web Services shipped beneath FGLDIR/web_utilities
• Built-in Web Components that can be found in FGLDIR/webcomponents, the source in FGLDIR/src/webcomponents and the objects files in FGLDIR/lib

One to look closely at is the built-in find window where it is quite probably you will want to modify this to match the rest of your user interface.  Rather than modifying FGLDIR/src/fglfind.per and compiling it to produce a new FGLDIR/lib/fglfind.42f, you should take a copy of FGLDIR/src/fglfind.per , include it in your sources, compile and place your fglfind.42f higher up the FGLRESOURCEPATH path.   At runtime your copy will be found and used before our default in FGLDIR/lib/fglfind.42f.

Charmap alias file / Runtime System Messages

There are some places where unfortunately you may need to make changes directly to files beneath FGLDIR.

In order to map unexpected system specific locale to a standard IANA locale, you may need to edit FGLDIR/etc/charmap.alias directly as per these instructions.  .  This is very rare.

Less rare is the requirement to provide runtime system messages in different languages.  The runtime looks for the runtime system messages in FGLDIR/msg/LANG directory.  We only provide FGLDIR/msg/en_US so as per the instructions provided here  if you need runtime system messages in another language this will require you producing the .iem files and placing them here in FGLDIR/msg/LANG

GBC Customisation

Within the concept of GBC customisation, we provide theme variables and places where you can customise via stylesheets and customizing widgets.

Experienced web developers might have discovered that if there is not a customisation hook available, they can modify the source beneath GBC_PROJECT_DIR/src directly!.  When they rebuild their customisation, this modified code is used.  The problem with this technique is that you have to reapply this change every GBC maintenance release, i.e every month.

If you are doing this, we would rather you communicated to us what change you are making and our team can then investigate and find a solution where your desired behaviour can be implemented through the customisation framework as intended.

Patch, Don’t Copy

When using these techniques of having your own configuration files, a bad habit to get it into when upgrading is to simply copy them from one Genero installation to a newer Genero installation.  If you do this, you will not get any changes we have made to the standard configuration.   I covered this in an earlier Ask Reuben, Patch, Don’t Copy.

Summary

In summary, if you do find yourself modifying and compiling files in our installed products, ask yourself, is this the right thing to be doing? Is there a way I can enact this change that does not involve modifying a file inside a Genero installation.