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.
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. 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.
  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. 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 Zen Report Settings page (System Administration > Configuration > Zen Report Settings), and make the following changes:
    Alternatively, you can enter commands to set the corresponding global at the Terminal prompt, for example, to set the renderer executable:
     Set ^%SYS("zenreport","transformerpath")="VMSIT3$DKA100:[MP.fop.build]fop1.com"
    
    To set the configuration file, set ^%SYS("zenreport","transformerconfig") to the path of the configuration file.
  3. The default behavior is to use the installed FOP, unless you have set an alternative renderer on the Management Portal Zen Report Settings page (System Administration > Configuration > Zen Reports > Settings).
  4. 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 at the Terminal prompt:
     ZN "%SYS"
     SET ^%SYS("zenreport","oldfop")=1