Using Zen Reports
Zen Report Class Parameters
[Back] [Next]
   
Server:docs2
Instance:LATEST
User:UnknownUser
 
-
Search:    

A class parameter is an ObjectScript convention that you can use in Zen report classes. For an overview, see Class Parameters in the “Caché Classes” chapter of Using Caché Objects.

A Zen report class supplies the class parameters described in the following sections:
Class Parameters for General Use
This section lists the Zen report class parameters that provide essential processing instructions for a Zen report.
Note:
A Zen report class is not a Zen page class. Therefore, none of the Zen Page Class Parameters described in the book Developing Zen Applications apply to Zen report classes. However, a Zen report class is a Caché Server Page (CSP) class. Therefore, in addition to the Zen report class parameters described in this section, a Zen report class supports all of the CSP class parameters described in the online class documentation for %CSP.Page.
APPLICATION
Associates the Zen report with a Zen application. A Zen report's application provides the default values for built-in class parameters. A value specified in the Zen Report itself takes priority over the value from the application. If you do not specify an application, the Zen report uses %ZEN.Report.defaultApplication.
If you define a new class parameter on the Zen report, there is no automatic logic to inherit the value from the Application. You need to define the parameter in both the report and the application. You can then use the macro $$$GETPARAMETER to get the value from the application, as illustrated in the following example:
/// User-defined parameter. Defined on Report and on Application.
Parameter COPYFROMAPP = "FromRpt";
Property CopyFromApp As %String(ZENURL = "CopyFromApp");
/// This callback is invoked after this report is instantiated
/// and before it is run.
Method %OnBeforeReport() As %Status
  {
    Set:..CopyFromApp="" ..CopyFromApp=$$$GETPARAMETER("COPYFROMAPP")
    Quit $$$OK
  } 
The application and the report must use the same name for the parameter. You cannot use the macro $$$GETPARAMETER to coalesce values from parameters with different names. The user-specified Application should extend %ZEN.Report.defaultApplication.
AGGREGATESIGNORENLS
Setting this parameter to true causes aggregates causes Zen reports to ignore National Language Settings (NLS) for aggregates. If it is set to false, NLS works transparently with Zen reports aggregates when the runtime mode is DISPLAY (2). The default value is true.
AGGREGATETAG
Setting this parameter enables support for aggregates in generated Excel spreadsheets. You can set it to any value that is a valid XML attribute name. The value becomes the name of an attribute that tags items in the generated XML as coming from an <aggregate> in the report. Used with DEFAULTMODE=”excel” and DEFAULTMODE=”xlsx”.
CONTENTTYPE
Contributes a type attribute to the xml-stylesheet instruction in the generated XSLT for the report; for example:
<?xml-stylesheet type="text/xsl"?>
The default CONTENTTYPE is text/xml.
DATASOURCE
Identifies an XML document that contains the data for the Zen report. See the section DATASOURCE in the chapter “Gathering Zen Report Data.”
DEFAULTMODE
Identifies the default output mode for the report. The user can override this parameter by setting $MODE in the URI.
If DEFAULTMODE is set to ps, you must also use the class parameter PS or the URI parameter $PS to provide the location of the PostScript printer.
A 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 information about $MODE appears at the beginning of the section Invoking Zen Reports from a Web Browser.” For additional information, also see Changing Output Mode to View Intermediate Files in the chapter “Troubleshooting Zen Reports.”
ENCODING
Contributes an encoding attribute to the xsl:output instruction in the generated XSLT for the report; for example:
<xsl:output method="xml" version="1.0" encoding="UTF-8" indent="no"/>
The default ENCODING is "UTF-8". If you need to display characters outside the UTF-8 character set, for example in the Latin-1 set, provide an alternate value for ENCODING such as:
Parameter ENCODING="ISO-8859-1";
EXCELMODE
Specifies whether the data for an Excel spreadsheet should come from <attribute> or <element> tags. By default, data comes from <element> tags. Use of EXCELMODE = "attribute" is not recommended, because it is inflexible and unable to carry Excel metadata. Used with DEFAULTMODE=”excel” and DEFAULTMODE=”xlsx”.
EXCELMULTISHEET
Specifies whether a Zen report that generates an Excel spreadsheet generates a spreadsheet that contains multiple worksheets. If EXCELMULTISHEET = 1, the report generates a worksheet for each <group> element that is a direct child of <report>.
EXCELSTYLESHEET
Identifies the to-excel stylesheet that controls XHTML output for the Zen report. If a Zen report class has both a non-empty, valid EXCELSTYLESHEET string and an XData ReportDisplay block, the EXCELSTYLESHEET parameter takes precedence over the XData block.
This string can be any of the following:
Warning:
Do not use a URI string that refers to the Zen report class in which the EXCELSTYLESHEET parameter appears. Doing so results in infinite recursion, which leads to an <UNDEFINED> error and the creation of hundreds of processes.
The XSLFOSTYLESHEET parameter performs the same function in reports that generate PDF output, and theHTMLSTYLESHEET parameter performs the same function in reports that generate HTML output.
HTMLSTYLESHEET
Identifies the to-HTML stylesheet that controls XHTML output for the Zen report. If a Zen report class has both a non-empty, valid HTMLSTYLESHEET string and an XData ReportDisplay block, the HTMLSTYLESHEET parameter takes precedence over the XData block.
This string can be any of the following:
Warning:
Do not use a URI string that refers to the Zen report class in which the HTMLSTYLESHEET parameter appears. Doing so results in infinite recursion, which leads to an <UNDEFINED> error and the creation of hundreds of processes.
The XSLFOSTYLESHEET parameter performs the same function in reports that generate PDF output, and the EXCELSTYLESHEET parameter performs the same function in reports that generate Excel spreadsheet output.
INDENT
Contributes an indent attribute to the xsl:output instruction in the generated XSLT for the report; for example:
<xsl:output method="xml" version="1.0" encoding="UTF-8" indent="no"/>
INDENT may be "yes" or "no". The default is "yes".
NAMESPACEDECLARATIONS
Allows you to define namespace declarations, for example:
"xmlns='http://mydefault' xmlns:ns1='http://namespace1'"
The namespace declarations are added to the root element of the generated XML and also to the stylesheet element of the generated XSL.
PDFSWITCH
Like XMLSWITCH and XSLSWITCH, PDFSWITCH helps Zen to format the command line it uses to invoke a third-party PDF rendering engine to produce PDF output. For details about PDF output, see the section Configuring Zen Reports for PDF Output.”
Usually the choice of PDF rendering engine is XEP or FOP, each of which supports the following command line option to introduce the name of the PDF output file for the transformation from XSL-FO to PDF:
-pdf
This is the default value for PDFSWITCH.
If you want Zen reports to use a PDF rendering engine other than XEP or FOP, this engine might require a different command line option to identify its PDF output file. You must specify the correct option syntax using the PDFSWITCH class parameter in your Zen report class. For example:
Parameter PDFSWITCH = "-o";
PRESERVESPACE
Contributes an xsl:preserve-space instruction to the generated XSLT for the report; for example, if PRESERVESPACE="literallayout" the instruction is:
<xsl:preserve-space elements="literallayout"/>
The value of PRESERVESPACE can be a comma-separated list of element names.
There is no default PRESERVESPACE value. If none is supplied, Zen does not generate the instruction.
PRIVATE
As described in the section Zen Report Tutorial,” a Zen report class is also a Caché Server Page (CSP) class. Therefore, a Zen report class supports the same class parameters as a CSP page class, including the PRIVATE parameter, which plays an important role in Zen reports.
When PRIVATE is set to 1, the page is private. This means it can only 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 book Using Caché Server Pages (CSP).
PS
Specifies the location of a PostScript printer, such as:
Parameter PS = "\\devD630\BrotherH";
To send a report directly to the specified PostScript printer, without creating an intervening PDF file, set the DEFAULTMODE class parameter to"ps". You can also set $MODE=ps in the URI string and set the URI query parameter $PS to the location of the PostScript printer.
REPORTNAME
(Firefox only) Controls the filename suggested by the browser when you choose File > Save As to save the final output of running a Zen report in XHTML or PDF format. If you do not supply a value for the REPORTNAME class parameter, the browser uses the Zen report class name as the suggested filename.
The location for saved Zen report output is as follows:
C:\MyCache\CSP\myApp\
Where C:\MyCache is the name of your installation directory and myApp is the namespace where the Zen report class resides.
REPORTNAME does not work with Internet Explorer, Chrome, or Safari. In these cases the <report> must have a title attribute set; that title is used in the File > Save As prompt. REPORTNAME works with Firefox when XHTML is generated on the server side. Server-side generation takes place when the output format is PDF, when XSLTMODE or $XSLT is set to "server" (the default), or when you have instructed Zen reports to embed XSLT instructions within the output XHTML by setting EMBEDXSL or $EMBEDXSL to 1.
Unlike most parameters that share a name except for the $ (dollar sign), there is no relationship between REPORTNAME and the URI query parameter $REPORTNAME.
REPORTDIR
Controls the directory for output files specified by The $REPORTNAME Query Parameter,” as described in the “Troubleshooting Zen Reports” section of the chapter “Running Zen Reports.”
REPORTDIR works with $REPORTNAME only. It does not interact with the REPORTNAME class parameter.
RESOURCE
Name of a system Resource for which the current user must hold USE privileges in order to view this page or to invoke any of its server-side methods from the client.
RESOURCE may be a comma-delimited list of resource names. In this case, the user must hold USE privileges on at least one of the given Resources in order to use the page.
For further details, see the section Application Resources in the “Assets and Resources” chapter of the Caché Security Administration Guide.
SQLCACHE
The correct processing of sibling groups and elements requires caching of SQL queries. By default, Zen reports cache SQL queries (SQLCACHE=1). If you prefer not to cache queries while running Zen reports (SQLCACHE=0), then you cannot use sibling groups and elements without generating an error when compiling the Zen report class.
STRIPSPACE
Contributes an xsl:strip-space instruction to the generated XSLT for the report; for example, if STRIPSPACE="*" the instruction is:
<xsl:strip-space elements="*"/>
There is no default STRIPSPACE value. If none is supplied, Zen does not generate the instruction.
SUPPRESSEXCELHEADERS
Set suppressExcelHeaders="true" to suppress all headers that are normally generated when you create an Excel spreadsheet from a Zen report.
TABLEALTCOLOR
Lets you set a color for alternate table rows on a report-wide basis, instead of specifying the <table> attribute altcolor on each table. You can use the corresponding TableAltColor property when using GenerateReport. If you specify altcolor on a table, the table setting overrides TABLEALTCOLOR.
USEHTML5
Lets you override the default behavior, which is to generate HTML5 when the browser supports it.
When UseHTML5 is "" (null), which is the default value, a report rendering in a browser generates HTML5 if it has determined that the browser supports HTML5. When UseHTML5 is non-null, the boolean value determines whether to generate HTML5 or not regardless of whether the browser supports HTML5. You can use the corresponding UseHTML5 property when using GenerateReport.
USEINSTANCEHOSTNAMEONRELATIVEURLS
When a Zen report is shared among several servers for load balancing purposes, and when the Zen report uses elements such as <xslinclude> that refer to other Zen or CSP pages, the external PDF rendering engine needs a way to come back to the Caché CSP Gateway instead of going all the way back to the virtual IP. The attempt to go back to the virtual IP results in an error, since the gateway does not recognize that address.
It is possible to configure a Zen report class so that it substitutes the configured instance host name for the CSP Gateway whenever it constructs a full URL from the relative paths contained in <xslinclude> and other elements that supply URLs. To enable this feature, set the USEINSTANCEHOSTNAMEONRELATIVEURLS class parameter to 1 (true). The default is 0 (false).
You can enable or disable USEINSTANCEHOSTNAMEONRELATIVEURLS without knowing or setting the instance host name for the CSP Gateway. It is rarely necessary to configure an instance host name other than the default, which identifies the local Caché server and its Web server port. For more details, see the Configuring Default Parameters section in the “CSP Gateway Operation and Configuration” chapter of CSP Gateway Configuration Guide.
XMLSTYLESHEET
Identifies the XSL stylesheet that transforms XML provided by the ReportDefinition into a form appropriate for input to the ReportDisplay.
XMLSWITCH
Like XSLSWITCH and PDFSWITCH, XMLSWITCH helps Zen to format the command line it uses to invoke a third-party PDF rendering engine to produce PDF output. For details about PDF output, see the section Configuring Zen Reports for PDF Output.”
Usually the choice of PDF rendering engine is XEP or FOP, each of which supports the following command line option to introduce the name of the XSL-FO data file for the transformation from XSL-FO to PDF:
-xml
This is the default value for XMLSWITCH.
If you want Zen reports to use a PDF rendering engine other than XEP or FOP, this engine might require a different command line option to identify its XSL-FO data file. You must specify the correct option syntax using the XMLSWITCH class parameter in your Zen report class. For example:
Parameter XMLSWITCH = "-d";
XSLFOSTYLESHEET
Identifies the to-XSLFO stylesheet that controls XHTML output for the Zen report. If a Zen report class has both a non-empty, valid XSLFOSTYLESHEET string and an XData ReportDisplay block, the XSLFOSTYLESHEET parameter takes precedence over the XData block.
This string can be any of the following:
Warning:
Do not use a URI string that refers to the Zen report class in which the XSLFOSTYLESHEET parameter appears. Doing so results in infinite recursion, which leads to an <UNDEFINED> error and the creation of hundreds of processes.
The HTMLSTYLESHEET parameter performs the same function in reports that generate HTML output, and the EXCELSTYLESHEET parameter performs the same function in reports that generate Excel spreadsheet output.
XSLSWITCH
Like XMLSWITCH and PDFSWITCH, XSLSWITCH helps Zen to format the command line it uses to invoke a third-party PDF rendering engine to produce PDF output. For details about PDF output, see the section Configuring Zen Reports for PDF Output.”
Usually the choice of PDF rendering engine is XEP or FOP, each of which supports the following command line option to introduce the name of the XSL-FO stylesheet file for the transformation from XSL-FO to PDF:
-xsl
This is the default value for XSLSWITCH.
If you want Zen reports to use a PDF rendering engine other than XEP or FOP, this engine might require a different command line option to identify its XSL-FO stylesheet file. You must specify the correct option syntax using the XSLSWITCH class parameter in your Zen report class. For example:
Parameter XSLSWITCH = "-s";
XSLTVERSION
A value of "1.0" or "2.0" causes the XSLT for this report to be processed as XSLT Version 1.0 or XSLT Version 2.0, respectively. "1.0" is the default. The XSLTVERSION value affects the XSLT that a Zen report generates as well as any that it encounters in <xslt> sections, XData blocks, or external files. A user can override the current XSLTVERSION setting for the report class by providing an $XSLTVERSION parameter in the URI when invoking the Zen report from a browser.
XSLT 1.0 is the default, and requires no special preparation. XSLT 2.0 represents significant changes from XSLT 1.0, including more careful type checking and more options for controlling the flow of logic within the transformation. XSLT 2.0 transformations are not likely to work if they are interpreted as XSLT 1.0. Problems in the other direction occur less frequently: XSLT 1.0 transformations often work when interpreted as XSLT 2.0. However, they can produce different output than when interpreted as XSLT 1.0, or fail to work. There are no compatibility guarantees.
Class Parameters for XSLT Stylesheets
This section lists the Zen report class parameters that contribute specialized XSLT processing instructions. These class parameters address problems that can occur when the browser is Internet Explorer and the Zen report class is marked as private by setting its CSP class parameter PRIVATE to 1 (True). If this is not your situation, you do not need these additional class parameters.
When invoked in the browser to generate XHTML, a Zen report generates XML, sends this XML to the client, then transforms this XML to XHTML on the client by following an xml-stylesheet processing instruction. The attributes for this instruction appear as query parameters in a URI string sent to the browser. Internet Explorer only understands URI instructions that have one parameter after the ? question mark. Problems can occur when the generated xml-stylesheet instructions for a Zen report class contains multiple parameters and the browser is Internet Explorer. This is particularly true if the Zen report class is marked as private by setting its CSP class parameter PRIVATE to 1 (True).
For this reason, many of the Zen report class parameters provide the information needed in xml-stylesheet processing instructions, so that this information does not need to appear in the URI query string. Once you have correctly configured the class parameters, Zen handles these instructions appropriately, regardless of the browser. The following list describes the Zen report class parameters of this type.
Note:
For information about how to supply report options as URI query parameters, and how to handle side effects that may occur in some browsers, see the Invoking Zen Reports from a Web Browser section of the chapter “Running Zen Reports.”
EMBEDXSL
When EMBEDXSL=1 (true) Zen generates XSLT instructions embedded within the output XHTML. The default for EMBEDXSL is 0 (false), in which case Zen generates a separate XSLT file, rather than embedding the instructions in the XHTML file.
Embedding the XSLT instructions brings up the issue of uniqueness for XML elements in the output file. The default namespace http://www.w3.org/1999/xhtml cannot be the namespace for all the generated XML elements if the generated XML and XSLT are combined in a single HTTP response. To ensure fully qualified XML names, InterSystems recommends when you set EMBEDXSL=1 you also provide a namespace name and prefix by providing values for REPORTXMLNAMESPACE and REPORTXMLNAMESPACEPREFIX in the Zen 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 work with this XML:
<SR:myReport xmlns:SR="http://www.example.com"
             runTime='2008-03-27 00:01:49'
             runBy='_SYSTEM' author='BOB' month='Jan'>
  <SR:SalesRep name='Jack'>

    <SR:record id='331' number='5'>
      <SR:date>2005-01-20</SR:date>
      <SR:customer>Yoyomo Inc.</SR:customer>
    </SR:record>

    <SR:record id='537' number='9'>
      <SR:date>2005-01-20</SR:date>
      <SR:customer>XenaData.com</SR:customer>
    </SR:record>

    <!-- more records omitted -->

  </SR:SalesRep>
</SR:myReport>
You can omit the REPORTXMLNAMESPACE or REPORTXMLNAMESPACEPREFIX parameters from the Zen report class. When EMBEDXSL=1 and these parameters are not set, they default as follows:
When an external 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.
REPORTXMLNAMESPACE
Specifies the XML namespace to be used in the generated XML report. This is especially important if you are using EMBEDXSL=1. There is a default name, http://www.intersytems.com/mydefaultnamespace, but you can specify your own choice. For details, see EMBEDXSL.
REPORTXMLNAMESPACEPREFIX
Specifies the XML namespace prefix to be used in the generated XML report. This is especially important if you are using EMBEDXSL=1. There is a default prefix, my, but you can specify your own choice. For details, see EMBEDXSL.
STYLESHEETDEFAULTMODE
Allows you to specify the processing mode to use if the URI parameter $MODE is not specified. DEFAULTMODE serves this same purpose, but cannot be used if the Zen report class is marked as private by setting its CSP class parameter PRIVATE to 1 (True). STYLESHEETDEFAULTMODE is provided to help in this case. Otherwise it is not needed.
If your Zen report uses both DEFAULTMODE and STYLESHEETDEFAULTMODE, you must set them carefully. Be aware that if both are set and the URI parameter $MODE is not specified, then STYLESHEETDEFAULTMODE overrides DEFAULTMODE as the default style mode.
If you want to use the STYLESHEETDEFAULTMODE, and your desired output format is:
The full list of possible values for STYLESHEETDEFAULTMODE is:
USETEMPFILES
When USETEMPFILES=1 (true) Zen writes its generated XSLT stylesheet to a file. It subsequently uses the generated XSLT stylesheet in the file to generate the output XHTML. The default for USETEMPFILES is 0 (false). In this case Zen generates and 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 “Troubleshooting Zen Reports” section of the chapter “Running Zen Reports.” $USETEMPFILES is the equivalent URI query parameter for USETEMPFILES.
XSLTMODE
Allows you to specify where XSLT transformation occurs, without adding to the number of query parameters in the URI string for the Zen report. XSLTMODE can have the value "browser" or "server". This causes the XSLT to be processed, and XHTML to be generated, on the server or browser, respectively.
XSLT processing is expensive; it could compromise the scalability of the application to shift XSLT processing to the server. However, the XSLTMODE option is provided to allow that flexibility. The default XSLTMODE is "server". Also see USETEMPFILES.
A user can override the current XSLTMODE setting for the report class by providing a $XSLT parameter in the URI when invoking the Zen report from a browser.
When the output mode is PDF, some processing always occurs on the server, because the third-party PDF generator engine (RenderX or FOP) runs on the server.