Distributed Mode

The report engine can be started as a daemon to which report applications can connect to process reports. One or more engines can be started on the same machine or on different machines, hence distributed mode.

Distributed mode offers the following advantages:
  • Faster processing for short documents.

    The startup time of the JVM that is incurred for every report in regular mode can exceed the processing time of the report, causing the overall performance to be poor. In distributed mode, the JVM is started and initialized only once. For report batches, the improvement in performance can be dramatic; for example, in one test a 500 file PDF batch completed in 17 seconds rather than in 7 minutes.

  • Improved scalability

    Formatting graphical reports is CPU intensive. However CPU is usually expensive on the server optimized for IO that is running the DVM and/or the database. The distributed mode allows offloading the report processing entirely to another, very much cheaper, machine such as a standard PC. Such a dedicated report formatting PC could be installed with Windows™ which has the additional advantage of handling fonts and printers in a user friendlier way.

  • Ability to have the GRE and application on separate machines

    Perhaps your IT policy requires the GRE sit on a separate machine, or perhaps the required font sits on a specific machine.

Take advantage of distributed mode

To take advantage of distributed mode:
  1. Place your report design documents (.4rp) on the server where the GRE daemon runs. If your design document references images using "file: url", place these files on the same server. See Place report design documents on the daemon server.
  2. Edit the source code to reflect that distributed mode is being used. This includes providing remote connection details, handle errors, and specify the location for finished files. See Connect to a daemon using the reporting API and Logging in distributed mode.
  3. Start the GRE daemon. See Start the Genero Report Engine daemon.

Place report design documents on the daemon server

Place your report design documents (.4rp) on the server running the Genero Report Engine daemon. In addition to the report design documents, ensure that the fonts, images, and printers required for the reports are available. See Configure fonts.

Start the Genero Report Engine daemon

The daemon is invoked by calling the script $GREDIR/bin/greportwriter with the “–l” option and specifying the port it listens on. For example:
cd $GREDIR
. ./envgre
$GREDIR/bin/greportwriter -l 6500

If the Genero Report Engine daemon resides on a different machine than the DVM, you must start the daemon with the -l portname option. The -l option listens on the specified port and for each connection attempts to read an XML document from the socket. For example:

$GREDIR/bin/greportwriter -l 6500

If the Genero Report Engine daemon resides on the same machine as the DVM, or if you are using SSH port forwarding, you can optionally use the -o option. The -o option provides extra security by ensuring that the daemon accepts incoming connections only if they are local. It must be used in conjunction with the -l option, for example:

$GREDIR/bin/greportwriter –l 5900 -o

Connect to a daemon using the reporting API

The API function fgl_report_configureDistributedProcessing is used to select and configure distributed processing. It takes two parameters that denote the server to use; a host name and a port. This code shows an example for a GRE daemon running on the local machine (host “localhost”):
IF NOT fgl_report_loadCurrentSettings("OrderReport.4rp") THEN   
  ...
END IF
...
CALL fgl_report_configureDistributedProcessing("localhost",6500)
RETURN fgl_report_commitCurrentSettings()
This example connects to a daemon running on the server “PrintServer”:
IF NOT fgl_report_loadCurrentSettings("OrderReport.4rp") THEN   
  ...
END IF
...
CALL fgl_report_configureDistributedProcessing("PrintServer",6500)
RETURN fgl_report_commitCurrentSettings()
Note: If the server runs on a different physical machine with different resource paths to the DVM, you might need to configure the environment variables using the fgl_report_configureDistributedEnvironment function.

Logging in distributed mode

If the GREDEBUG environment variable is set, the daemon logs messages of the specified level to the file gre.log in the home directory of the user invoking the daemon.
Important: Sensitive and personal data may be written to the output. Make sure that the log output is written to files that can only be read by application administrators.

The API function fgl_report_setDistributedRequestingUserName can set a user name in the log file in order to distinguish between log entries originating from different users.