Configuring InterSystems IRIS for PDF Output
When you print to PDF, InterSystems IRIS® uses Java to call out to a third-party PDF rendering tool. The rendering tool applies the XSLT stylesheet to the XML data and transforms the XML into XSL-FO. Finally, the tool transforms the XSL-FO into PDF.
The InterSystems IRIS installation provides a version of Apache FOP to use as the default PDF rendering engine. You can also use another rendering engine, such as XEP PDF from RenderX, or download and install FOP from Apache.
Using the Built-in PDF Rendering Engine
The PDF rendering process works only if you have performed the required configuration steps. This section discusses configuration for the built-in FOP. For information on configuring alternate PDF renderers, see the section “Using Other Rendering Engines.”
If you do not already have a Java Virtual Machine (JVM) installed on the server, download and install this tool on your system. The JVM is included in the Java Runtime Environment (JRE) and the Java Developers Kit (JDK) version 7 (also known as version 1.7) or later, so if you have either of these tools you already have a JVM. Alternatively, you may install and use OpenJDK version 8.
In order for InterSystems IRIS to find Java, you need to define the JAVA_HOME environment variable and set it to the location where you have installed Java. JAVA_HOME is described in the Java documentation.
You must ensure that user privileges are set correctly. To generate PDF output, the user must be logged into a user account that has the %System_CallOut:USE privilege.
You can create custom configuration files for the built-in FOP as described in materials on the Apache FOP Web site:
If you want the InterSystems IRIS callout to FOP to use a custom configuration file, you can set the global ^%SYS("zenreport","transformerconfig") to the path of the configuration file. Configuration files are important for adding fonts to FOP. You must first create font metrics, and then register them with FOP. The process is described on the Apache FOP web site.
If you modify the FOP configuration file fop.xconf, then an InterSystems IRIS install does not copy over it. The FOP configuration file that comes with your InterSystems IRIS distribution is named fop.xconf_dist. If your fop.xconf file becomes corrupted for any reason (such as running RenderX, which truncates the file if the parameter USEINSTALLEDFOP is not set to zero), you can revert to the file as distributed with InterSystems IRIS by copying fop.xconf_dist to fop.xconf.
PDF rendering can consume a lot of memory. If you run into trouble, you might want to modify the FOP.bat or XEP.bat file to increase the amount of memory available to the Java Virtual Machine. The respective products provide documentation that explains how to do this.
Using Other Rendering Engines
A version of Apache FOP is installed with InterSystems IRIS. If you chose to use another PDF rendering tool, you must perform the following additional configuration steps.
Install the XSL-FO to PDF rendering tool. Two of the available options are:
An open source project from Apache called FOP. You can download it from the following Web site:
To install, simply extract the files from the kit.
The XEP product from RenderX. You can download a free trial version that produces a RenderX watermark on each output page, or you can buy the XEP product. See this Web site for details:
To install, follow the instructions in the kit.
To configure InterSystems IRIS to work with RenderX XEP, you need to define a %JAVA_HOME% and a %XEP_HOME% environment variable. %JAVA_HOME% is described in the Java documentation. %XEP_HOME% is an environment variable specifying the location where you have installed XEP.
Configure InterSystems IRIS with the full pathname of the command file that invokes the rendering tool. For XEP or FOP on Windows or UNIX®, once you have installed the tool as instructed in Step 1, this command file is present on your system under the installation directory for the tool, for example C:\fop-0.95\fop.bat for Windows or /fop-0.95/fop on UNIX®.
To perform this configuration, use the Management Portal, go to Report Settings page (System Administration > Configuration > Report Servers > Settings), and make the following changes:
Path and File Name For PDF Generation: — Enter the path to the executable file. Click Browse to locate and select the command file.
Foxit / Adobe Path for Pdfprint: — Ignore this field.
Configuration File For PDF Rendering Engine: — This field is optional. Select Use or None. If you select Use, enter the path to the FOP configuration file. If you do not specify a FOP configuration file, the FOP renderer uses the configuration file supplied with the built-in FOP.
Do not enter a path in this field if you are using an XEP renderer. The XEP renderer truncates any file specified here to 0 length. Click Browse to locate and select the configuration file.
You can create custom configuration files as described by the tool provider’s Web site. To provide XEP with a custom configuration file, you need to follow the manual for XEP.
Default HotJVM Render Server Port — Enter the port number where the HotJVM Render Server is running.
Verify Now — Click this button to test whether or not the rendering tool is configured correctly.
Alternatively, start the Terminal and set the corresponding global nodes. For example, to set the renderer executable:
Set ^%SYS("zenreport","transformerpath")="/Applications/fop-0.95/fop.bat"Copy code to clipboard
Similarly, to set the configuration file, set ^%SYS("zenreport","transformerconfig") to the path of the configuration file.
The default behavior is to use the installed FOP, unless you have set an alternative renderer on the Management Portal Report Settings page (System Administration > Configuration > Report Servers > Settings).
For FOP version 0.94 or earlier
If you are using FOP version 0.94 or earlier, you must set a flag to specify that an older FOP version is the rendering tool. To do this, enter the following commands in the Terminal:
set $namespace = "%SYS" set ^%SYS("zenreport","oldfop")=1Copy code to clipboard