GAS 5.01 upgrade guide

These topics describe product changes you must be aware of when upgrading to version 5.01.

Important:

This incremental upgrade guide covers only topics related to the Genero Application Server (GAS) version specified in the page title. Check prior upgrade guides if you migrate from an earlier version, and complete the migration tasks for all versions between your existing version and the target version, in order. Make sure to also read about the new features for this version.

Corresponding new features page: GAS 5.01 new features.

Previous upgrade guide: GAS 5.00 upgrade guide

Required GAS versions for GDC 5.01.02 and later

Important:

Starting with GDC 5.01.02, GDC may send HTTP headers in any letter case (for example: X-Custom-Header, x-custom-header, X-CUSTOM-HEADER).

  • To ensure correct header handling, you must run one of the following GAS releases when using GDC 5.01.02 or newer:
    • GAS 3.21.03
    • GAS 4.01.07
    • GAS 5.01.03
  • If you do not upgrade to one of the versions above, header processing may fail, causing unexpected behavior in applications that rely on HTTP headers.

New GAS resource: res.gwa.deployment.root

To support Genero Web Application deployment on the GAS, there is a new resource, res.gwa.deployment.root, that points to a new directory in the appdata directory, $(res.appdata.path)/gwa. This resource may be used to specify the path to Genero Web Applications deployed in Genero archive (gwa) files.

For more information, go to GAS installation and application data directories and gasadmin tool.

Changes to logs when DEBUG category is set

Starting with Genero 5.01.00, user data gathered during the normal course of running applications, which may contain sensitive or personal data, is no longer written to the logs by the INFO category log filter, now it is only written when DEBUG is set. DEBUG should only be set for debugging purposes and when requested by your support center. To safeguard sensitive data, logs need to be protected from unauthorized access.

You can continue to use the INFO category as a default category for log information, without risk of gathering sensitive data.

For more information about the type of messages written to the logs by the various categories, go to CATEGORIES_FILTER and FORMAT. For more information about security recommendations, go to Security recommendations for production environment.

Allow access to static files for application and services

A DOCROOT element may be added to your application and web services configuration files (xcf) to allow end users access static files. The DOCROOT element allows you to specify a path to static resources provided in the path of an application or web service. The static files can be fetched using a specific URL:
  • Applications: 
    http[s]://host:port/ua/web[/group-name]/xcf-file/filename
  • Web services: 
    http[s]://host:port/ws/web[/group-name]/xcf-file/filename

Access to the DOCROOT resources will be verified by the GAS via the ACCESS_CONTROL element at runtime. For more information, go to DOCROOT.

New command line options to load app and service groups when starting dispatchers

Starting with Genero 5.01.01, dispatchers now support two new command line options: --application-group and --service-group. With these options, you can specify XML files with configurations for application or service groups to load with the dispatcher in addition to groups defined in the GAS configuration file (as.xcf).

Where before, you would have had to define these groups in the GAS configuration file as.xcf, now you can create separate configurations for these groups and apply them when starting the dispatcher.

For more information, go to Create application/service group and Start dispatcher with group app/service options.

New ForwardOptionsRequest attribute added to service EXECUTION element

Starting with Genero 5.01.01, the ForwardOptionsRequest is a new attribute added to EXECUTION (for service) for managing response to requests with the HTTP verb OPTIONS.
  • If set to TRUE or not present (default), the HTTP request will be forwarded to the 4GL service.
  • If set to FALSE, the HTTP request will be replied to by the dispatcher and not forwarded to the 4GL service.
Headers configured in the GAS configuration file (as.xcf) or in the service configuration file (xcf) will be added to the response in both cases.

New Method attribute added to HEADER elements

Starting with Genero 5.01.01, in an enhancement to how you manage headers in responses, the Method attribute is added to the HEADER (Dedicated) and HEADER (Common) elements. The Method attribute identifies HTTP methods when the header is to be added in HTTP responses. This attribute is optional and if set, must contain valid HTTP methods, such as GET, OPTIONS, and so on. It can take a comma-separated list of HTTP methods.

  • If the Method attribute is provided, the header will only be added to HTTP responses for the specified HTTP method.
  • If the Method attribute is not provided, the header will be added to all HTTP responses (the default behavior).

For more information and examples, go to HEADER (Dedicated) and HEADER (Common).

New resource added for GIP StarterApp access

Starting with FGLGWS versions 3.21.04, 4.01.10, and 5.01.06, you can update the res.gip.access.control resource from NOBODY to ALL to grant access to the StarterApp. This resource is defined in the GAS configuration file (as.xcf).

After setting up the GIP, remember to reset the resource back to NOBODY to restrict access and prevent users from running the StarterApp. In production, ensure that the resource is also set to NOBODY for the same reason.

For more information on using the resource, refer to the ACCESS_CONTROL page.

Retransmission requests now logged in uaproxy

Starting with GAS versions 3.21.04, 4.01.08, 5.01.04, and 6.00.01, retransmission requests are recorded in the uaproxy log. These entries use the WARNING level instead of DEBUG to indicate that a client resent a request because the original response was not received. Retransmission entries can indicate potential network issues between the user agent and GAS.

Example log entry:

18:01:12.937000 "Retransmission" uri=/ua/sua/a2e7f6512783b2f2c440c7fc0a379cca?ConnectorURI=&appId=0&pageId=6

To troubleshoot retransmission requests, go to Retransmission requests in uaproxy logs.

Log category entries added to GAS logs

Starting with GAS versions 3.21.04, 4.01.08, 5.01.04, and 6.00.01, each GAS log file (dispatcher, proxy) begins with an entry showing the current log category. GAS also adds a new entry whenever the log category changes, including when you run gasadmin reset-log. This makes it easy to confirm the active log category (for example, ALL) across all logs. 

#Version: 1.0
#Date: 2025/10/22 17:10:26.099000
#Log category: WARNING ERROR INFO

For more information about logs and filter categories, go to CATEGORIES_FILTER and Log files.

Changes to the Systemd service templates

Starting with GAS versions 3.21.04, 4.01.08, 5.01.04, and 6.00.01, the systemd service templates for Linux® have updates:
  • The User= and Group= directives are added for dispatcher processes, allowing you to specify the user and group that run the dispatcher process.
  • SELinux-related directives are included in the template as commented-out examples for environments where SELinux is enabled and enforcing.
For more details, go to Systemd service template

Changes in earlier versions

Make sure to check the upgrade notes of earlier versions, to not miss changes introduced in maintenance releases. For more details, see GAS 5.00 upgrade guide.