docs.intersystems.com
Home  /  Application Development: Analytics Options  /  Using the Analyzer  /  Configuring InterSystems IRIS for PDF Output


Using the Analyzer
Configuring InterSystems IRIS for PDF Output
[Back] 
InterSystems: The power behind what matters   
Search:  


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. The full requirements are an Itanium platform running v8.3 or later and using an ODS-5 disk structure, which does not have to be the system disk.
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.”
  1. If you do not already have a Java Virtual Machine (JVM) and Java Developers Kit (JDK) version 1.7 or later installed, download and install these tools on your system. 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.
  2. If you are printing PDF directly via Foxit or Adobe Reader, you need to tell InterSystems IRIS where the executable file resides on the server. To do so, open the Terminal and enter the following commands:
     ZN "%SYS"
     SET ^%SYS("zenreport","adobepath")="C:\Program Files\Adobe\Reader\AcroRd32.exe"
  3. 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.
Note:
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.
  1. Install the XSL-FO to PDF rendering tool. Two of the available options are:
  2. Configure InterSystems IRIS with the full pathname of the command file that invokes the rendering tool. You can find the pathname as follows: 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 Window or /fop-0.95/fop on UNIX®.
    To configure InterSystems IRIS, open the Terminal, change to the %SYS namespace and set nodes of the configuration global as follows:
    ^%SYS("zenreport","transformerpath") Path to the executable file that invokes the rendering tool.
    ^%SYS("zenreport","adobepath") Path to the Foxit or Adobe Reader executable file on the server. Required to print PDF directly.
    ^%SYS("zenreport","transformerconfig") 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 specify a configuration file if you are using an XEP renderer.
    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.
    ^%SYS("zenreport","renderserverport") Port number where the HotJVM Render Server is running. If you specify a port number, InterSystems IRIS always uses the HotJVM running on this port.
    For example:
     Set ^%SYS("zenreport","transformerpath")="c:\test\run-fop.bat"
    
    The default behavior is to use the installed FOP if you have not set an alternative renderer.
  3. For FOP version 0.94 or earlier
    If you are using FOP version 0.94 or earlier, you must set a flag to tell InterSystems IRIS that an older FOP version is the rendering tool. To do this, enter the following commands at the Terminal prompt:
     ZN "%SYS"
     SET ^%SYS("zenreport","oldfop")=1