Printing text reports using the client’s printer and changing the printer settings

Official Content


The following is a solution to print Reports in text mode using the client’s printer in Web applications. In this scenario, the printer settings may change depending on some execution options, so the Printer Rule could be used. Also, the gxprn.ini file would be configured in most cases.

The solution is based on a printing applet (printingappletsigned.jar) that is downloaded to the client machine (so, the Java plugin of the browser is required). The applet connects to the local printer settings and sends the report to the printer. It is available for Linux and Windows platforms, either on the server or client machines.


1. Configure the text report with the following properties:

2. Use the Printer Rule if necessary.

3. To configure the gxprn.ini on the server, run GxSetFrm Utility and define the printer; you can leave the printer location undefined because it will be defined for each client machine at runtime. The gxprn.ini file on the server must be located in the virtual directory. For the Java generator, it must be located in the web app directory.

4. Configure the Show printer dialog on reports property.


In case of Linux machines the Text Report Output Property must be set to "Text" value for the Java generator.
For the .NET generator, read SAC 19564 for more information.


Any browser that runs the Java plugin supports this solution, except for Chrome, which has the following limitations:

See SAC #37605 for additional information.

See Troubleshooting tips for applications that use the browser's Java plugin

Configuring the client’s printer for printing reports

In general, you define the Printer Rule for the report and configure the  gxprn.ini file on the server. However, different combinations may exist, as explained below:

  • If there is no Printer Rule configured for the report, it will be printed in the client’s default printer.
  • If the report has the Printer Rule configured, but there is no gxprn.ini file defined on the server, the first time a report is sent to the printer, a dialog box will be displayed to configure the printer. From then on, the configuration is saved in the local gxprn.ini file located on the client machine.
  • If there is a gxprn .ini file on the server, and there is no gxprn .ini file on the client, the file is downloaded from the server to the client.

Let's explain the previous behavior in more detail.

Consider that the following rule is defined for the report:


The dialog box to configure the printer will be displayed the first time the report is executed. The dialog box allows the user to select the printer to be used. Once the printer has been selected, the dialog will not be displayed again. 

So, the dialog box will appear only the first time that the report is sent for printing. In the following printing instances, the configuration is saved on the gxprn.ini file located on the client machine.

Note 1

If the default printer is selected, the configuration in the gxprn.ini file is as follows:


If another printer is selected, the configuration is made as follows:


If the gxprn.ini file exists on the server, and there is no gxprn.ini file on the client (when the report is printed for the first time), the gxprn.ini file is downloaded to the client.

  • If the printer names are not defined for each Form, the user is asked only once, and from then on, this configuration is saved on the client machine.
  • If gxprn.ini declares the definition to the printers for each printer rule; the configured printers are used.
Note 2

For example, if the printers are not configured in the file saved on the server, we have something like the following:


Printer selection dialog box

The dialog displayed to configure the printers is the following:


Note 3

By selecting the default printer and clicking OK, the gxprn.ini file is configured with that printer and the report is sent for printing to the client's default printer:


When a printer other than the default printer is selected (Other printer), it is configured in the gxprn.ini with all the options selected for that printer. From then on, this printer will be used for all reports sent for printing (the printer selection dialog will not be displayed again).


Updating printers in the client’s machine

Once the printers are configured in the client, reports are sent for printing there, and the configuration cannot be changed.

If any configuration used by the client has to be changed, the configuration file can be edited in the client for the necessary modifications to be made.

To replace the file in the client with the file in the server, you can delete the client’s file (located in the temp directory of the client machine). The next time that a report is executed, the file saved in the server will be downloaded again (with the corresponding configurations).

Adding a new printer to the client’s machine

If a new report associated with a new printer is defined in GeneXus, the printer rule is configured when the report is defined. For example: printer('tickets_printer').

Once the change is deployed, and the client executes this new report, the first time it is run, the dialog will be displayed again to configure the new printer. Once it is configured, the client’s gxprn.ini is updated with that new printer:


This means that it is not necessary to manually add the new printer to the configuration file, because it is done the first time that the report is executed.

Note 4

What happens when there are several applications using the gxprn.ini file and clients execute them?

In this case, all printers are configured in the same gxprn.ini, so they should be identified with a prefix denoting the application they belong to.



Implementation details

  1. The .gxr (or .txt file depending on the Text report output property) is saved temporarily under the path indicated by the Blob local storage directory property on the web server. It's deleted when the web session times out.
  2. When gxprn.ini is downloaded to the client machine, it is saved under C:\Users\<user>\AppData\Local\Temp, or in the directory configured as default temp. The files rbuilder.dll and gxdib32.dll (if Text report output property = Report Viewer) are also downloaded to the temp directory
  3. Useful for troubleshooting is a trace log that is also saved under the temp directory on the client machine. The name of the log is randomly generated, like log1274971938686.log.
  4. In case of NET generator, using IIS server, it may be necessary to configure the MIME Types for .gxr, .txt and .ini.
  5. In case of Java generator, the log generated by the servlet server can be useful for troubleshooting because it leaves a trace of the errors thrown if any exception occurs.


For .NET, this feature applies as from GeneXus X Evolution 1 Upgrade 2.5. For Java, this feature applies as from GeneXus X Evolution 1 Upgrade 3. 

See Also

Another solution that does not use the printingappletsigned.jar is explained in Printing text reports on the client machine without changing the printer settings but it has limitations compared to the solution that uses the Java applet.

Was this page helpful?
What Is This?
Your feedback about this content is important. Let us know what you think.