Using Zen Reports - InterSystems Documentation

Using Zen ReportsVersion 2008.210 October 2008InterSystems Corporation 1 Memorial Drive Cambridge MA 02142 www.intersystems.com

Using Zen ReportsCaché Version 2008.2 10 October 2008Copyright © 2008 InterSystems CorporationAll rights reserved.This book was assembled and formatted in Adobe Page Description Format (PDF) using tools and information fromthe following sources: Sun Microsystems, RenderX, Inc., Adobe Systems, and the World Wide Web Consortium atwww.w3c.org. The primary document development tools were special-purpose XML-processing applications builtby InterSystems using Caché and Java.andCaché WEBLINK, Distributed Cache Protocol, M/SQL, N/NET, and M/PACT are registered trademarks of InterSystemsCorporation.andInterSystems TrakCare, InterSystems Jalapeño Technology, Enterprise Cache Protocol, ECP, and InterSystemsZen are trademarks of InterSystems Corporation.All other brand or product names used herein are trademarks or registered trademarks of their respective companiesor organizations.This document contains trade secret and confidential information which is the property of InterSystems Corporation,One Memorial Drive, Cambridge, MA 02142, or its affiliates, and is furnished for the sole purpose of the operationand maintenance of the products of InterSystems Corporation. No part of this publication is to be used for any otherpurpose, and this publication is not to be reproduced, copied, disclosed, transmitted, stored in a retrieval system ortranslated into any human or computer language, in any form, by any means, in whole or in part, without the expressprior written consent of InterSystems Corporation.The copying, use and disposition of this document and the software programs described herein is prohibited exceptto the limited extent set forth in the standard software license agreement(s) of InterSystems Corporation coveringsuch programs and related documentation. InterSystems Corporation makes no representations and warrantiesconcerning such software programs other than those set forth in such standard software license agreement(s). Inaddition, the liability of InterSystems Corporation for any losses or damages relating to or arising out of the use ofsuch software programs is limited in the manner set forth in such standard software license agreement(s).THE FOREGOING IS A GENERAL SUMMARY OF THE RESTRICTIONS AND LIMITATIONS IMPOSED BYINTERSYSTEMS CORPORATION ON THE USE OF, AND LIABILITY ARISING FROM, ITS COMPUTERSOFTWARE. FOR COMPLETE INFORMATION REFERENCE SHOULD BE MADE TO THE STANDARD SOFTWARELICENSE AGREEMENT(S) OF INTERSYSTEMS CORPORATION, COPIES OF WHICH WILL BE MADE AVAILABLEUPON REQUEST.InterSystems Corporation disclaims responsibility for errors which may appear in this document, and it reserves theright, in its sole discretion and without notice, to make substitutions and modifications in the products and practicesdescribed in this document.For Support questions about any InterSystems products, contact:InterSystems Worldwide Customer SupportTel: +1 617 621-0700Fax: +1 617 374-9391Email: support@InterSystems.com

Table of ContentsAbout This Book ................................................................................................................................ 11 Building a Zen Report ................................................................................................................... 31.1 Preparing to Generate a Report .............................................................................................. 41.2 Creating a Zen Report Class .................................................................................................. 62 Zen Report Class Parameters ..................................................................................................... 133 XData ReportDefinition ............................................................................................................... 213.1 The %val Variable ................................................................................................................ 223.2 ................................................................................................................................ 233.3 ............................................................................................................................ 233.3.1 Attributes .................................................................................................. 233.3.2 Sibling Elements ........................................................................................................ 253.4 ............................................................................................................................ 253.5 .......................................................................................................................... 263.5.1 Built-in Aggregate Classes ......................................................................................... 273.5.2 Creating a New Aggregate Class ............................................................................... 283.6 ................................................................................................................................ 293.6.1 Attributes ..................................................................................................... 293.6.2 Building the Query ...................................................................................... 303.6.3 Break On Field or Expression .................................................................................... 333.6.4 Nested Groups ........................................................................................................... 353.6.5 Sibling Groups ........................................................................................................... 364 XData ReportDisplay ................................................................................................................... 394.1 Dimension and Size ............................................................................................................. 414.2 ................................................................................................................................ 414.3 ......................................................................................................................... 424.3.1 ....................................................................................................................... 434.3.2 .............................................................................................................. 454.3.3 .............................................................................................................. 454.4 ....................................................................................................................... 464.5 ........................................................................................................................ 464.6 ................................................................................................................................. 474.7 Layout and Display Elements .............................................................................................. 474.7.1 ...................................................................................................................... 484.7.2 ...................................................................................................................... 494.7.3 and .............................................................................................. 50Using Zen Reportsiii

4.7.4 ......................................................................................................................... 504.7.5 ........................................................................................................................ 514.7.6 ......................................................................................................................... 544.7.7 .......................................................................................................................... 554.7.8 ............................................................................................................................. 564.7.9 .............................................................................................................. 574.7.10 ..................................................................................................................... 574.8 Stylesheet Control Elements ................................................................................................ 594.8.1 ............................................................................................................................ 594.8.2 ........................................................................................................................ 604.8.3 ....................................................................................................................... 605 Charts in Zen Reports ................................................................................................................. 616 Zen Reports from a Web Browser .............................................................................................. 637 Configuring Zen for PDF Output ............................................................................................... 698 Zen Reports from a Command Line .......................................................................................... 719 Troubleshooting Zen Reports ...................................................................................................... 739.1 Solving PDF Generation Problems ...................................................................................... 739.2 Viewing Intermediate Files .................................................................................................. 759.2.1 The $LOG Query Parameter ...................................................................................... 759.2.2 The $MODE Query Parameter .................................................................................. 769.2.3 The $NODELETE Query Parameter ......................................................................... 779.2.4 The $REPORTNAME Query Parameter ................................................................... 779.2.5 The $USETEMPFILES Query Parameter ................................................................. 79Index ................................................................................................................................................. 81ivUsing Zen Reports

List of FiguresHow a Zen Report Class Produces a Report ....................................................................................... 5Using Zen Reportsv

List of TablesReport Display Attributes .................................................................................................................. 48URI Query Parameters for Zen Reports ............................................................................................ 66viUsing Zen Reports

About This BookThis book explains how to generate reports in XML, XHTML, and PDF format, based on data storedin Caché.This book contains the following sections:• “Building a Zen Report” explains how Zen reports work.• “Zen Report Class Parameters” describes how to control Zen report behavior at runtime.• “XData ReportDefinition” shows how to use XML to specify the data contents of a report.• “XData ReportDisplay” explains how to use XML to specify layout and style for a report.• “Zen Reports from a Web Browser” explains how to enter a URI to view XHTML output.• “Configuring Zen for PDF Output” explains how to enter a URI to view PDF output.• “Zen Reports from a Command Line” explains how to run a report from the Caché Terminal.• “Troubleshooting Zen Reports” describes how to generate diagnostic information for a report.There is also a detailed Table of Contents.The following books provide related information:• Using Zen provides the conceptual foundation for developing Web applications using Zen.• Using Zen Components details each of the built-in Zen components for Web application development.• Developing Zen Applications explores Web application programming issues and explains how toextend the Zen component library with custom code and client-side components.Using Zen Reports 1

1Building a Zen ReportZen provides an extensible framework for specifying database reports in XML, XHTML or PDF format.Report output in PDF format might look like the following sample.Using Zen Reports 3

Building a Zen Report1.1 Preparing to Generate a ReportZen generates a report as the result of three independent steps:1. A developer creates a Zen report class and, within it, provides two XML documents:• XData ReportDefinition describes the data• XData ReportDisplay describes the display2. The developer or end-user generates output by entering the report class URI in a browser, or byinvoking the GenerateReport method from the command line or from within the application.The type of output must be specified:• XHTML can be viewed in a browser• PDF creates printer-friendly pages3. The report class guides the data and display information through one of the two processingsequences shown in the following figure: XHTML or PDF.4 Using Zen Reports

How a Zen Report Class Produces a ReportPreparing to Generate a ReportThe two main processing sequences for Zen reports are as follows:To XHTMLTo PDFFor XHTML output, XData ReportDefinition causes a query to be run. Zen formats the datafrom this query as XML. Meanwhile, XData ReportDisplay generates an XSLT transformationcalled the To-HTML stylesheet. Zen applies this XSLT transformation to the XML file. Theresult is the XHTML output file.For PDF output, XData ReportDefinition causes a query to be run. Zen formats the data fromthis query as XML. Meanwhile, XData ReportDisplay generates an XSLT transformationcalled the To-XSLFO stylesheet. Zen sends this XSLT transformation and the XML file toa third-party rendering tool, which uses them to generate a report in XSL-FO format. Thethird-party tool then renders the XSL-FO as PDF.Using Zen Reports 5

Building a Zen Report14. Compile the class and view the report. The XML output appears as follows. Each element now includes an attribute, name, whose value is the SalesRep field returned by the SQLquery:15. Add an element to the group within XData ReportDefinition:16. Compile the class and view the report. The XML output appears as follows. Each element now includes an element called . The value within is the sum of all theNum field values for the corresponding SalesRep field returned by the SQL query:83377498382682482517. Add more , , and elements within XData ReportDefinition:8 Using Zen Reports

18. Compile the class and view the report. The XML output now displays a much larger data set foreach sales person. The aggregate elements , , and appear at the end ofeach record.19. Now that you have structured the report data as XML, you can specify how to display this datain XHTML or PDF format.Find the following text in the XData ReportDisplay block. Place the cursor between this commentand the closing element:20. At the cursor position, add a element to enclose the display items within the report. Withinthe place a that displays a title for the report. Also add the title attribute to the element to set the title of the browser window:Tutorial Sales Report21. Change the DEFAULTMODE class parameter value from "xml" to "html".22. Compile the class and view the report.23. Add a table to XData ReportDisplay as follows:Creating a Zen Report ClassUsing Zen Reports 9

Building a Zen ReportTutorial Sales ReportWhere:• is a reference to the element in the generatedXML.• is the syntax for referring to the attribute name.• is the syntax for referring to the element .24. Compile the class and view the report.25. Highlight the heading by formatting it using a pre-defined style class. Change the element inXData ReportDisplay as follows:Tutorial Sales Report26. Compile the class and view the report.27. Consider adding the following display modifications within XData ReportDisplay. Some of thesechanges affect style and layout; others add data to the display:Tutorial Sales Report10 Using Zen Reports

Creating a Zen Report Class28. Compile the class and view the report.Using Zen Reports 11

2Zen Report Class ParametersA Zen report class offers the class parameters listed in this chapter. It also has the same class parametersas a CSP page, including the PRIVATE parameter, which plays an important role. For details aboutCSP page class parameters, see the book Using Caché Server Pages (CSP).Note:Both Zen pages and Zen reports are CSP pages, but a Zen report is not a Zen page. None ofthe Zen page class parameters apply to Zen report classes.When invoked in the browser to generate XHTML, a Zen report generates XML, sends this XML tothe client, then transforms this XML to XHTML on the client by following an xml-stylesheetprocessing instruction. The attributes for this instruction appear as query parameters in a URI stringsend to the browser. Internet Explorer only understands URI instructions that have one parameter afterthe ? question mark. Problems can occur when the generated xml-stylesheet instructions for aZen report class contains multiple parameters and the browser is Internet Explorer.For this reason, many of the Zen report class parameters provide the information needed inxml-stylesheet processing instructions, so that this information does not need to appear in theURI query string. Once you have correctly configured the class parameters, Zen handles theseinstructions appropriately, regardless of the browser. The following list highlights class parameters ofthis type by labeling them as stylesheet parameters.Note:For information about how to supply report options as URI query parameters, and how tohandle side effects that may occur in some browsers, see the chapter “Zen Reports from aWeb Browser.”APPLICATIONAssociates the Zen report with a Zen application. This association is for documentation purposesonly. It does not have any effect on the behavior of the Zen report class.Using Zen Reports 13

Zen Report Class ParametersCONTENTTYPEContributes a type attribute to the xml-stylesheet instruction in the generated XSLTfor the report; for example:DATASOURCEThe default CONTENTTYPE is text/xml .Identifies an XML document that contains the data for the Zen report. The DATASOURCEvalue can be the URI of any valid XML document. Relative URIs are handled with respectto the current URI.If DATASOURCE is an empty string, the class generates its own XML document using thespecification in its XData ReportDefinition block. If a Zen report class has both a non-empty,valid DATASOURCE string and an XData ReportDefinition block, the DATASOURCEparameter takes precedence over the XData block.The DATASOURCE string can refer to an XML document created by another Zen reportclass in the same namespace. Use the $MODE=xml query parameter to specify that you wantto use the XML output from that class, as follows:Parameter DATASOURCE="MyApp.Report.cls?$MODE=xml";When a DATASOURCE is identified, EMBEDXSL is ignored. You cannot use embeddedXSL with a data source.A user can override the current DATASOURCE setting for the report class by providing a$DATASOURCE parameter in the URI when invoking the Zen report from a browser.DEFAULTMODEIdentifies the default output mode for the report. This value is used only if the URI parameter$MODE is not specified. Possible values are:• "html" — Generate a report in XHTML format. This is the default.• "pdf" — Generate a report in PDF format.• "tohtml" — Generate a to-HTML stylesheet in XSLT format.• "toxslfo" — Generate a to-XSLFO stylesheet in XSLT format.• "xml" — Display report data in XML format.• "xslfo" — Display the XSL-FO file that is generated while producing PDF.14 Using Zen Reports

EMBEDXSLA user can override the current DEFAULTMODE setting for the report class by providing a$MODE parameter in the URI when invoking the Zen report from a browser. Basic informationabout $MODE appears at the beginning of the chapter “Zen Reports from a Web Browser.”For details, also see “The $MODE Query Parameter” in the chapter “Troubleshooting ZenReports.”A stylesheet parameter. When EMBEDXSL=1 (true) Zen generates XSL instructionsembedded within the output XHTML. The default for EMBEDXSL is 0 (false). In this caseZen generates a separate XSL file.Embedding the XSL instructions brings up the issue of uniqueness for XML elements in theoutput file. The default namespace http://www.w3.org/1999/xhtml cannot be thenamespace for all the generated XML elements if the generated XML and XSLT are combinedin a single HTTP response. To ensure fully qualified XML names, InterSystems recommendswhen you set EMBEDXSL=1 you also provide a namespace name and prefix by providingvalues for REPORTXMLNAMESPACE and REPORTXMLNAMESPACEPREFIX in theZen report class, for example:Parameter EMBEDXSL=1;Parameter REPORTXMLNAMESPACE="http://www.example.com";Parameter REPORTXMLNAMESPACEPREFIX="SR";Then the generated XML looks like the following example and the XSLT is updated to workwith this XML:2005-01-20Yoyomo Inc.2005-01-20XenaData.comYou can omit the REPORTXMLNAMESPACE or REPORTXMLNAMESPACEPREFIXparameters from the Zen report class. When EMBEDXSL=1 and these parameters are notset, they default as follows:http://www.intersytems.com/mydefaultnamespacemyZen Report Class ParametersUsing Zen Reports 15

Zen Report Class ParametersENCODINGWhen a DATASOURCE is identified, EMBEDXSL is ignored.A user can override the current EMBEDXSL setting for the report class by providing a$EMBEDXSL parameter in the URI when invoking the Zen report from a browser.Contributes an encoding attribute to the xsl:output instruction in the generated XSLTfor the report; for example:The default ENCODING is "UTF-8" .HTMLSTYLESHEETINDENTIdentifies the to-HTML stylesheet that controls XHTML output for the Zen report. This stringcan be the URI of any valid XSLT stylesheet. Relative URIs are handled with respect to thecurrent URI.If HTMLSTYLESHEET is an empty string, the class generates a to-HTML stylesheet usingthe specification in its XData ReportDisplay block. If a Zen report class has both a non-empty,valid HTMLSTYLESHEET string and an XData ReportDisplay block, the HTML-STYLESHEET parameter takes precedence over the XData block.The HTMLSTYLESHEET string can refer to a to-HTML stylesheet created by another Zenreport class in the same namespace. Use the $MODE=tohtml query parameter to specify thatyou want to use the to-HTML output from that class, as follows:Parameter HTMLSTYLESHEET="MyApp.Report.cls?$MODE=tohtml";Contributes an indent attribute to the xsl:output instruction in the generated XSLT forthe report; for example:INDENT may be "yes" or "no". The default is "no".PRESERVESPACEContributes an xsl:preserve-space instruction to the generated XSLT for the report;for example, if PRESERVESPACE="literallayout" the instruction is:There is no default PRESERVESPACE value. If none is supplied, Zen does not generate theinstruction.16 Using Zen Reports

Zen Report Class ParametersPRIVATEA CSP class parameter. When PRIVATE is set to 1, the page is private. This means it canonly be navigated to from another page within the same CSP session. For further details, see“Authentication and Encryption” in the “CSP Session Management” chapter in the bookUsing Caché Server Pages (CSP).REPORTNAMEREPORTDIRControls the filename suggested by the browser when you ask to save the final output ofrunning a Zen report in XHTML or PDF format. If you do not supply a value for theREPORTNAME, Zen uses the report class name as the filename.The location for saved Zen report output is as follows, where C:\MyCache is the name of yourinstallation directory:C:\MyCache\CSP\myApp\Where C:\MyCache is the name of your installation directory and myApp is the namespacewhere the Zen report class resides.Unlike most parameters that share a name except for the $ (dollar sign), there is no relationshipbetween REPORTNAME and the URI query parameter $REPORTNAME.Controls the directory for output files specified by “The $REPORTNAME Query Parameter,”as described in the chapter “Troubleshooting Zen Reports.”REPORTDIR works with $REPORTNAME only. It does have any interaction with theREPORTNAME class parameter.REPORTXMLNAMESPACEA stylesheet parameter. Specifies the XML namespace to be used in the generated XMLreport. This is especially important if you are using EMBEDXSL=1. There is a default name,http://www.intersytems.com/mydefaultnamespace, but you can specify yourown choice. For details, see EMBEDXSL.REPORTXMLNAMESPACEPREFIXSTRIPSPACEA stylesheet parameter. Specifies the XML namespace prefix to be used in the generatedXML report. This is especially important if you are using EMBEDXSL=1. There is a defaultprefix, my, but you can specify your own choice. For details, see EMBEDXSL.Contributes an xsl:strip-space instruction to the generated XSLT for the report; forexample, if STRIPSPACE="*" the instruction is:Using Zen Reports 17

Zen Report Class ParametersThere is no default STRIPSPACE value. If none is supplied, Zen does not generate theinstruction.STYLESHEETDEFAULTMODEA stylesheet parameter. Allows you to specify the processing mode if the URI parameter$MODE is not specified.You must use DEFAULTMODE and STYLESHEETDEFAULTMODE carefully. If bothare set and the URI parameter $MODE is not specified, then STYLESHEETDEFAULTMODEoverrides DEFAULTMODE as the default style mode. Therefore, when you set a value forSTYLESHEETDEFAULTMODE use it carefully, as follows:To view XHTML output, use this combination:• Class parameter DEFAULTMODE may have any value• Class parameter STYLESHEETDEFAULTMODE="tohtml"• URI query string parameter $MODE="html"To view PDF output, use this combination:• Class parameter DEFAULTMODE may have any value• Class parameter STYLESHEETDEFAULTMODE="toxslfo"• URI query string parameter $MODE="pdf"To view report data in XML format, use this combination:• Class parameter DEFAULTMODE may have any value• Omit the class parameter STYLESHEETDEFAULTMODE• Omit $MODE, or use $MODE="xml"The full list of possible values for STYLESHEETDEFAULTMODE is:• "none" — Ignore the STYLESHEETDEFAULTMODE setting. This is the default.• "html" — XHTML format• "pdf" — PDF format• "tohtml" — To-HTML stylesheet in XSLT format• "toxslfo" — To-XSLFO stylesheet in XSLT format• "xml" — XML format• "xslfo" — Pre-display in XSL-FO format18 Using Zen Reports

Zen Report Class ParametersUSETEMPFILESA stylesheet parameter. When USETEMPFILES=1 (true) Zen writes its generated XSLTstylesheet to a file. It subsequently uses the generated XSLT stylesheet in the file to generatethe output XHMTL. The default for USETEMPFILES is 0 (false). In this case Zen generatesand uses XSLT but does not save it to a file.For further details, including the file locations for the generated XSLT stylesheet file, see“The $USETEMPFILES Query Parameter” in the chapter “Troubleshooting Zen Reports.”$USETEMPFILES is the equivalent URI query parameter for USETEMPFILES.XSLFOSTYLESHEETXSLTMODEIdentifies the to-XSLFO stylesheet that controls PDF output for the Zen report. This stringcan be the URI of any valid XSLT stylesheet. Relative URIs are handled with respect to thecurrent URI.If XSLFOSTYLESHEET is an empty string, the class generates a to-XSLFO stylesheet usingthe specification in its XData ReportDisplay block. If a Zen report class has both a non-empty,valid XSLFOSTYLESHEET string and an XData ReportDisplay block, the XSLFOS-TYLESHEET parameter takes precedence over the XData block.The XSLFOSTYLESHEET string can refer to a to-XSLFO stylesheet created by another Zenreport class in the same namespace. Use the $MODE=toxslfo query parameter to specifythat you want to use the to-XSLFO output from that class:Parameter HTMLSTYLESHEET="MyApp.Report.cls?$MODE=toxslfo";A stylesheet parameter. Allows you to specify where XSLT processing will occur, withoutadding to the number of query parameters in the URI string for the Zen report. XSLTMODEcan have the value "browser" or "server". This causes the XSLT to be processed, andXHTML to be generated, on the server or browser, respectively.XSLT processing is expensive; it could compromise the scalability of the application to shiftXSLT processing to the server. However, the XSLTMODE option is provided to allow thatflexibility. The default XSLTMODE is "browser", which means the XSLT processingoccurs on the client. Also see USETEMPFILES.A user can override the current XSLTMODE setting for the report class by providing a $XSLTparameter in the URI when invoking the Zen report from a browser.Using Zen Reports 19

3XData ReportDefinitionThe XData ReportDefinition block specifies the data to gather for the report. It also describes how toformat this data as XML. An XData ReportDefinition block may contain references to the followingvariable:• %val — the value of the field attribute in the same elementAnd may contain the following XML elements:• — Identifies the query that returns the data. There is only one at the top level. contains the following elements in any order or quantity:- — Writes an XML element to the output XML file- — Writes an XML attribute to the output XML file- — Calculates sums and averages for reporting purposes contains 0 or more of the following elements:- — Groups items together so that operations can be performed on the group.The following is a sample XData ReportDefinition block:XData ReportDefinition{

XData ReportDefinition}field="Num"class="%ZEN.Report.Aggregate.StDev"/>You can omit or override the XData ReportDefinition block if you provide a valid value for theDATASOURCE class parameter as described in the section “Zen Report Class Parameters.” If youprovide both, the DATASOURCE value takes precedence.You can also omit XData ReportDefinition if you only plan to use this Zen report class to generateXSLT stylesheets.Unlike the default XML handling of white space, Zen does not strip out newline (ASCII 10) characterswhen generating the logical XML view of a report. Carriage returns (ASCII 13) are always removed.However, if the text contents of an element contains a newline (ASCII 10), Zen wraps a CDATA blockaround the element value. This handling applies only to elements, never to attributes. XML does notallow attribute values to contain newline characters.3.1 The %val Variable%val is a variable that you can use only in an XData ReportDefinition block.You can use %val in the expression attribute for , , or . %val representsthe value of the field from the field attribute in the same element. You can see this in the following example:Or in : also supports %val. You can use %val in a breakOnExpression expression to represent thevalue of the breakOnField field.22 Using Zen Reports

3.2 The element is the top level container within an XData ReportDefinition block.Important:There is a different element for use within an XData ReportDisplay block.Within an XData ReportDefinition block, a element:• May contain zero or more , , and elements in any order, butwithout nesting.• May contain zero or more elements.• Supports the same attributes as .• Requires a name attribute.• Requires some combination of query attributes as described in the documentation for .For more detailed documentation of , see the documentation for later in this section.3.3 The element is valid within a or in an XData ReportDefinition block.Each adds an XML element to the XML document that structures the report data.3.3.1 Attributes has the attributes described in the following table.Using Zen Reports 23

XData ReportDefinitionAttributeexpressionDescriptionAn ObjectScript expression that processes the field value before outputtingit. Within the expression, the %val variable represents the field value. If youuse the %val variable in the expression, the field attribute is required tosupply a value for %val.The following example would work in a Zen report class that defined aGetDisplayURL method with one input argument:The expression attribute can be used without %val to return static data,such as the report run time in the following example:fieldSpecifies which field in the resultset to get the data from. Theresultset in question is the one returned by the query for this .The referenced field must actually exist in the resultset. An getsits resultset from the closest query among its ancestors in the XDataReportDefinition block. This is either:• The query for the or that contains the or:• The query inherited by the that contains the . Thishappens when the that contains the does not providea query of its own and instead inherits its query from the nearestancestor or . In this case, the may referenceany field in the inherited resultset, just as if the query were defined atthe same level as the that contains the .nameGenerates an XML element of this name in the output. Suppose there is afield called month in the resultset for the or that containsthis , and suppose one of the valid values for month is the stringJuly. An entry like this:Could yield an element like this in the XML that defines the data for thereport:July24 Using Zen Reports

3.3.2 Sibling ElementsThere is an extended discussion of “Sibling Groups” in the section about the element. An may also be a sibling of one or more elements at the same level of the XDataReportDefinition block. When this is the case, the that is sequentially the first sibling groupat that level has special significance for each and at that level. This iscalled the collegial group for that level.Suppose an and a are siblings. Any at this level gets its data either fromits own query, or from the query defined by its next nearest ancestor or . There ismuch more detail about this in the “Building the Query” and “Break On Field or Expression”sections of the documentation, later in this chapter.Meanwhile, any at the sibling level gets its data from the field whose containing row in theresultset satisfies the break condition of the collegial group. If an has no collegial group,its contents in the XML output consist of the value of the identified field for each row in the resultset,even if these are not distinct values.3.4 The element is valid within a or in an XData ReportDefinition block. works much like , but the data it captures is output to the XML data descriptionas an XML attribute of the containing or , rather than as an XML element. has the following attributes.AttributeexpressionDescriptionAn ObjectScript expression that processes the field value before outputtingit. Within the expression, the %val variable represents the field value. If youuse the %val variable in the expression, the field attribute is required tosupply a value for %val.The following example would work in a Zen report class that defined aGetDisplayURL method with one input argument:The expression attribute can be used without %val to return static data,such as the report run time in the following example:Using Zen Reports 25

XData ReportDefinitionAttributefieldDescriptionSpecifies which field in the resultset to get the data from. Theresultset in question is the one returned by the query for this .The referenced field must actually exist in the resultset. An getsits resultset from the query that is one level up among its ancestors in theXData ReportDefinition block. This is either:• The query for the or that contains the thatcontains this or:• The query inherited by the that contains the thatcontains the . This happens when the in questiondoes not provide a query of its own and instead inherits its query fromthe nearest ancestor or . In this case, the may reference any field in the inherited resultset.nameGenerates an XML attribute of this name in the output. Suppose there is afield called name in the resultset for the or that containsthis , and suppose one of the valid values for name is the stringJack. An entry like this:Could yield an entry like this in the XML that defines the data for the report:3.5 The element performs a calculation over every record in the resultset returned by thequery associated with a or . has the following attributes.26 Using Zen Reports

AttributeclassmethodDescriptionIf the type is CLASS, the class attribute must specify the package and classname of a class that extends %ZEN.Report.CustomAggregate.You can create your own subclasses of %ZEN.Report.CustomAggregate, orthere are several built-in aggregate classes that you can reference.If the type is CUSTOM, the method attribute must specify the name of aserver-side method within the Zen report class. The method must have thefollowing form:ClassMethod MyAgg(pMode As %String,pAccumValue As %String,pValue As %String,pCount As %Integer)As %String{Quit$Case(pMode,"Start":0,"Accum":pAccumValue+(pValue*2),"End":pAccumValue)}typeSpecifies which kind of aggregation to perform. Valid values include the followingcase-sensitive strings:• "SUM" — the sum of all values• "COUNT" — the total number of records• "AVG" — the average of all values• "MAX" — the maximum value in the set• "MIN" — the minimum value in the set• "CLASS" — (see the class attribute)• "CUSTOM" — (see the method attribute)3.5.1 Built-in Aggregate ClassesThe following are the built-in custom aggregate classes:• %ZEN.Report.Aggregate.CountDistinctThe number of distinct values in a set of data, as opposed to a simple COUNT.• %ZEN.Report.Aggregate.MedianUsing Zen Reports 27

XData ReportDefinitionThe median of a set of numerical data, as opposed to a simple AVG (average). The median is anumber with half of the data set of greater value than it, and half of lesser value.For a data set with an odd size, the median is a member of the data set. For a data set with an evensize, the median is a value halfway between two members of the data set.• %ZEN.Report.Aggregate.ModeThe statistical mode (most frequent observation) of a set of data.• %ZEN.Report.Aggregate.StDevThe standard deviation of the values processed.3.5.2 Creating a New Aggregate ClassIf you need a new type of aggregate, you can develop and use a custom aggregate class as follows:1. Subclass %ZEN.Report.CustomAggregate2. Override the following methods:• GetResult is invoked after every record has been processed to return the final value of theaggregate.• ProcessValue is called sequentially on each record returned by the report query or queries.3. Save and compile the class as myPackage.myClassName4. When referencing this calculation in the element, use these attributes:• type="CUSTOM"• class="myPackage.myClassName"The following example may be useful to you if you are creating your own aggregate class. This is thecode for the built-in custom aggregate class %ZEN.Report.Aggregate.CountDistinct, which counts thenumber of distinct values in a set of data:Class %ZEN.Report.Aggregate.CountDistinct Extends %ZEN.Report.CustomAggregate{/// Array of values processedProperty Values As array Of %String;/// Running count of distinct values processedProperty Count As %Integer [ InitialExpression = 0 ];/// Processes each new valueMethod ProcessValue(pValue As %String) As %Status{If ..Values.GetAt(pValue) {// seen it already} Else {28 Using Zen Reports

}Do ..Values.SetAt(1,pValue)Set ..Count=..Count+1}Quit $$$OK/// Return the count of distinct values processsedMethod GetResult() As %String{Quit ..Count}}3.6 Within an XData ReportDefinition block, the element indicates that Zen should perform thesame set of operations on every record in the resultset returned by the query for the group. A element contains elements and attributes that specify what to do with the records in this resultset.The syntax rules are as follows:• may not be nested inside any other element• can contain any of the same attributes or elements as • may contain multiple , , and elements in any order• , , and elements may not be nested• may contain one or more elements. For details see:- Nested Groups- Sibling GroupsA must define a query. A may define its own query, but if no query is defined fora it inherits the query from its nearest ancestor that does define a query. This ancestor mustbe a or . To learn more about the techniques for defining a query, see the topics“Building the Query” and “Break On Field or Expression,” later in this section.3.6.1 Attributes and have the general-purpose attributes listed in the following table.Using Zen Reports 29

XData ReportDefinitionAttributenameDescriptionThe generates an XML element of this name in the output.If you do not provide a value for name, the generates aname for itself based on the Zen report class name. If the group isa the name attribute is required.Aside from name, and attributes fall into two categories related to acquiring andorganizing the source data for the report. The next two topics in this section discuss them:• Building the Query• Break On Field or Expression3.6.2 Building the QueryA or requires a resultset to generate a report. A or can either:• Generate a resultset by providing the query attributes described in this topic;or:• Use the resultset generated by the query that is defined by its containing or .For details, see the section “Nested Groups.”AttributeOnCreateResultSetqueryClassqueryNameruntimeModeDescription(Optional) The name of a server-side callback method to call tocreate a %ResultSet object. The OnCreateResultSet value must bethe name of a server-only class method defined in the Zen reportclass. See the details following this table.(Optional) The name of the class containing the query. You mustalso provide a value for queryName.(Optional) The name of the class query that will provide the%ResultSet for this list. You must also provide a value forqueryClass.SQL runtime mode to apply to the %ResultSet object used to fetchresults for this report. The default runtimeMode of 2 is appropriatefor most cases and usually does not need to be changed. Possiblevalues are: 0 for LOGICAL mode, 1 for ODBC mode, and 2 forDISPLAY mode.30 Using Zen Reports

AttributesqlDescription(Optional) Server-side SQL query to get contents of the or list.This attribute has the underlying data type %ZEN.Datatype.sql. Thismeans it cannot be accessed from the client. Its value is encrypted(using the current session key) when it is sent to the client. If thisvalue is returned to the server, it is automatically decrypted. Thismakes it possible to place sensitive data on the client for futureprocessing on the server, without letting a user view this data.If you use the OnCreateResultSet attribute to specify a server-side callback method, as in this example:Then the method named by the OnCreateResultSet attribute must be defined within the page class withthe specific signature shown in the following example:ClassMethod CreateRS(ByRef pSC As %Status, ByRef pParameters) As %ResultSet{set rs = ##class(%ResultSet.SQL).%New()set sql = "SELECT Name FROM Sample.Person where Home_State=?"set pSC = rs.Prepare(sql)set pSC = rs.Execute(pParameters(1))quit rs}Where:• The callback method must instantiate and return a new instance of a %ResultSet object. Thisresultset then becomes the source of data for the or .• The callback method must return a status code by reference to indicate whether or not there wereany errors encountered in creating the %ResultSet object.• The required inbound argument pParameters is an array that, at runtime, automatically containsany values that you supplied in the or definition, such as the value"AL" for Home_State in the example above.The pParameters array is subscripted by a 1–based number that indicates the order of theseparameters in the or definition. Even if there are no elements, ifyou omit the inbound argument pParameters from the callback method signature, the resultingreport will be empty.Using Zen Reports 31

XData ReportDefinitionAlthough the OnCreateResultSet callback method signature must return a %ResultSet object, insidethe method it can be helpful to work with an object of the class %ResultSet.SQL, as shown in the previousexample. The reason is that if you create and use a %ResultSet object inside the OnCreateResultSetcallback, the resultset field names must use the same case as they do in the class. This can cause confusionand difficulty in working with the result. When you use %ResultSet.SQL, as shown in the previousexample, issues with case-sensitivity do not occur.The following is another example that demonstrates the principles outlined in this topic. Here is theexcerpt from XData ReportDefinition showing the OnCreateResultSet attribute:Here is the callback method referenced by OnCreateResultSet:ClassMethod myRS(ByRef pSC As %Status, ByRef pParameters) As %ResultSet{set sql = "SELECT Name FROM Sample.Person " _"where Home_State=? and Name Like ? ORDER BY NAME"set rs = ##class(%ResultSet.SQL).%Prepare(sql,.tError,,pParameters(1),pParameters(2))if $isobject(tError) { set pSC = tError.Status } else { set pSC = $$$OK }quit rs}The required signature for the method identified by the OnCreateResultSet attribute is different fromZen reports than it is for . However, regarding all other query attributes, Zen reports workthe same way as . For details and examples, see the following sections in the “Zen Tables”chapter of Using Zen Components:• How to use query attributes with or :- Specifying an SQL Query (sql)- Referencing a Class Query (queryClass, queryName)• How to provide elements within or :- Query ParametersAdditional rules for processing the results of the query for a or are as follows:• Any references to a non-existent field returns an empty string (that is, "") rather than triggering a“not found” error.• If a or has a query and contains an , the value of the printsout for each row that satisfies the query.32 Using Zen Reports

• When a or contains a query with parameters and its parent is a sibling, theparameters refer to the values they have in the parent, which are the values they had in the firstsibling in that parent’s group, before that first sibling encountered a break.• When a group is a nested group, it gets a row of data for each row in its parent group, regardlessof whether that row meets any break condition. That is, a parent group gives all its data to eachof its child groups, whether or not a break condition has been met.• A sibling group only gets data after a break condition has been met, and uses the data that existedin the row just before the break condition was met.• If the siblings within a group contain elements, Zen correctly recognizes aggregateson any sibling in the group. The sibling does not need to be the first sibling in the group.3.6.3 Break On Field or ExpressionThe or can organize its resultset by providing breakOnExpression and breakOnFieldattributes. These attributes tell the or how to organize the records that it has retrievedfrom the resultset. To “break on” an item means to “group the records in the resultset according tothe value of” this item. An example would be to list sales by month, graduates by fraternity house,and so on. If no “break on” item is supplied, the processes every record in the resultset inthe same way, without breaking or grouping the records.The “break on” item is either:• A field in the resultset. Use the breakOnField attribute to identify this field using its name in thequery that controls the group. The group then organizes its records according to the value of thisfield;or:• An expression that calculates a value based on a field in the resultset. Use the breakOnExpressionattribute to specify this expression. If you use breakOnExpression, you must also supply abreakOnField to identify the field whose value is the input argument for that expression. Withinthe breakOnExpression, use the keyword %val to represents this field’s value. The group thenorganizes its records according to the value calculated by the expression.For example, suppose you want to group by month, and you have a method in the Zen report classcalled GetMonth which accepts a date as an input argument and returns a value indicating the month.Then you could set breakOnField to the resultset field that contains the date, and use breakOnExpressionto calculate the month that you want to use to group the records, like this:Using Zen Reports 33

XData ReportDefinitionAttributebreakOnExpressionbreakOnFieldDescriptionbreakOnExpression provides an ObjectScript expression to applyto the value of the field specified by breakOnField. In theexpression, %val represents the value of the breakOnField field.Identifies a field in the resultset, such that all of the records thatcontain the same value in this field will be processed together.If you set the breakOnField attribute for a that is nested inside another or ,the field that you specify for breakOnField must be a field in the query for the containing or, not the nested . That is, when looking for a breakOnField value to assign to thenested , you must look one level up, to the parent, to find the field on which to break the outputfor the nested .In the following example, the group named salesRep3ab is incorrect, because SSN is a field in thequery for the current group:In the following example, the group named salesRep3ab is correct, because HOME_CITY is a fieldin the query for the containing group, salesRep3a:34 Using Zen Reports

If you set the breakOnField attribute for a that is nested inside another or ,the query in the containing or should ORDER BY the field that you identify as thebreakOnField for the nested . This is because field breaking examines the resultset sequentially,and creates a break whenever the specified field changes, so if the query is not ordered by thebreakOnField, a break may occur unexpectedly in the output for the nested . The previousexample is correct in this regard.3.6.4 Nested GroupsA may contain one or more elements, each of which may also contain one or more elements. The resulting report is said to contain nested groups. Any number of levels ofnesting is supported. A group’s level indicates how deeply nested the group is from the top of thereport definition.There are two major techniques for setting up the queries for nested groups. A Zen report can:• Define one query in the parent group and have the grouping levels break on columns within thisquery;or:• Define one query in the parent group and also define additional queries at the lower group levels.In this case the query for each child group is typically fed some parameter from the query for itsparent. The child query is executed once for each new breaking value from the parent query. Thefollowing code provides an example of this convention:...Important:When processing a group, any data that does not match the break condition is passedto any nested groups.When you use nested groups in Zen reports, references to fields within queries are resolved accordingto the following set of rules:• Every (including the outer ) defines a query context at that group’s level.• If a child does not define a new query, it uses its parent group’s query as if it was itsown.• References to fields within a , , or element are resolved bylooking at the query one level up from the current element.• References to fields within an or element are resolved by looking at thequery at the same level as the current element.Using Zen Reports 35

XData ReportDefinitionThe following are some examples of resolving references to fields within queries:• Name comes from Table1:...• Name is unresolved and gives an error:...• Name comes from Table2:...• Name comes from Table1:Table1...To correctly process the data results returned by nested groups, review the rules in the section“Building the Query.” Also see the next section, “Sibling Groups.”3.6.5 Sibling GroupsWhen a report contains nested groups, each contained is called a child of the thatcontains it; the containing is called the parent of the elements that it contains.Multiple elements may exist at each level of nesting, except at the top level, where there isonly one element. Any elements that are contained within the same parent ,at the same level, are called siblings.There are two major techniques for setting up queries for sibling groups:• Each sibling defines its own query, referring to a breaking field from the parent query in theWHERE clause;or:• None of the siblings defines a query. In this case, the first sibling tests for break conditions andoutputs its records, then the subsequent siblings are processed using the same break field.36 Using Zen Reports

Important:Breaking columns only apply to the first sibling. The attributes breakOnField andbreakOnExpression are ignored for any that is not the first in sequential orderamong its siblings.To understand the sibling rules, start with an example in which there are no siblings. There is a parentquery and a breaking group:...This example outputs one node per distinct City, for example:...Now, as a test case, add a copy of the first group as a second sibling. Change some names so the groupsare distinct. This produces an example that illustrates the case where there are siblings, but none ofthe siblings defines a query:...Now each group is processed for each distinct City, giving results something like this:...Now define a query for each sibling group. In this case, the group query is executed for each siblingusing the current breaking value of the outer query:Using Zen Reports 37

XData ReportDefinition...In this case, the group query is executed for each sibling using the current breaking value of the outerquery:Note:As a convenience, Zen defines a special variable, %node(level) to be equal to the sequentialnumber of the current sibling at the given grouping level, beginning at 1 for the first sibling.You can use this variable within an ObjectScript expression in an XData ReportDefinitionblock, for example:To correctly process the data results returned by sibling groups, review the rules in the section“Building the Query.” Also see the previous section, “Nested Groups,” and the discussionof sibling elements in the topic.38 Using Zen Reports

4XData ReportDisplayThe “XData ReportDefinition” section explained how to structure the XML data upon which the Zenreport is based. This section explains how to write a specification for displaying this data. The specificationconsists of an XData ReportDisplay block in the Zen report class.Styles in the XData ReportDisplay block are independent of the output format. At runtime, the choiceof format depends on a parameter supplied by the caller in one of the following ways:• In a browser URI string. See the section “Zen Reports from a Web Browser.”• At the Terminal command line. See the section “Zen Reports from the Command Line.”The exact value of the parameter depends on whether it is being used in the browser or at the commandline. However, its meaning is the same in each environment. It instructs the Zen report class to createreport output in one of the following formats:• XHTML — The Zen report class creates an XSLT stylesheet and uses this stylesheet to transformsits XML data into an XHTML report.• PDF — The Zen report class creates an XSLT stylesheet, then passes this XSLT stylesheet andthe XML data file to a third-party rendering tool, which produces XSL-FO and then PDF output.An XData ReportDisplay block may contain the following XML elements:• — Identifies the title. Contains these elements (in the following order):- — general page characteristics, primarily for PDF output- — page headers, used in PDF and optionally in HTML- — page footers, used in PDF only- — the container for elements that control:• Graphical layout. See the section “Layout and Display Elements.”Using Zen Reports 39

XData ReportDisplay• Style and appearance. See the section “Stylesheet Control Elements.”The following is a simple example that uses very few of the available elements:XData ReportDisplay{Tests}You can omit the XData ReportDisplay block entirely, if you provide a valid value for the HTML-STYLESHEET and XSLFOSTYLESHEET class parameters. For details, see the section “Zen ReportClass Parameters.” If you provide both an XData ReportDisplay block and parameter values, theparameter values take precedence.40 Using Zen Reports

Dimension and SizeYou can also omit XData ReportDisplay if you only plan to use this Zen report class to generate XMLdata files.4.1 Dimension and SizeAn XData ReportDisplay block allows you to specify sizes (widths, heights, lengths, etc.) in a varietyof units, just as you would in HTML or XSL-FO syntax. 2in, 5cm, 12px, 14pt, 3em, or 75% are allvalid sizes. Generally, Zen measures percentage values with respect to the containing element.4.2 The element is the top level container in an XData ReportDisplay block.Important:There is a different element for use within an XData ReportDefinition block.Within an XData ReportDisplay block, may contain the following elements only. It mustcontain them in the following order and quantities:• (0 or 1)• (0 or 1)• (0 or 1)• (1 is required)A element that appears in an XData ReportDisplay block has the following attributes.Using Zen Reports 41

XData ReportDisplayAttributenamestyletitleDescriptionThe report name, which should match the top-level element name in the XMLdata for the report.If the XData ReportDefinition block from the same Zen report class is usedto generate this XML, then the name attribute for the element inXData ReportDisplay should match the name attribute for the elementin XData ReportDefinition.If style="none", the standard Zen stylesheet is not rendered, otherwise it is.The standard stylesheet is a collection of available style classes that includesp.banner1, table.table1, td.table1, th.table1, ..., th.table6, as well as table, td,and th.grid.For more on style classes, see the element.The report title, used for items such as the PDF filename or XHTML pagetitle.Although you can enter ordinary text for this attribute, it has the underlyingdata type %ZEN.Datatype.caption. This makes it easy to localize its text intoother languages, as long as a language DOMAIN parameter is defined in theZen report class. The %ZEN.Datatype.caption data type also enables you touse $$$Text macros when you assign values to the title property from clientsideor server-side code.4.3 The element applies primarily to PDF output. specifies physical layoutcharacteristics such as page dimensions and margins. can contain multiple ,, and elements for custom styling.The element can be omitted from a , even if PDF output is intended. The resultin this case is an 8.5x11 inch page with 1.25–inch left and right margins and 1–inch top and bottommargins.If more than one element is included in the , all but the first are ignored. has the following attributes.42 Using Zen Reports

AttributefooterHeightheaderHeightheightmarginBottommarginLeftDescriptionLike headerHeight, but refers to the .HTML length value that specifies a block of empty space to be reservedbeneath the top margin, but above the main body of the report.headerHeight should be specified if this report has a element indicating a header to appear on every page.HTML length value that specifies the page height.HTML length value that specifies the bottom marginHTML length value that specifies the left margin.The margin is containedwithin the width of the page, so the width of the available area of thepage is:width - (marginLeft + marginRight)marginRightmarginTopwidthHTML length value that specifies the right margin.HTML length value that specifies the top marginHTML length value that specifies the page width.4.3.1 The element renders style information into a CSS class in the XHTML report, and intoequivalent XSLT stylesheet information for the PDF report. elements can only occur as children of . Multiple elements may be present.Each element has the attribute listed in the following table.Using Zen Reports 43

XData ReportDisplayAttributenameDescriptionIdentifies a style class. Style class names are of the form tag.class, as incascading style sheets (CSS). Possible names include:• table (referring to general table layout)• th (table header cells)• td (table cells)• a (links)• p (paragraphs)For more information about style classes, see the class attribute asdescribed in the “Report Display Attributes” table in the section “Layoutand Display Elements.”The element contains elements that specify the styling information for the class. can only occur as a child of . It specifies a piece of style information for that class. hasthe following attributes.AttributenamevalueDescriptionThe attribute name. This corresponds to a CSS attribute name (color,background-color, font-size, font-family, width, etc). Zen simply passes the attributes on to CSS and XSL-FO, so the user can specify anything; itis up to the browser or PDF rendering tool to be able to interpret the attribute.The value to assign to the attribute.To provide the equivalent of the CSS document fragment given here:th.myTable {background-color: blue;color: white;}The following element is needed:44 Using Zen Reports

4.3.2 The element applies to XHTML output only. When producing the XSLT stylesheet forPDF output, the class simply ignores any elements.Multiple elements may be present within a element. Each element has has the attribute listed in the following table.AttributehrefDescriptionURI of an external CSS stylesheet to include in the HTML stylesheet.The href string can be a comma-separated list of URIs, and each will beincluded; this the same as providing multiple elements.Some browsers struggle when the file referenced does not end in .css.4.3.3 The element applies to the XSLT stylesheet for PDF output only. When producing theHTML version of the report, the class simply ignores any elements.Multiple elements may be present within a element. Each element has the attribute listed in the following table.AttributehrefDescriptionFilename of an external XSLT file to include in the to-XSLFO stylesheet.This feature is potentially very powerful, but XSLT can be difficult to write.In practice, the main purpose of the element is for the externalXSLT stylesheet to contain elements, which can do thesame work as CSS classes.To continue the previous example, to import the th.myTable class from external files, the element would look something like this:With myStyle.css containing:Using Zen Reports 45

XData ReportDisplayth.myTable {background-color: blue;color: white;}And myStyle.xsl containing:bluewhite4.4 The element, if present in the , must occur before the element. can contain the same layout and display elements as . See the list of elementsin the section “Layout and Display Elements.” However, everything contained within the is rendered in the blank space provided by the element headerHeight attribute. If youwant your report to display a page header in the PDF report output, you must provide all of the followingin your XData ReportDisplay block:• A element with a headerHeight value• A elementXHTML reports do not support page-by-page headers, so in XHTML reports the contents of are simply rendered at the beginning of the report.4.5 The element, if present in the , must occur before the element. can contain the same layout and display elements as . See the list of elements inthe section “Layout and Display Elements.” However, everything contained within the is rendered in the blank space provided by the element footerHeight attribute. If you wantyour report to display a page footer in the PDF report output, you must provide all of the following inyour XData ReportDisplay block:• A element with a footerHeight value• A elementXHTML reports do not display elements at all.46 Using Zen Reports

4.6 The element is the required child of . It has no attributes, but contains the bulk of thereport information. contains elements that control:• Graphical layout. See the section “Layout and Display Elements.”• Style and appearance. See the section “Stylesheet Control Elements.”4.7 Layout and Display ElementsThis topic describes the elements that display the visual content of the report. Any of these elementsmay be a child of , , , , or . The elements are:• — Bar chart• — Group of items for a table row or column• — Group of items for a page footer• — Group of items for repeated actions• — Group of items for a page header• — Image• — Data value• — Horizontal line• — Line chart• — Bulleted or numbered list• — Text string of any length• — Page break• — Pie chart• — TableEach of these elements has the three attributes described in the following table. It may have otherattributes also.Using Zen Reports 47

XData ReportDisplayReport Display AttributesAttributeclassDescriptionCSS style class to apply to the element. Style classes are defined by the element, and some are given by the standard style sheet.When specifying a value for the class attribute, do not include the elementname that is given when creating the class. For example, if you have a styleclass named table.myTable that you want to use, in the specify:Parent elements propagate their class attribute value to children that do nothave a class specified. So if you define table.myTable, th.myTable, andtd.myTable, you only need to give the element a class attribute.Youcan even put a class attribute on the element to give a class forevery element in the report (at least, for those that do not override it with aclass attribute of their own).styleSimilar to the style attribute in CSS, this attribute may provide a semicolondelimitedlist of attribute:value pairs. For example:style="fill: yellow; font-size: 6pt ;"Information contained within the style attribute takes precedence over styleinformation given by the class.widthHTML length value that defines the element’s width. The exact meaningdepend on the individual element. If widths are omitted, the PDF renderingtool can produce unexpected results.4.7.1 The element renders all of its child elements sequentially. It can be used anywhere in the as a kind of spanning element, but it is most useful as a container within a . In general,a treats every child element as a new row or column, so the element can be used togroup multiple elements into a single row or column. For the list of elements that can contain,see the section “Layout and Display Elements.” has the following attributes.48 Using Zen Reports

Layout and Display ElementsAttributeDisplayattributescaptionDescriptionFor descriptions of style, width, and class, see the “Report Display Attributes”table in the section “Layout and Display Elements.”(Optional) Caption text for this block.Although you can enter ordinary text for this attribute, it has the underlyingdata type %ZEN.Datatype.caption. This makes it easy to localize its text intoother languages, as long as a language DOMAIN parameter is defined inthe Zen report class. The %ZEN.Datatype.caption data type also enables youto use $$$Text macros when you assign values to the caption property fromclient-side or server-side code.4.7.2 Within an XData ReportDisplay block, the element allows the Zen report class to respond tothe hierarchically structured data that is typical of XML.Important:There is a different element for use within an XData ReportDefinition block. has the following attributes in XData ReportDisplay.AttributeDisplayattributescaptionlineDescriptionFor descriptions of style, width, and class, see the “Report DisplayAttributes” table in the section “Layout and Display Elements.”(Optional) Caption text for this group.Although you can enter ordinary text for this attribute, it has the underlyingdata type %ZEN.Datatype.caption. This makes it easy to localize its text intoother languages, as long as a language DOMAIN parameter is defined inthe Zen report class. The %ZEN.Datatype.caption data type also enables youto use $$$Text macros when you assign values to the caption property fromclient-side or server-side code.HTML length value that specifies the thickness of the line to be drawnbetween each iteration of the group. If line is 0, no line is drawn.Using Zen Reports 49

XData ReportDisplayAttributenameDescriptionRequired. displays the contents of each element in the XML datawhose name matches this attribute. So if your XML data contains elements, your XData ReportDisplay block could contain:...The elements within the container determine how the displayhandles the data within the container. can containthe same elements as . See the list of elements in the section“Layout and Display Elements.” elements can be nested. Suppose each elementscontains multiple elements. To specify how to display each salewithin the display for each sales representative, you would provide somethinglike:......To display a group as a table, see the group attribute of .pagebreakIf true, put a page break after each iteration of the group.This attribute has the underlying data type %ZEN.Datatype.boolean. It has thevalue "true" or "false" in XData Contents, 1 or 0 in server-side code, true orfalse in client-side code.4.7.3 and The and elements are simple containers used for clarity, but they can be useful toorganize style within the report. Each can propagate its class attribute to its children. and each have the common display attributes style, width, and class. For descriptions,see the “Report Display Attributes” table in the section “Layout and Display Elements.”4.7.4 The element inserts an image into the report. has the following attributes.50 Using Zen Reports

Layout and Display ElementsAttributeDisplayattributescaptionheightsrcDescriptionFor descriptions of style, width, and class, see the “Report Display Attributes”table in the section “Layout and Display Elements.”(Optional) Caption text for this image.Although you can enter ordinary text for this attribute, it has the underlyingdata type %ZEN.Datatype.caption. This makes it easy to localize its text intoother languages, as long as a language DOMAIN parameter is defined inthe Zen report class. The %ZEN.Datatype.caption data type also enables youto use $$$Text macros when you assign values to the caption property fromclient-side or server-side code.HTML length value that specifies the image height.URI of the source file for the image. This URI is relative to the subdirectoryin which CSP stores the supporting files for applications in the currentnamespace. Suppose the namespace in which the Zen report resides iscalled myNameSpace. Then there is a subdirectory called /csp/mynamespacebelow the Caché installation directory in which the image is expected toreside. If you specify:The Zen report class looks for the file myPic.jpg in the subdirectory/csp/mynamespace/images below the Caché installation directory.If the src attribute value begins with an exclamation point, it is interpretedas an XPath expression just as in the field attribute of the element.This allows you to dynamically generate URIs within the XML data, and thenuse these customized URIs as the image source.When using ! to dynamicallygenerate the image URI, the resulting string must be an absolute URI or itwill not appear in the PDF report.widthHTML length value that specifies the image width.4.7.5 The element outputs literal values or data from the XML into the report. must haveexactly one of its value, field, or special attributes specified. has the following attributes.Using Zen Reports 51

XData ReportDisplayAttributeDisplay attributesbreakOnLineFeedcaptionDescriptionFor descriptions of style, width, and class, see the “Report DisplayAttributes” table in the section “Layout and Display Elements.”If breakOnLineFeed is true, any line feeds that Zen encounterswithin element data are replaced with in HTML output and in PDF output. Line feeds are not preserved or supportedwithin attribute values, only within the text contents of XML elements.If breakOnLineFeed is false, line feeds are treated as white spaceand ignored, as is typical for XML processing. The defaultbreakOnLineFeed value is false.This attribute has the underlying data type %ZEN.Datatype.boolean.It has the value "true" or "false" in XData ReportDisplay, 1 or 0 inserver-side code, true or false in client-side code.(Optional) Caption text for this item.Although you can enter ordinary text for this attribute, it has theunderlying data type %ZEN.Datatype.caption. This makes it easy tolocalize its text into other languages, as long as a language DOMAINparameter is defined in the Zen report class. The%ZEN.Datatype.caption data type also enables you to use $$$Textmacros when you assign values to the caption property from clientsideor server-side code.52 Using Zen Reports

Layout and Display ElementsAttributefieldDescriptionIf the field attribute is specified, the renders the value of thatfield in the XML data. field is actually used as an XPath expression,so if you have the data:MegaPlexSystemsTo get the value of the id attribute you need the XPath expression:field= "@id"Whereas to obtain the value of the element you needthe XPath expression:field="customer"The field attribute is interpreted with respect to the current matched. For an within , only attributes and children of are available.formatNumberlinkString specifying the number format to use. This string uses thesame conventions as the XSLT format-number function, such as###.# for a three-digit number with one decimal place.Optional hyperlink to place around the item’s data. If the link attributebegins with an exclamation point, it is interpreted as an XPathexpression just as in the field attribute. This allows you todynamically generate URIs within the XML data, and then use thesecustomized URIs in the display. If link is specified, the item’s styleclass will use the "a" option.Using Zen Reports 53

XData ReportDisplayAttributespecialDescriptionIf the special attribute is specified, the renders a pre-definedpiece of dynamic data. Possible values for special are:• number — gives the record number within the group.• page-number — inserts the page number within a PDF report.Is rendered as '##' in XHTML.• page-count — inserts the number of pages within a PDF report.It is rendered as '##' in XHTML.• page-number-of — inserts the page number in the form '2 of18'. It is rendered as '## of ##' in XHTML.• page-number-/ — inserts the page number in the form '2/18'.It is rendered as '##/##' in XHTML.References to the total page count can be slow in extremely largePDF reports. If speed is essential and you run into problems withspeed, avoid page-count, page-number-of, and page-number-/.valueIf the value attribute is specified, the renders it as a literalvalue.Although you can enter ordinary text for this attribute, it has theunderlying data type %ZEN.Datatype.caption. This makes it easy tolocalize its text into other languages, as long as a language DOMAINparameter is defined in the Zen report class. The%ZEN.Datatype.caption data type also enables you to use $$$Textmacros when you assign values to the value property from clientsideor server-side code.4.7.6 The element inserts a line break into the report. This can either be a visible horizontal line oran empty line break. has the following attributes.AttributeDisplayattributesalignDescriptionFor descriptions of style, width, and class, see the “Report DisplayAttributes” table in the section “Layout and Display Elements.”Alignment within the report page. Possible values are "left", "right", and"center".54 Using Zen Reports

Layout and Display ElementsAttributecaptioncolorcountlengthlineHeightpatternthicknessDescription(Optional) Caption text for this line.Although you can enter ordinary text for this attribute, it has the underlyingdata type %ZEN.Datatype.caption. This makes it easy to localize its text intoother languages, as long as a language DOMAIN parameter is defined inthe Zen report class. The %ZEN.Datatype.caption data type also enables youto use $$$Text macros when you assign values to the caption property fromclient-side or server-side code.CSS color value that specifies the line color. color only applies to solid ordashed linesThe number of line breaks to draw.This is the same as repeating the element.HTML length value that specifies the line length. length only applies to solidor dashed lines.HTML length value that specifies how much space to leave for displayingthe line. This is not the same as the line thickness when pattern is "solid"or "dashed". lineHeight applies to "empty" lines as well.Despite using this attribute, line spacing can vary between XHTML andXSL-FO (that is, PDF). This can be overcome using and elements.Possible values are "empty", "solid", and "dashed"HTML length value that specifies the line thickness. The default value is1px. thickness only applies to solid or dashed lines.4.7.7 The element is used to display an itemized or ordered list within a Zen report. has thefollowing attributes.Using Zen Reports 55

XData ReportDisplayAttributeDisplayattributesgroupimagestartvaluetypeDescriptionFor descriptions of style, width, and class, see the “Report Display Attributes”table in the section “Layout and Display Elements.” For a element,the style attribute applies to its bullets or numbers.Required. group identifies the entry that provides the data for thislist. The group value in must match the name value of some in XData ReportDefinition.The URI of an image to use as a custom bullet. If you provide an imagevalue, the type attribute is ignored.The first number value for ordered lists. startvalue is always specified as aninteger. If type is "A" and startvalue is "3", the first element in the list islabeled "C".The bullet or numbering style to use for list items. Possible values are:"none", "circle", "square", "disc", "1", "A", "a", "I", "i". PDF reports do notsupport "square" or "circle".4.7.8 The element renders a block of text. It uses the "p" option for its style class. has the followingattributes.AttributeDisplayattributescaptionDescriptionFor descriptions of style, width, and class, see the “Report Display Attributes”table in the section “Layout and Display Elements.”(Optional) Caption text for this block.Although you can enter ordinary text for this attribute, it has the underlyingdata type %ZEN.Datatype.caption. This makes it easy to localize its text intoother languages, as long as a language DOMAIN parameter is defined inthe Zen report class. The %ZEN.Datatype.caption data type also enables youto use $$$Text macros when you assign values to the caption property fromclient-side or server-side code.The element is an XML projection of the Zen reports class %ZEN.Report.Display.p. If you viewthe description of this class in the online Class Reference Information, you will see that it has a propertycalled content. This is where Zen stores the text that you place in between the and elementsin XData ReportDisplay.56 Using Zen Reports

You can also programmatically change the value of the content property. If you do so, keep in mindthat this text string actually has the underlying data type %ZEN.Datatype.caption. This makes it easyto localize its text into other languages, as long as a language DOMAIN parameter is defined in theZen report class. The %ZEN.Datatype.caption data type also enables you to use $$$Text macros whenyou assign values to the content property from client-side or server-side code.4.7.9 The element inserts a page break in PDF output. It inserts a dashed line in the XHTMLreport on screen, and causes a page break when you print the XHTML report.4.7.10 Layout and Display ElementsThe element outputs a table into the report. has the following attributes.AttributeDisplayattributesalignaltcolorcaptiongroupDescriptionFor descriptions of style, width, and class, see the “Report DisplayAttributes” table in the section “Layout and Display Elements.”Aligns the table within the report. Possible values are "left," "right," and"center".CSS color value that specifies the background color of the alternate rows(2, 4, 6, etc.).This is only possible when orient is "col" and group is specified.(Optional) Caption text for this table.Although you can enter ordinary text for this attribute, it has the underlyingdata type %ZEN.Datatype.caption. This makes it easy to localize its text intoother languages, as long as a language DOMAIN parameter is defined inthe Zen report class. The %ZEN.Datatype.caption data type also enables youto use $$$Text macros when you assign values to the caption property fromclient-side or server-side code.A table can be used to display a group of data. If the group attribute isspecified, the table displays a row or column in the table for each item inthe group. If no group is specified, there is only one row or column in thetable (plus an optional header and optional footer row or column).Using Zen Reports 57

XData ReportDisplayAttributelayoutDescriptionPossible layout values are "auto" and "fixed". For PDF output, the XEPrendering tool supports both "auto" and "fixed" formats. FOP supports "fixed"only.When layout is "fixed", it is important that you specify a width for each column.The code produces a good result from minimal width information, butyou can gain closer control as follows:• If orient is "col," then each child of the table class should have a widthattribute specified.• If orient is "row", then only one child of the table needs to have its widthsspecified. However, if that element within the table has a or child element to define a header column or footer column,it is necessary that these elements also specify their width.orientEach element contained within the table is treated as either a row or column,depending on the value of the orient attribute. If orient is "row," each childelement of table will be placed in a new row. Similarly, if orient is "col" eachchild element will be placed in a new column. Possible values are "row"and "col". The default is "col".Every cell the table renders uses the "td" option for its style class, except for the header cells, whichuse "th".4.7.10.1 To include a caption for a row or column of the table, an element within a table can contain a element. The element works just like , and has the same attributes. For details, seethe section.When you place as a child of an element within a table, it indicates that the row or columnhas a header. The header text comes from the value of the element.When you have nested tables, it is possible for the inner table to have element within it, butthat does not mean the is something for that table to display. It actually refers to giving theinner table a caption within the outer table.4.7.10.2 The element is the same as , except that it creates a footer for the row or column.It is possible to place multiple elements running from left to right along the footer of aZen report. The syntax for doing this is carefully constrained. Consider the following sample XDataReportDisplay block. In this example the output display a summary in the Average, Max, and Count58 Using Zen Reports

columns, but not in the Name column. Notice that all three of the required elements appearinside the element that applies to the first element in order from left to right; thatis, the Average:XData ReportDisplay[ XMLNamespace = "http://www.intersystems.com/zen/report/display" ]{}You can also give a a text label, by using the element as shown for “Amount”in the following example.Stylesheet Control Elements4.8 Stylesheet Control ElementsThis topic describes elements within XData ReportDisplay that control the XSL stylesheet requiredto output the Zen report. The following elements are valid anywhere within the element of anXData ReportDisplay block.4.8.1 The element can contain the same elements as . See the list of elements in the section“Layout and Display Elements.” The difference is that everything contained within is renderedin the XSL-FO (that is, PDF) report only. is useful for correcting issues where the XHTML reportand PDF report do not look alike due to inherent page differences, such as page breaks. has the following attributes.Using Zen Reports 59

XData ReportDisplayAttributeDisplayattributescaptionDescriptionFor descriptions of style, width, and class, see the “Report Display Attributes”table in the section “Layout and Display Elements.”(Optional) Caption text for this block.Although you can enter ordinary text for this attribute, it has the underlyingdata type %ZEN.Datatype.caption. This makes it easy to localize its text intoother languages, as long as a language DOMAIN parameter is defined inthe Zen report class. The %ZEN.Datatype.caption data type also enables youto use $$$Text macros when you assign values to the caption property fromclient-side or server-side code.4.8.2 The element supports the same elements and attributes as , but renders its contentsin the XHTML report only.4.8.3 The element writes directly to the stylesheet, instead of to the report. The elementmay legally appear anywhere within a or element. However, can be most useful within or . For example:This is HTML! ]]>This is XSL-FO ]]>The element is an XML projection of the Zen report class %ZEN.Report.Display.write. If youview the description of this class in the online Class Reference Information, you will see that it has aproperty called content. This is where Zen stores the text that you place in between the and elements in XData ReportDisplay.You can also programmatically change the value of the content property. If you do so, keep in mindthat this text string actually has the underlying data type %ZEN.Datatype.caption. This makes it easyto localize its text into other languages, as long as a language DOMAIN parameter is defined in theZen report class. The %ZEN.Datatype.caption data type also enables you to use $$$Text macros whenyou assign values to the content property from client-side or server-side code.60 Using Zen Reports

5Charts in Zen ReportsImportant: Charts in Zen reports use SVG for graphics. Support for SVG is built into Firefox 1.5or later. If you are using Internet Explorer 6.0 or later, you must download the freeSVG Viewer from Adobe to use charts in Zen reports.The syntax for placing charts in Zen reports is identical to the syntax for placing charts on Zen pages.For details, see the “Zen Charts” chapter of Using Zen Components. There are a few exceptions tothis rule; this section describes them.Zen reports support the , , and elements only. Zen reports supportthe chartPivot attribute, but not chartStacked. does not support markers or filled linecharts in Zen reports. Also, Zen report charts are not interactive; they simply display.When used in Zen reports, the , and elements support the followingattributes:AttributeDisplayattributesChartattributesdataFieldsDescriptionFor descriptions of style, width, and class, see the “Report DisplayAttributes” table in the section “Layout and Display Elements.”For descriptions of the general-purpose attributes that apply to any chart,see the section “Chart Layout, Style, and Behavior” in the “Zen Charts”chapter of Using Zen Components. Also see the unique attributes listedin the sections that describe , , and .All charts: Comma-separated list of fields to acquire data from. If adataGroup is also provided, only the first data field in dataFields is used.Pie charts: A pie chart looks at the first field specified by dataFields andtotals the value that each series has for this field. Each series then getsa slice proportional to its percentage of the total for this field.Using Zen Reports 61

Charts in Zen ReportsAttributedataGroupseriesColorsseriesCountseriesGroupseriesNamesseriesSizeDescriptionAll charts: Specifies the group that provides the data elements for thechart.Pie charts: If dataGroup is specified, the pie chart determines the valuefor a series by summing the dataFields for each element in thedataGroup.Comma-separated list of CSS color values used for data series. Thecolors can be acquired dynamically by using the form "!fieldname".Number of data series to display on this chart. If "", this is computedautomatically from the chart’s data source.All charts: The group that provides the list of series for the chart.Pie charts: seriesGroup is required. If series were specified statically,the series would be looking at the same data, and so the pie chart wouldbe divided evenly no matter what.Comma-separated list of names used to label each data series in thelegend box. Series names can be acquired dynamically by beginningthe value with a ! character. If seriesGroup is provided, only the firstseries name field is considered.Number of items within each data series to display on this chart. Ifomitted, Zen computes this number automatically from the chart’s datasource.A or in a Zen report may contain and elements. When usedin Zen reports, and support the following attributes:AttributeAxisattributeslabelValuesDescriptionGeneral-purpose attributes for chart axes. For descriptions, see thesection “Chart Axes” in the “Zen Charts” chapter of Using ZenComponents.All charts: Comma-separated list of label values of category axes. If leftblank, the category number is used.Pie charts: labelValues cannot be specified on the chart, as pie chartsdo not have axes.62 Using Zen Reports

6Zen Reports from a Web BrowserA user can view XHTML and PDF reports in a browser by entering the URI of the Zen report .cls file.To specify the output format, the user either relies on the DEFAULTMODE class parameter in theZen report class, or provides a $MODE parameter in the query string. The following examples use$MODE:• To view the HTML report:http://localhost:57772/csp/myPath/myApp.myReport.cls?$MODE=htmlWhere 57772 is the port number assigned to the Caché server.Note:The port number in your configuration might be different. You can double-check theport number by navigating to the System Management Portal [Home] > [Configuration]> [Memory and Startup] page.The report displays in HTML format. For example:Using Zen Reports 63

Zen Reports from a Web Browser• To view the PDF report, first use the instructions in the section “Configuring Zen for PDF Output,”then provide the following URI:http://localhost:57772/csp/myPath/myApp.myReport.cls?$MODE=pdfThe report displays in PDF format. Depending on your settings, the browser might first promptyou to save the file. If so, click Save to view the PDF.• To view raw data for a report in XML format:http://localhost:57772/csp/myPath/myApp.myReport.cls?$MODE=xmlColorized XML displays in the browser. For example:64 Using Zen Reports

Zen Reports from a Web BrowserWhen invoked in the browser, a Zen report generates XML, sends this XML to the client, then transformsthis XML to XHTML on the client by following an xml-stylesheet processing instruction. Theattributes for this instruction appear as query parameters in a URI string send to the browser. InternetExplorer only understands URI instructions that have one parameter after the ? question mark. Problemscan occur when the generated xml-stylesheet instructions for a Zen report class contains multipleparameters and the browser is Internet Explorer.For this reason, many of the Zen report class parameters provide the information needed inxml-stylesheet processing instructions, so that this information does not need to appear in theURI query string. Once you have correctly configured the class parameters, Zen handles theseinstructions appropriately, regardless of the browser.Even if the user enters only one parameter, such as $MODE, when entering the URI string for a Zenreport, the subsequent processing for the report may invisibly add more parameters, or the browsermay have difficulty understanding additional parameters, as in the following cases:• The Zen report class has its CSP class parameter PRIVATE set to 1. This makes the page private.A private page can only be navigated to from another page within the same CSP session. In thiscase Caché automatically adds the CSPToken parameter to the query parameter string in the URI,so on Internet Explorer the string cannot support additional query parameters.Using Zen Reports 65

Zen Reports from a Web Browser• The Caché namespace and database associated with your Zen report has been configured withUnauthenticated access using the Enable/Disable Authentication allowed field on the [Home] >[Security Management] > [CSP Applications] page.Unauthenticated access causes a problem that Password authentication does not. Password accessrequires a user to enter a username and password before running a Zen report that is associatedwith a particular Caché namespace and database. This login transaction gives Zen the opportunityto detect that the browser supports cookies, so that when the user subsequently enters the URI ofa Zen report, multiple parameters in the query string work well.Without a login transaction, Zen has no opportunity to detect that the browser supports cookies,so that when the user subsequently enters the URI of a Zen report, additional parameters in thisquery string do not work on Internet Explorer.There are several options to handle these situations. Any one of them solves the problem:• Use the [Home] > [Security Management] > [CSP Applications] page to configure the Cachénamespace and database that contains the Zen report class with a Use Cookie for Session value ofAlways.• Use class parameter EMBEDXSL=1 in the Zen report class.• Use class parameter STYLESHEETDEFAULTMODE="tohtml" in the Zen report class.Despite problems that may occur on Internet Explorer, there are a number of query parameters availablefor use in the URI for a Zen report class. You may use them freely in Firefox. The following table liststhese query parameters and their class parameter equivalents. You can find additional details aboutany parameter using the links provided in the table, or consult the chapters “Zen Report ClassParameters” and “Troubleshooting Zen Reports.”URI Query Parameters for Zen ReportsURI QueryParameter$DATASOURCE$EMBEDXSLClass ParameterEquivalentDATASOURCEEMBEDXSLDescriptionThe URI of an XML document thatcontains the data for the Zen report.Relative URIs are handled with respectto the current URI.1 (true) or 0 (false). When true, Zengenerates XSL instructions embeddedwithin the output XHTML. The default isfalse. In this case Zen generates aseparate XSL file.66 Using Zen Reports

URI QueryParameter$LOG$MODE$NODELETE$REPORTNAME$USETEMPFILES$XSLTClass ParameterEquivalent—DEFAULTMODE; also seeSTYLESHEETDEFAULTMODE——USETEMPFILESXSLTMODEDescriptionZen Reports from a Web Browser1 (true) or 0 (false). When true, use with$MODE=html or $MODE=pdf to viewone of the intermediate files that Zengenerates.Basic information about $MODEappears at the beginning of this chapter,“Zen Reports from a Web Browser.”You may also use $MODE to viewintermediate files, as described in“Troubleshooting Zen Reports.”1 (true) or 0 (false). When true, saveintermediate files to the general Cachétemporary directory.The filename to use when savingintermediate files for diagnosticpurposes. $REPORTNAME is notrelated to REPORTNAME.1 (true) or 0 (false). When true, savegenerated XSL files in the CSP directoryfor your application on the server."browser" or "server" causes theXSLT to be processed, and output to begenerated, on the browser or server,respectively. "browser" is the default.Using Zen Reports 67

7Configuring Zen for PDF OutputWhen you load a Zen report class into a browser with a request to view the output as PDF, Caché callsout to the command line to run a third-party PDF rendering tool. The rendering tool applies the XSLTstylesheet to the XML data to transform the XML into XSL-FO. Finally, the tool transforms the XSL-FO into PDF.This works only if you have performed the required configuration steps, as follows:1. Install an 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 followingWeb site:http://xmlgraphics.apache.org/fopTo install, simply extract the files from the kit.• The XEP product from RenderX. You can download a free trial version that produces aRenderX watermark on each output page, or you can buy the XEP product. See this Web sitefor details:http://www.renderx.com/tools/xep.htmlTo install, follow the instructions in the kit.2. Even if your Zen application does not use security features, you must ensure that user privilegesare set correctly. To run a report with PDF output, the user must be logged into a user accountthat has the %System_CallOut:USE privilege.This is true even if your Zen application has enabled Unauthenticated access using theEnable/Disable Authentication allowed field on the [Home] > [Security Management] > [CSP Applications]page. In this case the UnknownUser account must have the %System_CallOut:USEprivilege.Using Zen Reports 69

Configuring Zen for PDF OutputTo configure Zen application settings of all types, see the “Zen Application Configuration” sectionin the “Zen Applications” chapter of Developing Zen Applications. For information about privilegessuch as %System_CallOut:USE, see the “Assets and Resources” chapter in the CachéSecurity Administration Guide.3. Set the Caché global ^%SYS("zenreport","transformerpath") to location of the batchfile or shell script that calls the rendering tool. Once you have installed FOP or XEP, this file isalready present on your system. Find its location, then set the global accordingly:• For FOP, something like:Set ^%SYS("zenreport","transformerpath")="C:\fop-0.95\fop.bat"• Or similarly, for XEP:Set ^%SYS("zenreport","transformerpath")="C:\XEP\XEP.bat"4. (Optional) You can create custom configuration files for FOP as described in:http://xmlgraphics.apache.org/fop/0.95/configuration.htmlIf you want the Caché callout to FOP to use a custom configuration file, you can set the global^%SYS("zenreport","transformerconfig") to the path of the configuration file. Configurationfiles are important for adding fonts to FOP. You must first create font metrics, and thenregister them with FOP. The process is described on the FOP Web site at:http://xmlgraphics.apache.org/fop/0.95/fonts.htmlNote:PDF rendering can consume a lot of memory. If you run into trouble, you might want tomodify the FOP.bat or XEP.bat file to increase the amount of memory available to the JavaVirtual Machine. The respective products provide documentation that explains how to dothis.70 Using Zen Reports

8Zen Reports from a Command LineBefore calling a Zen report class from the command line to generate a Zen report, you must first setup a %CSP.Request object so that Zen knows where to locate images, SVG files, and other items thatCSP serves to Zen reports. A command sequence looks like this:Zn "myNameSpace"Set %request = ##class(%CSP.Request).%New()Set %request.URL = myRelativeURIMinusParametersSet %request.CgiEnvs("SERVER_NAME")= myWebServerHostNameSet %request.CgiEnvs("SERVER_PORT")= myWebServerPortNumberSet report = ##class(myZenReportClass).%New()Set myStat = report.GenerateReport(myOutputFile, myMode)If 'myStat Do DecomposeStatus^%apiOBJ(myStat,.myErr) Write !,myErr(myErr) ;'Write !,myStatWhere:• myNameSpace is the namespace where you are currently working.• myRelativeURIMinusParameters is a URI that identifies the subdirectory of the Cachéinstallation directory in which CSP stores the supporting files for applications in the namespacemyNameSpace.• myWebServerHostName is a string that gives the host name.• myWebServerPortNumber is a numeric value.• myZenReportClass identifies a class in the current namespace.• The parameters in the call to GenerateReport are as follows:- myOutputFile is a string that gives the pathname of the output file.- myMode is an integer that tells Zen which type of report output to generate.Possible values include:• 0 — XMLUsing Zen Reports 71

Zen Reports from a Command Line• 1 — XHTML• 2 — PDF. This works only if you have already used the instructions in the section“Configuring Zen for PDF Output.”And for debugging purposes:• 3 — To-HTML stylesheet• 4 — To-XSLFO stylesheet- You can also provide an optional third parameter value of 1 (true):Do report.GenerateReport("C:\Temp\mySamplePDF.log",2,1)If so, the output file contains the transformation log rather than the report. This log is similarto the result in the browser when you supply the query parameter $LOG=1. If you omit thisparameter, the default is false, and no log file is created.• myStat is a status object.• myErr is an error message.A specific example might be as follows:Zn "SAMPLES"Set %request=##class(%CSP.Request).%New()Set %request.URL = "/csp/samples/ZENApp.ZenReportImageExample.cls"Set %request.CgiEnvs("SERVER_NAME")="127.0.0.1"Set %request.CgiEnvs("SERVER_PORT")=57774Set report=##class(ZENApp.ZenReportImageExample).%New()Set Status=report.GenerateReport("C:\perforce\Users\me\P62204\X.PDF",2)If 'Status Do DecomposeStatus^%apiOBJ(Status,.Err) w !,Err(Err) ;'Write !,Status72 Using Zen Reports

9Troubleshooting Zen ReportsThis chapter provides instructions for troubleshooting Zen reports. Topics include:• Solving PDF Generation Problems• Viewing Intermediate Files9.1 Solving PDF Generation ProblemsIf you are having trouble using Zen reports to generate PDF output, the problem may arise from oneof the following sources:• Incorrect configuration of Caché to point to the XSL-FO to PDF rendering tool (FOP or RenderX).For correct instructions, see the chapter “Configuring Zen for PDF Output.”• Broken installation of the renderer (FOP or RenderX).• An XSL-FO command that the XSLT processor for the renderer does not understand. Zen generatesXSL-FO following the XSL-FO standard, but not all XSLT processors are complete implementationsof the XSL-FO standard. FOP, which is free of charge, is known to be incomplete.• Syntax errors in XData ReportDisplay. The rendering engine (FOP or RenderX) can report theseas errors when Zen does not catch them on the server side.The following sample troubleshooting session explores problems with displaying a Zen report in PDFformat. In this example:• Zen is running on Caché for Macintosh• The browser is running on WindowsUsing Zen Reports 73

Troubleshooting Zen Reports• The Caché installation directory is /Applications/Cach81• The Web Server is configured on the default port, 80• The name of the Caché for Macintosh server machine is myproThese instructions assume that FOP is the XSL-FO to PDF rendering tool, but similar instructionsapply to RenderX:1. Use these Caché Terminal commands to point Caché to FOP on the Macintosh machine:zn "%SYS"Set ^%SYS("zenreport","transformerpath")="/Applications/fop-0.94/fop"2. Run the report from the browser on Windows; for example:http://mypro.local:80/csp/app/ZENApp.MyRep.cls?$MODE=pdfThe PDF report should display.If the PDF report does not display, you can test for problems in the FOP installation as follows:1. Make sure the /Applications/Cach81/mgr/temp directory on the Caché server is empty.2. Enter the following URI in the browser on Windows:http://mypro.local:80/csp/app/ZENApp.MyRep.cls?$MODE=pdf&$LOG=1&$NODELETE=13. Rename the XML and XSL output files from this run by entering the following commands on theMacintosh where Caché is installed:cd /Applications/Cache81/mgr/tempmv *.xsl test.xslmv *.xml test.xml4. While still in the /Applications/Cach81/mgr/temp directory, run FOP with the files test.xmland test.xsl, by entering the following command:/Applications/fop-0.94/fop -xml test.xml -xsl test.xsl -pdf test.pdf5. Examine the console output for any errors. If there are so many errors that they run off the consolescreen, you can redirect the console output to the file test.log as follows:/Applications/fop-0.94/fop -xml test.xml -xsl test.xsl -pdf test.pdf > test.log6. Try to view the output file test.pdf.74 Using Zen Reports

Viewing Intermediate Files9.2 Viewing Intermediate FilesSeveral URI query parameters are available to help in troubleshooting Zen reports. These parametersallow you to view and save the intermediate and final files generated by the transformation pipeline.These files might include generated XSL or XSLFO files, text files containing error messages fromthe XML parser, or the final XHTML or PDF files that result from the completed pipeline.Note:For information about how to supply report options as URI query parameters, and how tohandle side effects that may occur in some browsers, see the chapter “Zen Reports from aWeb Browser.” In that chapter, the table URI Query Parameters for Zen Reports lists allpossible URI query parameters. This chapter lists only a few of them.The diagnostic query parameters are:• $LOG — Use with $MODE=html or $MODE=pdf to view one of the intermediate files.• $MODE — Choose a value (tohtml, toxslfo, xslfo) to view one of the intermediate files.• $NODELETE — Save intermediate files to the general Caché temporary directory.• $REPORTNAME — Save intermediate files with the name and location of your choice.• $USETEMPFILES — Save generated XSL files in the CSP directory for your application.To enable diagnostic query parameters to produce a text file listing errors detected by the Saxon parser,you must configure Zen reports with the location of the Saxon .jar file. You can do this from the CachéTerminal command prompt. Depending on the version number for the Saxon parser, the requiredcommand may be:set ^%SYS("zenreport","saxjar")="c:\saxon65\saxon.jar"Or:set ^%SYS("zenreport","saxjar")="c:\saxon\saxon8.jar"The diagnostic query parameters for Zen reports produce most of the useful diagnostic files withoutthis command, but do not produce the additional messages from the Saxon parser unless you provideone of the commands described here.9.2.1 The $LOG Query ParameterWhen specifying $MODE=html or $MODE=pdf as described in “Zen Reports from a Web Browser,”you can also set the query parameter $LOG=1. This allows you to view the output of the transformationfrom XML to XHTML or the transformation from XML via XSLT to XSL-FO to PDF, respectively.For example:Using Zen Reports 75

Troubleshooting Zen Reportshttp://localhost:57772/csp/myPath/myApp.myReport.cls?$MODE=pdf&$LOG=1Where 57772 is the port number assigned to the Caché server. For example:9.2.2 The $MODE Query ParameterAs an alternative to $LOG, you can display diagnostic information for a Zen report by providing specialvalues for the $MODE query parameter when you supply the .cls URI to the browser. For example:• To view the XSLT stylesheet that turns XML into XHTML:http://localhost:57772/csp/myPath/myApp.myReport.cls?$MODE=tohtml• To view the XSLT stylesheet that turns XML into XSL-FO:http://localhost:57772/csp/myPath/myApp.myReport.cls?$MODE=toxslfo• To view the XSL-FO stylesheet before PDF rendering:http://localhost:57772/csp/myPath/myApp.myReport.cls?$MODE=xslfoWhere 57772 is the port number assigned to the Caché server. For example:76 Using Zen Reports

Viewing Intermediate Files9.2.3 The $NODELETE Query Parameter$LOG and $MODE each display only one form of output at a time, and do not save the files for laterviewing. When your processing pipeline for report output has multiple intermediate files of varioustypes, you can add the query parameter called $NODELETE to save all intermediate and final outputfiles for later viewing. Zen assigns these output files arbitrarily generated names such as2037q4XM9.xsl. You can identify the specific file you need by its time stamp and filename extension.Zen stores $NODELETE files in the following location, where C:\MyCache is the name of yourinstallation directory:C:\MyCache\Mgr\TempYou can reset this location using the [Home] > [Configuration] > [Advanced Settings] page. Select theMiscellaneous category, and in the TempDirectory row, click Edit. Enter a subdirectory name otherthan Temp. Caché creates a subdirectory of this name under the Mgr subdirectory in the Caché installationdirectory, as shown for Temp in the previous example.Important:When you change the Caché temporary directory, it changes for all Caché applications,not just for applications that use Zen reports.You can run $NODELETE during regular processing, when $MODE=html or $MODE=pdf, or youcan combine it with special values of $LOG or $MODE to save the output for further study.9.2.4 The $REPORTNAME Query ParameterThe $REPORTNAME query parameter allows you to save all files generated by the transformationpipeline with the name and location of your choice.Using Zen Reports 77

Troubleshooting Zen ReportsThe REPORTDIR class parameter specifies the location for these files in the local file system on theCaché server. If you do not supply a value for REPORTDIR, Zen stores $REPORTNAME files in theCaché temporary directory, which by default is:C:\MyCache\Mgr\TempThis default may be changed, as explained in the previous topic for $NODELETE files. To ensure thatoutput files are well organized, InterSystems recommends that you set a value for REPORTDIR if youplan to use $REPORTNAME.Important:Unlike most parameters that share a name except for the $ (dollar sign), there is norelationship between the REPORTNAME class parameter and the $REPORTNAMEquery parameter.The following is a sample $REPORTNAME session:1. Specify the following line in the Zen report class:Parameter REPORTDIR = "c:\zenout"2. Enter a line like the following in the browser address field:http://localhost:57772/csp/rpt/Re.Rpt1.cls?$MODE=html&$REPORTNAME=testeWhere:• 57772 is the port number assigned to the Caché server• Re.Rpt1.cls is your Zen report class name• rpt is the namespace where your application resides• teste is the filename you wish to use for the output3. Change to the directory you specified in step 1, and list the generated files as follows:C:\> cd zenoutC:\zenout> dirVolume in drive C has no label.Volume Serial Number is 6035-CA91Directory of C:\zenout06/19/2008 02:55 PM .06/19/2008 02:55 PM ..06/19/2008 02:55 PM 6,320 teste.htm06/19/2008 02:55 PM 559 teste.txt06/19/2008 02:55 PM 753 teste.xml06/19/2008 02:55 PM 4,892 teste.xsl4 File(s) 12,524 bytes2 Dir(s) 17,536,151,552 bytes free78 Using Zen Reports

You can run a session like this without setting the Saxon .jar location as described at the beginning ofthis section. You will still see the intermediate files, but you will see no error messages in the browserand no .txt file will be generated, so you will have no information about syntax errors from the parser.This sample session also works with $MODE=pdf. Because the FOP and RenderX rendering enginesalways produce a syntax analysis, in the PDF case the browser will always report on error messages,and you will always see a .txt file that contains a syntax report. As a commercial product, RenderXhas better syntax analysis than FOP, so it is useful to be able to run RenderX to analyze PDF generationerrors.9.2.5 The $USETEMPFILES Query ParameterWhen the $USETEMPFILES query parameter is set to 1 (true) it causes the Zen report class to writeits generated XSLT stylesheet to a file. It subsequently uses the generated XSLT stylesheet in the fileto generate the output XHMTL. The default for USETEMPFILES is 0 (false). In this case Zen generatesand uses XSLT but does not save it to a file.There are several reasons why you might use $USETEMPFILES to output the generated XSLTstylesheet when $NODELETE and $REPORTNAME are also available and provide more options.The reasons for using $USETEMPFILES are as follows:• When you are diagnosing style issues, the .xsl file may be the only file of interest.Viewing Intermediate Files• $USETEMPFILES avoids the server-side expense incurred when XSLTMODE is "server".• Zen saves the .xsl files for $USETEMPFILES in a different location for each Caché namespace.$NODELETE saves all intermediate files in the same Caché temporary directory.• Internet Explorer users are limited in the number of URI query parameters they can use wheninvoking a Zen report from the browser. These users might not be able to supply $NODELETEor $REPORTNAME as a URI query parameter in the browser address field. Unlike $NODELETEand $REPORTNAME, $USETEMPFILES has a Zen report class parameter equivalent calledUSETEMPFILES, which you can set to 1 in the Zen report class to enable the $USETEMPFILESfeature without using a URI query parameter.Important:A $USETEMPFILES query parameter supplied to the browser overrides anyvalue set for the class parameter USETEMPFILES in the Zen report class.When USETEMPFILES=1, Zen stores .xsl stylesheet files in the following location, where C:\MyCacheis the name of your installation directory and myApp is the namespace where the Zen report classresides:C:\MyCache\CSP\myApp\The following is an example of the stylesheet instruction in the generated XML. The pathname for thehref attribute is relative to the Caché installation directory. csp is the top–level directory for all CSPUsing Zen Reports 79

Troubleshooting Zen Reportsapplications. myapp is the all–lowercase namespace name, in this case myApp, and 1928b1VL6.xslis the arbitrarily assigned name of the .xsl stylesheet file:Periodically you might want to delete the generated .xsl files that Zen has saved due to $USETEMP-FILES. You can do so by issuing the following command at the Terminal prompt, or from within anObjectScript routine. In this example, ZENApp.MyReport is the full package and class name of the Zenreport class:do ##class(ZENApp.MyReport).%DeleteTempFiles()The default value for $USETEMPFILES is 0 (false).80 Using Zen Reports

IndexSymbols$DATASOURCE, 14$EMBEDXSL, 15$LOG, 75$MODE, 63, 76$NODELETE, 77$REPORTNAME, 77see also REPORTNAME$USETEMPFILES, 79$XSLT, 19%val, 22Aaggregate, 26alignline, 54table, in reports, 57altcolor, 57APPLICATION, 13att, 44attribute, 25Bblock, 48body, 47breakOnExpression, 33breakOnField, 33breakOnLineFeed, 52Ccaptionblock, 49fo, 60group, 49img, 51item, 52line, 55p, 56reports, 58table, in reports, 57chartsreports, 61classattributefor aggregate, 27in reports, 48element, in reports, 43colorline, 55contentp component, 56write component, 60CONTENTTYPE, 14count, 55cssinclude, 45DdataFields, 61dataGroup, 62DATASOURCE, 14DEFAULTMODE, 14document, 42Eelementin reports, 23EMBEDXSL, 15ENCODING, 16expressionattribute, 25element, 24Ffieldattribute, 26element, 24field attributefor item, 53fo, 59footer, 50footerHeightdocument, 43Using Zen Reports 81

formatNumber, 53Ggroupsin reportslist, 56table, 57XData ReportDefinition, 29XData ReportDisplay, 49Hheader, 50headerHeightdocument, 43heightdocument, 43img, 51hrefcssinclude, 45xslinclude, 45html elementin reports, 60HTMLSTYLESHEET, 16Iimageattribute, for list, 56img, 50INDENT, 16item, 51LlabelValues, 62layouttable, in reports, 58length, 55linebetween groups, 49for line breaks, 54lineHeight, 55linkitem, 53list, 55LOGsee $LOGMmarginBottomdocument, 43marginLeftdocument, 43marginRightdocument, 43marginTopdocument, 43methodaggregate, 27MODEsee $MODENnameatt, 44attribute, 26CSS style class, in reports, 44element, 24groupXData ReportDefinition, 30XData ReportDisplay, 50report, 42NODELETEsee $NODELETEOOnCreateResultSetgroup, in reports, 30orient, 58Pp, 56pagebreakattribute, for group, 50element, in reports, 57pagefooter, 46pageheader, 46parametersZen report class, 13pattern, 55PDFas report output, 3configuring Zen for PDF output, 69PRESERVESPACE, 1682 Using Zen Reports

PRIVATE, 17Qqueryreport, 30queryClassgroup, in reports, 30queryNamegroup, in reports, 30RREPORTDIR, 17REPORTNAME, 17see also $REPORTNAMEreports, 3common attributes, 47XData ReportDefinition, 21XData ReportDisplay, 39REPORTXMLNAMESPACE, 17REPORTXMLNAMESPACEPREFIX, 17runtimeMode, 30SseriesColorsreports, 62seriesCountreports, 62seriesGroup, 62seriesNamesreports, 62seriesSizereports, 62special, 54sqlgroup, in reports, 31srcimg, 51startvalue, 56STRIPSPACE, 17styleattributein reports, 42, 48STYLESHEETDEFAULTMODE, 18summary, 58Ttablesin reports, 57thickness, 55titlereport, 42typeaggregate, 27list, 56UUSETEMPFILES, 19Vvalsee %valvalueatt, 44item, 54Wwidthattribute, in reports, 48document, 43img, 51write, 60XXData ReportDefinition, 21XData ReportDisplay, 39XHTML, 3XSL-FO, 3XSLFOSTYLESHEET, 19xslinclude, 45XSLT, 3XSLTMODE, 19Using Zen Reports 83