7
Customizing Reports at Runtime

Oracle Reports Services can run report definitions built with XML tags and merge them with other report definitions. In previous releases, a report had to be built and saved in the Oracle Report Builder in order to be run by Oracle Reports Services. With the 6i release, you can build a report definition using XML tags. This XML report definition can be run by itself or applied to another report at runtime to customize the output for a particular audience.

Using XML report definitions you can:

Apply customizations to reports at runtime without changing the original report. By creating and applying different XML report definitions, you can alter the report output on a per user or user group basis. The advantage of this scenario is that you can use the same report to generate different output depending upon the audience.
Apply batch updates to existing reports. When you apply an XML report definition to another report, you have the option of saving the combined definition to a file. As a result, you can use XML report definitions to make batch updates to existing reports. The advantage of this is that you can quickly update a large number of reports without having to open each file in the Oracle Report Builder to manually make the changes.
Create complete report definitions in XML. The advantage of this is that you can build reports on the fly without using the Oracle Report Builder. If you can generate XML tags, then you can create a report definition that can be run by Oracle Reports Services.

7.1 Overview

Using XML tags, you can build a full or partial report definition that can serve as either a customization file or a completely self-contained report. A full report definition specifies a complete data model and layout in XML and can be run separately or applied to another report to customize it. A partial definition can contain far less information and can only be used in conjunction with another report (that is, it cannot be run by itself).

A customization file is a report definition that is applied to an existing report (.RDF or .XML). It can change certain characteristics of existing report objects, such as the field's date format mask or background color. A customization file can also be used to add entirely new objects to another report.

In order to be run by itself, an XML report must contain a full report definition. A self-contained XML report is one that is run without being applied to another report.

7.1.1 Creating and Using XML Report Definitions

The steps below outline the process of building and using XML report definitions:

Create a full or partial report definition using the XML tags described in Section 7.5, "XML Tag Reference". You can create this definition manually with an editor or you can create it programmatically.¹ The following is a sample of a partial report definition:
```
<report name="emp" DTDVersion="1.0">
 <layout>
  <section name="main">
   <field name="f_sal" source="sal" textColor="red"/>
   <field name="f_mgr" source="mgr" fontSize="18" font="Script"/>
   <field name="f_deptno" source="deptno" fontStyle="bold"
          fontEffect="underline"/>
  </section>
 </layout>
</report>
```
This sample would change the formatting characteristics of some fields when applied to another report. This XML could not be run by itself because it does not contain a full report definition. It contains no data model definition and only a partial layout definition. In order to be run by itself, it would need to contain a complete data model and layout definition.

For more information on this step, refer to Section 7.2, "Creating an XML Report Definition".
Store the XML report definition in a location that is accessible to Oracle Reports Services.²
Apply the XML report definition to another report (using the CUSTOMIZE command line argument or the PL/SQL built-in SRW.APPLY_DEFINITION) or run the XML report definition by itself (using the REPORT command line argument).

For more information on this step, refer to Section 7.3, "Running XML Report Definitions".

The remainder of this chapter describes in greater detail the steps for building and using XML report definitions, and includes a reference section for the XML tags used to build a definition.

7.2 Creating an XML Report Definition

The best way to understand how to build an XML report definition is to work our way up from just the required tags to a partial definition and, finally, to a complete definition (that is, one that does not require an .RDF file in order to be run). This section describes the following XML definitions:

Section 7.2.1, "Required Tags"

Some XML tags are required regardless of whether you are building a partial or full report definition in XML. This XML report definition shows you the minimum set of XML tags that a report definition must have in order to be parsed correctly.
Section 7.2.2, "Partial Report Definitions"

This type of XML report definition contains less than a complete report definition. As a result, it can only be applied to another report as a customization file. It cannot be run by itself.
Section 7.2.3, "Full Report Definitions"

This type of XML report definition contains a complete report definition. As a result, it can be applied to an .RDF file or it can be run by itself.

7.2.1 Required Tags

Every XML report definition, full or partial, must contain the following required tag pair:

<report></report>

For example, the following is the most minimal XML report definition possible:³

<report name="emp" DTDVersion="1.0">
</report>

The <report> tag indicates the beginning of the report, its name, and the version of the Document Type Definition (DTD) file that is being used with this XML report definition.⁴ The </report> tag indicates the end of the report definition.

A full report definition requires both a data model and a layout and therefore also requires the following tags and their contents:

<data></data>
<layout></layout>

7.2.2 Partial Report Definitions

One of the primary uses of XML report definitions is to make modifications to another report at runtime. The XML report definition enables you to easily change the data model or formatting of another report at runtime, without permanently affecting the original report.⁵ The advantage of this is that it enables you to use a single report to serve multiple audiences. For example, you can build one .RDF file and apply different partial XML report definitions to it to customize it for different audiences. The XML report definition can be very simple, containing only a few tags to change the appearance of a few objects, or very complex, affecting every object in the report and possibly adding new objects.

To help you understand the kind of modifications possible in customization files, it is helpful to see some examples. The Building Reports manual contains descriptions of how to build several example reports using Oracle Reports Builder. The finished .RDF files for these reports are located in the ORACLE_HOME\TOOLS\DOC60\US\RBBR60 directory. For the purposes of this chapter, an XML report definition that modifies some of these reports has been placed in this directory with the .RDF files. The table that follows describes each of these XML report definitions in greater detail.

Table 7-1 XML Report Definitions for Building Reports

.`XML` File	.`RDF` File	Description
`cond.xml`	`cond.rdf`	`cond.xml` changes: The format mask of F_trade_date to MM/DD/RR. The fill colors of F_Mincurrent_pricePersymbol and F_Maxcurrent_pricePersymbol. `cond.xml` adds: HTML in the report escapes to be inserted when generating HTML output. Refer to Section 7.2.2.1, "Formatting Modifications Example", for more information.
`temp.xml`	`temp.rdf`	`temp.xml` changes: The field labels for F_high_365 and F_low_365. `temp.xml` adds: A formatting exception to F_p_e to highlight values greater than 10. A formatting exception to F_p_e1 to highlight values greater than 10. Refer to Section 7.2.2.2, "Formatting Exception Example", for more information.
`sect.xml`	`sect.rdf`	`sect.xml` adds: Program units to the report. Link destinations to the detail records in the main section of the report. Hyperlinks from the employee summary in the header section to the detail records in the main section. Refer to Section 7.2.2.3, "Program Unit and Hyperlink Example", for more information
`ref.xml`	`ref.rdf`	`ref.xml` adds: A new query, Q_summary, to the data model. A header section to the report that uses the data from the new query, Q_summary. Refer to Section 7.2.2.4, "Data Model and Formatting Modifications Example", for more information.

You can apply the XML customizations by running the .RDF files with one additional argument. For example:

rwrun60 userid=scott/tiger report=cond.rdf
        customize=e:\orant\tools\doc60\us\rbbr60\cond.xml

Refer to Section 7.3, "Running XML Report Definitions", for more information

Take a few moments to run these .RDF files with and without the customization file. In the next section, we examines the XML used to achieve these modifications.

7.2.2.1 Formatting Modifications Example

The XML in the cond.xml file modifies some basic formatting characteristics of the cond.rdf file and adds some HTML code to be inserted at the beginning and end of the report when generating HTMLCSS output.

Tips on this Example

The following tips are useful when looking at this example:

In this case the name attribute on the <report> tag matches the name of the .RDF file. You could also use a different name, for example, condnew.
The name attributes on the <field> and <section> tags match the names of fields and the section that exist in the .RDF file. As a result, the other attributes on the <field> tag are applied to those existing fields in the main section of the layout defined in the .RDF file.
The code inside of the <customize> tag modifies the before and after report escapes. The beforeReportType property indicates that the contents of the before report escape are located in a file. The beforeReportValue property indicates the name of the file, header_example.html, and its path (you might need to change this path if the file is located elsewhere on your machine).

The afterReportType property indicates that the contents of the second report escape are located in the afterReportValue property. Note the use of the <!CDATA[]]> tag around the HTML for the afterReportValue property. When using characters in your XML report definition that could be confused with XML tags, you should always enclose those segments in the <!CDATA[]]> tag.
The header_example.html file contains a reference to a graphic orep.gif. This graphic must be located in the same path as the HTML generated from the report.

To see the effects of the code in the <customize> tag, you need to generate HTML output. This report's output is best viewed with HTMLCSS output (DESFORMAT=HTMLCSS) and page streaming (PAGESTREAM=YES).

<report name="cond" DTDVersion="1.0">
 <layout>
   <section name="main">
     <field name="f_trade_date" 
           source="trade_date" 
            formatMask="MM/DD/RR"/>
     <field name="F_Mincurrent_pricePersymbol" 
            source="Mincurrent_pricePersymbol" 
            lineColor="black" 
            fillColor="r100g50b50"/>
     <field name="F_Maxcurrent_pricePersymbol"
            source="Maxcurrent_pricePersymbol"
            lineColor="black" 
            fillColor="r100g50b50"/>
   </section>
 </layout>
 <customize>
   <object name="videosales" type="REP_REPORT">
   <properties>
    <property name="beforeReportType">File</property>
    <property name="beforeReportValue">
         d:\orant\tools\doc60\us\rbbr60\header_example.html
    </property>
    <property name="afterReportType">Text</property>
    <property name="afterReportValue">
     <![CDATA[
      <center>
      <font face="Arial,Helvetica"><font size=-1><font color="#000000">
        Send questions to <a
href="mailto:your_email_id">YourNameHere</a>.
        <br>&nbsp;
      </font>
      </center>
      </body>
      </html>
     ]]>
    </property>
   </properties>
  </object>
 </customize>
</report>

7.2.2.2 Formatting Exception Example

The XML in temp.xml adds formatting exceptions to two fields in temp.rdf.

Tips on this Example

The following tips are useful when looking at this example:

Note the usage of the <exception> tag to define the formatting change. This formatting exception is only applied when the criteria defined by the <condition> tag is met.

The <object> tags inside of the <customize> section enable you to change the labels of an existing field in the layout. If you are creating a new field, then you can specify the label using the label attribute of the <field> tag.

<report name="temp" DTDVersion="1.0">
 <layout>
   <section name="main">
     <field name="f_p_e" source="p_e" alignment="right"
            formatMask="NNN0.00">
       <exception textColor="red">
         <condition source="p_e" operator="gt" operand1="10"/>
       </exception>
     </field>
     <field name="f_p_e1" source="p_e" alignment="right"
            formatMask="NNN0.00">
       <exception textColor="blue">
         <condition source="p_e" operator="gt" operand1="10"/>
       </exception>
     </field>
   </section>
 </layout>
 <customize>
  <object name="B_high_365" type="REP_GRAPHIC_TEXT">
   <properties>
    <property name="textSegment">High</property>
   </properties>
  </object>
  <object name="B_low_365" type="REP_GRAPHIC_TEXT">
   <properties>
    <property name="textSegment">Low</property>
   </properties>
  </object>
 </customize>
</report>

7.2.2.3 Program Unit and Hyperlink Example

The XML in sect.xml adds two program units to sect.rdf and uses the program units to add a header section.

Tips on this Example

The following tips are useful when looking at this example:

When the parameter form appears, you should enter 100 for the parameter.
The program units are created outside of the data model and layout, inside the <programUnits> tag.
The functions are referenced by name from the formatTrigger attribute of the <field> tag.
Notice the usage of the <![CDATA[]]> tag around the PL/SQL function. This is necessary because of the special characters used within the PL/SQL code.

This report is best viewed in PDF. To generate PDF output, you use the following command line:

rwrun60 userid=scott/tiger@nt805 report=sect.rdf customize=sect.xml 
destype=file desformat=htmlcss desname=d:\sect.pdf

Open the .PDF file and roll your mouse over the values in the SSN column. Click a value to be see to the details on that record.

<report name="sect" DTDVersion="1.0">
 <layout>
   <section name="header"> 
     <field name="F_ssn1" 
            source="ssn1" 
            formatTrigger="F_ssn1FormatTrigger"/>
   </section>
   <section name="main">
     <field name="F_ssn" 
            source="ssn" 
            formatTrigger="F_ssnFormatTrigger"/>     
   </section>
 </layout>
 <programUnits> 
  <function name="F_ssn1FormatTrigger"> 
   <![CDATA[
      function F_ssn1FormatTrigger return boolean is
        begin
          SRW.SET_HYPERLINK('#EMP_DETAILS_&<' || LTRIM(TO_CHAR(:SSN)) ||
'>');
          return (TRUE);
        end;
   ]]>
  </function> 
  <function name="F_ssnFormatTrigger"> 
  <![CDATA[
     function F_ssnFormatTrigger return boolean is
       begin
         SRW.SET_LINKTAG('EMP_DETAILS_&<' || LTRIM(TO_CHAR(:SSN)) ||
'>');
         return (TRUE);
       end;
   ]]>
  </function> 
 </programUnits>
</report>

7.2.2.4 Data Model and Formatting Modifications Example

The XML in ref.xml adds a new query to the data model of ref.rdf and adds a header section.

Tips on this Example

The following tags are useful when looking at this example:

This XML report definition can be run by itself or applied to ref.rdf. The reason it can be run by itself is that it has both a data model and a complete layout.
Notice the use of aliases in the SELECT statement. In general, it is a good idea to use aliases in your SELECT lists because it guarantees the name that is assigned to the report column. If you do not use an alias, then the name of the report column is defaulted and could be something different from the name you expect (for example, portid1 instead of portid). This becomes important when you must specify the source attribute of the <field> tag because you have to use the correct name of the source column.

Also notice the use of the <labelAttribute> tag. This tag defines the formatting for the field labels in the layout. Because it lies outside of the <field> tags, it applies to all of the labels in the tabular layout. If you wanted it to pertain to only one of the fields, then you place it inside of the <field></field> tag pair. Be aware that if there is both a global and local <labelAttribute>, the local one overrides the global one. Refer to Section 7.5.8, "<field>", for more information

<report name="ref" DTDVersion="1.0">
 <data>
   <dataSource name="Q_summary">
   <select>
    select portid ports, locname locations from portdesc
   </select>
  </dataSource>
 </data>
 <layout>
   <section name="header"> 
   <tabular name="M_summary" template="corp2.tdf">
     <labelAttribute font="Arial" 
            fontSize="10"
            fontStyle="bold"
            textColor="white"/>
     <field name="F_ports" 
            source="ports" 
            label="Port IDs" 
            font="Arial" 
            fontSize="10"/>
     <field name="F_locations" 
            source="locations" 
            label="Port Names" 
            font="Arial" 
            fontSize="10"/>
   </tabular>
  </section>
 </layout>
</report>

7.2.3 Full Report Definitions

Another use of XML report definitions is to make an entire report definition in XML that can be run independently of another report. The advantage of this is that you can build a report without using the Oracle Reports Builder. In fact, you could even use your own front end to generate the necessary XML and allow your users to build their own reports dynamically.

The following example illustrates a complete report definition in XML. This XML report definition is named videosales.xml and can be found in the ORACLE_HOME\TOOLS\DOC60\US\RBBR60 directory.

Tips on this Example

The following tips are useful when looking at this example:

This XML report definition is complete and can be run by itself. It contains a full data model and layout. This report is best viewed in PDF.
The first query in the data model (Q_1) is used to populate a summary tabular layout in the header section of the report. The second query (Q_2) is used for the matrix break layout in the main section of the report. The <group>, <matrixRow>, <matrixCol>, and <matrixCell> tags define both the layout and the data model structure needed to support it. Based on which fields are inside these tags, the groups and columns are arranged within the data model. To get a better sense of the data model, you can run the report to the Oracle Reports Builder and look at the Oracle Data Model view of the Oracle Reports Editor:
```
rwbld60 userid=scott/tiger report=videosales.xml
```

The quarter and city values in the header section are linked to the quarter and city values in the main section. This is accomplished by associating format triggers with each of the fields that contain quarter and city values. The PL/SQL for the triggers is located inside the <programUnits> tag at the end of the report definition. When the report is used to generate PDF or HTMLCSS output, the user can click on values in the summary in the header section to jump to the details in the main section of the report.

<report name="videosales" author="Generated" DTDVersion="1.0">
 <data>
  <dataSource name="Q_1">
   <select>
    SELECT ALL VIDEO_CATEGORY_BY_QTR.QUARTER, 
           VIDEO_CATEGORY_BY_QTR.SALES_REGION,
           VIDEO_CATEGORY_BY_QTR.STATE, VIDEO_CATEGORY_BY_QTR.CITY, 
           VIDEO_CATEGORY_BY_QTR.PRODUCT_CATEGORY, 
           VIDEO_CATEGORY_BY_QTR.TOTAL_SALES, 
           VIDEO_CATEGORY_BY_QTR.TOTAL_COST,
           VIDEO_CATEGORY_BY_QTR.TOTAL_PROFIT
    FROM SCOTT.VIDEO_CATEGORY_BY_QTR
    WHERE VIDEO_CATEGORY_BY_QTR.SALES_REGION='West'
   </select>
  </dataSource>
  <dataSource name="Q_2">
   <select>
    SELECT ALL VIDEO_CATEGORY_BY_QTR.QUARTER,
VIDEO_CATEGORY_BY_QTR.CITY, 
           VIDEO_CATEGORY_BY_QTR.PRODUCT_CATEGORY, 
           VIDEO_CATEGORY_BY_QTR.TOTAL_PROFIT,
           VIDEO_CATEGORY_BY_QTR.TOTAL_SALES,
           VIDEO_CATEGORY_BY_QTR.TOTAL_COST
    FROM SCOTT.VIDEO_CATEGORY_BY_QTR
    WHERE VIDEO_CATEGORY_BY_QTR.SALES_REGION='West'
   </select> 
  </dataSource>
  <summary name="SumTOTAL_SALESPerCITY1" source="total_sales1"/> 
  <summary name="SumTOTAL_COSTPerCITY1" source="total_cost1"/> 
  <summary name="SumTOTAL_PROFITPerCITY1" source="total_profit1"/> 
  <summary name="SumTOTAL_SALESPerQUARTER" source="total_sales"/> 
  <summary name="SumTOTAL_COSTPerQUARTER" source="total_cost"/> 
  <summary name="SumTOTAL_PROFITPerQUARTER" source="total_profit"/> 
  <summary name="SumTOTAL_SALESPerCITY" source="total_sales"/> 
  <summary name="SumTOTAL_COSTPerCITY" source="total_cost"/> 
  <summary name="SumTOTAL_PROFITPerCITY" source="total_profit"/> 
  <formula name="Profit_Margin" source="FormulaProfitMargin" 
           datatype="number" width="9"/>
 </data>    
 <layout>
  <section name="header">
   <groupLeft name="M_video_sales_summary" template="corp1.tdf">
     <group>
       <field name="f_quarter1" source="quarter1" label="Quarter" 
              font="Arial" fontSize="8"
              formatTrigger="F_quarter1FormatTrigger">
         <labelAttribute font="Arial" fontSize="8" 
                         fontStyle="bold" textColor="yellow"/>
       </field>
     </group>
     <group>
       <field name="f_city1" source="city1" label="City" 
              font="Arial" fontSize="8"
              formatTrigger="F_city1FormatTrigger">
         <labelAttribute font="Arial" fontSize="8" 
                         fontStyle="bold" textColor="yellow"/>
       </field>
       <field name="f_SumTOTAL_SALESPerCITY1"
              source="SumTOTAL_SALESPerCITY1"
              label="Sales" font="Arial" fontSize="8"
              formatMask="LNNNGNNNGNNNGNN0D00">
          <labelAttribute font="Arial" fontSize="8" 
                          fontStyle="bold" textColor="yellow"/>
       </field>
       <field name="f_SumTOTAL_COSTPerCITY1"
              source="SumTOTAL_COSTPerCITY1"
              label="Costs" font="Arial" fontSize="8"
              formatMask="LNNNGNNNGNNNGNN0D00">
          <labelAttribute font="Arial" fontSize="8" 
                          fontStyle="bold" textColor="yellow"/>
       </field>
       <field name="f_SumTOTAL_PROFITPerCITY1"
              source="SumTOTAL_PROFITPerCITY1"
              label="Profits" font="Arial" fontSize="8"
              formatMask="LNNNGNNNGNNNGNN0D00">
          <labelAttribute font="Arial" fontSize="8" 
                          fontStyle="bold" textColor="yellow"/>
       </field> 
       <field name="f_Profit_Margin" source="Profit_Margin"
              label="Margin%" font="Arial" fontSize="8"
              formatMask="N0%">
          <labelAttribute font="Arial" fontSize="8" 
                          fontStyle="bold" textColor="yellow"/>
       </field>
     </group>
   </groupLeft>
  </section>
  <section name="main"> 
   <matrix name="M_video_sales" template="corp10.tdf">
    <group>
       <field name="f_quarter" source="quarter" label="Quarter:" 
              font="Arial" fontSize="8"
              formatTrigger="F_quarterFormatTrigger">
         <labelAttribute font="Arial" fontSize="8" 
                         fontStyle="bold" textColor="black"/>
       </field>
       <field name="f_SumTOTAL_SALESPerQUARTER" 
              source="SumTOTAL_SALESPerQUARTER"
              label="Qtrly:  Sales: " font="Arial" fontSize="8"
              fontStyle="bold"
              formatMask="LNNNGNNNGNNNGNN0D00">
          <labelAttribute font="Arial" fontSize="8" 
                          fontStyle="bold" textColor="black"/>
       </field>
       <field name="f_SumTOTAL_COSTPerQUARTER"
              source="SumTOTAL_COSTPerQUARTER"
              label="Costs: " font="Arial" fontSize="8" fontStyle="bold"
              formatMask="LNNNGNNNGNNNGNN0D00">
          <labelAttribute font="Arial" fontSize="8" 
                          fontStyle="bold" textColor="black"/>
       </field>
       <field name="f_SumTOTAL_PROFITPerQUARTER" 
              source="SumTOTAL_  PROFITPerQUARTER"
              label="Profits: " font="Arial" fontSize="8"
              fontStyle="bold"
              formatMask="LNNNGNNNGNNNGNN0D00">
          <labelAttribute font="Arial" fontSize="8" 
                          fontStyle="bold" textColor="black"/>
       </field>
    </group>
    <group>
       <field name="f_state" source="state" label="State:"
              font="Arial" fontSize="8">
         <labelAttribute font="Arial" fontSize="8" 
                         fontStyle="bold" textColor="black"/>
       </field> 
    </group>
    <matrixCol name="g_city">
       <field name="f_city" source="city" label="City: "
              font="Arial" fontSize="8" textColor="yellow"
              formatTrigger="F_cityFormatTrigger"/>
       <field name="f_SumTOTAL_SALESPerCITY"
              source="SumTOTAL_SALESPerCITY"
              label="Sales: " font="Arial" fontSize="8" fontStyle="bold"
              textColor="yellow" formatMask="LNNNGNNNGNNNGNN0D00">
          <labelAttribute font="Arial" fontSize="8" 
                          fontStyle="bold" textColor="yellow"/>
       </field>
       <field name="f_SumTOTAL_COSTPerCITY"
              source="SumTOTAL_COSTPerCITY"
              label="Sales: " font="Arial" fontSize="8" fontStyle="bold"
              textColor="yellow" formatMask="LNNNGNNNGNNNGNN0D00">
          <labelAttribute font="Arial" fontSize="8" 
                          fontStyle="bold" textColor="yellow"/>
       </field>
       <field name="f_SumTOTAL_PROFITPerCITY"
              source="SumTOTAL_PROFITPerCITY"
              label="Sales: " font="Arial" fontSize="8" fontStyle="bold"
              textColor="yellow" formatMask="LNNNGNNNGNNNGNN0D00">
          <labelAttribute font="Arial" fontSize="8" 
                          fontStyle="bold" textColor="yellow"/>
       </field>       
    </matrixCol>
    <matrixRow name="g_product_category">
       <field name="f_product_category" source="product_category" 
              label="Product Category" font="Arial" fontSize="8"/>       
    </matrixRow>
    <matrixCell name="g_total_sales">
     <field name="f_total_sales" source="total_sales" label="Total
Sales"
            font="Arial" fontSize="8" lineColor="noLine"
            formatMask="LNNNGNNNGNNNGNN0D00"/>
     <field name="f_total_cost" source="total_cost" label="Total Cost"
            font="Arial" fontSize="8" lineColor="noLine"
            formatMask="LNNNGNNNGNNNGNN0D00"/>
     <field name="f_total_profit" source="total_profit" label="Total
Profit"
            font="Arial" fontSize="8" lineColor="noLine"
            formatMask="LNNNGNNNGNNNGNN0D00"/>
    </matrixCell>
   </matrix>
  </section>
 </layout>
 <programUnits> 
  <function name="F_quarter1FormatTrigger"> 
   <![CDATA[
      function F_quarter1FormatTrigger return boolean is
        begin
          SRW.SET_HYPERLINK('#QUARTER_DETAILS_&<' || LTRIM(:quarter1) ||
'>');
          return (TRUE);
        end;
   ]]>
  </function> 
  <function name="F_quarterFormatTrigger"> 
  <![CDATA[
     function F_quarterFormatTrigger return boolean is
       begin
         SRW.SET_LINKTAG('QUARTER_DETAILS_&<' || LTRIM(:quarter) ||
'>');
         return (TRUE);
       end;
   ]]>
  </function> 
  <function name="F_city1FormatTrigger"> 
   <![CDATA[
      function F_city1FormatTrigger return boolean is
        begin
          SRW.SET_HYPERLINK('#QTR_CITY_DETAILS_&<' || LTRIM(:quarter1)
||
                             LTRIM(:city1) || '>');
          return (TRUE);
        end;
   ]]>
  </function> 
  <function name="F_cityFormatTrigger"> 
  <![CDATA[
     function F_cityFormatTrigger return boolean is
       begin
         SRW.SET_LINKTAG('QTR_CITY_DETAILS_&<' || LTRIM(:quarter) ||
                          LTRIM(:city) || '>');
         return (TRUE);
       end;
   ]]>
  </function> 
  <function name="FormulaProfitMargin"> 
   <![CDATA[ 
   FUNCTION FormulaProfitMargin RETURN number IS 
   BEGIN 
     return ((:TOTAL_PROFIT1 / (:TOTAL_SALES1 - (0.07 * :TOTAL_SALES1)))
* 100); 
   END; 
   ]]> 
  </function>
  </programUnits>
</report>

7.3 Running XML Report Definitions

Once you have created your XML report definition, you can use it in the following ways.

Section 7.3.1, "Applying an XML Report Definition at Runtime"

You can apply XML report definitions to .RDF or other .XML files at runtime by specifying the CUSTOMIZE command line argument or the SRW.APPLY_DEFINITION built-in.
Section 7.3.2, "Running an XML Report Definition by Itself"

You can run an XML report definition by itself (without another report) by specifying the REPORT command line argument.
Section 7.3.3, "Performing Batch Modifications"

You can use RWCON60 to make batch modifications using the CUSTOMIZE command line argument.

The sections that follow describe each of the above cases in more detail and provide examples.

7.3.1 Applying an XML Report Definition at Runtime

To apply an XML report definition to an .RDF or .XML file at runtime, you can use the CUSTOMIZE command line argument or the SRW.APPLY_DEFINITION built-in. CUSTOMIZE can be used with RWCLI60, RWRUN60, RWBLD60, RWCON60, and URL report requests. Refer to Section 7.3.3, "Performing Batch Modifications", for more information about using CUSTOMIZE with RWCON60.

7.3.1.1 Applying One XML Report Definition

The following command line sends a job request to Oracle Reports Services that applies an XML report definition, emp.xml, to an .RDF file, emp.rdf:

rwcli60 report=emp.rdf customize=e:\myreports\emp.xml
  userid=username/password@mydb destype=file desname=emp.pdf desformat=PDF
  server=repserver

If you were using Oracle Reports Runtime, then the equivalent command line would be:

rwrun60 userid=username/password@mydb report=emp.rdf
   customize=e:\myreports\emp.xml destype=file desname=emp.pdf
   desformat=PDF

When testing your XML report definition, it is sometimes useful to run your report requests with additional arguments to create a trace file. For example:

tracefile=emp.log tracemode=trace_replace traceopt=trace_app

The trace file provides a detailed listing of the creation and formatting of the report objects.

7.3.1.2 Applying Multiple XML Report Definitions

You can apply multiple XML report definitions to a report at runtime by providing a list with the CUSTOMIZE command line argument. The following command line sends a job request to Oracle Reports Services that applies two XML report definitions, emp0.xml and emp1.xml, to an .RDF file, emp.rdf:

rwcli60 report=emp.rdf 
  customize="(e:\corp\myreports\emp0.xml,
  e:\corp\myreports\emp1.xml)"
  userid=username/password@mydb destype=file desname=emp.pdf desformat=PDF
  server=repserver

If you were using Oracle Reports Runtime, then the equivalent command line would be:

rwrun60 report=emp.rdf 
  customize="(e:\corp\myreports\emp0.xml,
  e:\corp\myreports\emp1.xml)"
  userid=username/password@mydb destype=file desname=emp.pdf desformat=PDF

7.3.1.3 Applying an XML Report Definition in PL/SQL

To apply an XML report definition to an .RDF file in PL/SQL, you use the SRW.APPLY_DEFINITION and SRW.ADD_DEFINITION built-ins in the BeforeForm or AfterForm trigger.

7.3.1.3.1 Applying an XML Definition Stored in a File

To apply XML that is stored in the file system to a report, you can use the SRW.APPLY_DEFINITION built-in in the BeforeForm or AfterForm triggers of the report:

SRW.APPLY_DEFINITION ('d:\orant\tools\doc60\us\rbbr60\cond.xml');

When the report is run, the trigger executes and the specified XML file is applied to the report.

7.3.1.3.2 Applying an XML Definition Stored in Memory

To create an XML report definition in memory, you must add the definition to the document buffer using SRW.ADD_DEFINITION before applying it using SRW.APPLY_DEFINITION.

The following example illustrates how to build up several definitions in memory based upon parameter values entered by the user and then apply them. The PL/SQL in this example is actually used in the AfterParameterForm trigger of an example report called videosales_custom.rdf that can be found in the ORACLE_HOME\TOOLS\DOC60\US\RBBR60 directory.

The videosales_custom.rdf file contains PL/SQL in its AfterParameterForm trigger that does the following:

Conditionally highlights fields based upon parameter values entered by the user at runtime.
Changes number format masks based upon parameter values entered by the user at runtime.

Tips on this Example

The following tips are useful when looking at this example:

Each time you use SRW.APPLY_DEFINITION, the document buffer is flushed and you must begin building a new XML report definition with SRW.ADD_DEFINITION.
Notice the use of the parameters hilite_profits, hilite_costs, hilite_sales, and money_format to determine what to include in the XML report definition. The hilite_profits, hilite_costs, and hilite_sales parameters are also used in the formatting exceptions to determine which values to highlight.

Because of the upper limit on the size of VARCHAR2 columns, you might need to spread very large XML report definitions across several columns. If so, then you might have to create several definitions in memory and apply them separately rather than creating one large definition and applying it once.

function AfterPForm return boolean is
begin
SRW.ADD_DEFINITION('<report name="vidsales_masks"
author="Generated" DTDVersion="1.0">');
IF :MONEY_FORMAT='$NNNN.00' THEN
 SRW.ADD_DEFINITION(' <layout>');
 SRW.ADD_DEFINITION('  <section name="main">');
 SRW.ADD_DEFINITION('   <field name="F_TOTAL_PROFIT" 
         source="TOTAL_PROFIT" formatMask="LNNNNNNNNNNN0D00"/>');
 SRW.ADD_DEFINITION('   <field name="F_TOTAL_SALES" 
         source="TOTAL_SALES" formatMask="LNNNNNNNNNNN0D00"/>');
 SRW.ADD_DEFINITION('   <field name="F_TOTAL_COST" 
          source="TOTAL_COST" formatMask="LNNNNNNNNNNN0D00"/>');
 SRW.ADD_DEFINITION('   <field name="F_SumTOTAL_PROFITPerCITY"
          source="SumTOTAL_PROFITPerCITY"
formatMask="LNNNNNNNNNNN0D00"/>');
 SRW.ADD_DEFINITION('   <field name="F_SumTOTAL_SALESPerCITY"
          source="SumTOTAL_SALESPerCITY"
formatMask="LNNNNNNNNNNN0D00"/>');
 SRW.ADD_DEFINITION('   <field name="F_SumTOTAL_COSTPerCITY"
           source="SumTOTAL_COSTPerCITY"
formatMask="LNNNNNNNNNNN0D00"/>');
 SRW.ADD_DEFINITION('  </section>');
 SRW.ADD_DEFINITION(' </layout>');
ELSIF :MONEY_FORMAT='$NNNN' THEN
 SRW.ADD_DEFINITION(' <layout>');
 SRW.ADD_DEFINITION('  <section name="main">');
 SRW.ADD_DEFINITION('   <field name="F_TOTAL_PROFIT" 
           source="TOTAL_PROFIT" formatMask="LNNNNNNNNNNN0"/>');
 SRW.ADD_DEFINITION('   <field name="F_TOTAL_SALES" 
          source="TOTAL_SALES" formatMask="LNNNNNNNNNNN0"/>');
 SRW.ADD_DEFINITION('   <field name="F_TOTAL_COST" 
           source="TOTAL_COST" formatMask="LNNNNNNNNNNN0"/>');
 SRW.ADD_DEFINITION('   <field name="F_SumTOTAL_PROFITPerCITY"
          source="SumTOTAL_PROFITPerCITY"
formatMask="LNNNNNNNNNNN0"/>');
 SRW.ADD_DEFINITION('   <field name="F_SumTOTAL_SALESPerCITY"
          source="SumTOTAL_SALESPerCITY"
formatMask="LNNNNNNNNNNN0"/>');
 SRW.ADD_DEFINITION('   <field name="F_SumTOTAL_COSTPerCITY"
           source="SumTOTAL_COSTPerCITY" formatMask="LNNNNNNNNNNN0"/>');      
 SRW.ADD_DEFINITION('  </section>');
 SRW.ADD_DEFINITION(' </layout>');
END IF;
SRW.ADD_DEFINITION('</report>');
SRW.APPLY_DEFINITION;
SRW.ADD_DEFINITION('<report name="vidsales_hilite_costs"
author="Generated" DTDVersion="1.0">');
IF :HILITE_COSTS <> 'None' THEN
  SRW.ADD_DEFINITION(' <layout>');
  SRW.ADD_DEFINITION('   <section name="main">');
  SRW.ADD_DEFINITION('     <field name="F_TOTAL_COST"
          source="TOTAL_COST">');
  SRW.ADD_DEFINITION('     <exception textColor="red">');
  SRW.ADD_DEFINITION('       <condition source="TOTAL_COST"
           operator="gt" operand1=":hilite_costs"/>');
  SRW.ADD_DEFINITION('     </exception>');
  SRW.ADD_DEFINITION('   </field>');
  SRW.ADD_DEFINITION(' </section>');
  SRW.ADD_DEFINITION(' </layout>');
END IF;
SRW.ADD_DEFINITION('</report>');
SRW.APPLY_DEFINITION;
SRW.ADD_DEFINITION('<report name="vidsales_hilite_sales"
author="Generated" DTDVersion="1.0">');
IF :HILITE_SALES <> 'None' THEN
  SRW.ADD_DEFINITION(' <layout>');
  SRW.ADD_DEFINITION('   <section name="main">');
  SRW.ADD_DEFINITION('     <field name="F_TOTAL_SALES"
          source="TOTAL_SALES">');
  SRW.ADD_DEFINITION('     <exception textColor="red">');
  SRW.ADD_DEFINITION('       <condition source="TOTAL_SALES"
          operator="gt" operand1=":hilite_sales"/>');
  SRW.ADD_DEFINITION('     </exception>');
  SRW.ADD_DEFINITION('   </field>');
  SRW.ADD_DEFINITION(' </section>');
  SRW.ADD_DEFINITION(' </layout>');
END IF;
SRW.ADD_DEFINITION('</report>');
SRW.APPLY_DEFINITION;
SRW.ADD_DEFINITION('<report name="vidsales_hilite_profits"
author="Generated" DTDVersion="1.0">');
IF :HILITE_PROFITS <> 'None' THEN
  SRW.ADD_DEFINITION(' <layout>');
  SRW.ADD_DEFINITION('   <section name="main">');
  SRW.ADD_DEFINITION('     <field name="F_TOTAL_PROFIT"
           source="TOTAL_PROFIT">');
  SRW.ADD_DEFINITION('     <exception textColor="red">');
  SRW.ADD_DEFINITION('       <condition 
           source="TOTAL_PROFIT" operator="gt"
operand1=":hilite_profits"/>');
  SRW.ADD_DEFINITION('     </exception>');
  SRW.ADD_DEFINITION('   </field>');
  SRW.ADD_DEFINITION(' </section>');
  SRW.ADD_DEFINITION(' </layout>');
END IF;
SRW.ADD_DEFINITION('</report>');
SRW.APPLY_DEFINITION;
return (TRUE);
end;

7.3.2 Running an XML Report Definition by Itself

To run an XML report definition by itself, you send a request with an XML file specified in the REPORT argument. The following command line sends a job request to Oracle Reports Services to run a report, emp.xml, by itself:

rwcli60 userid=username/password@mydb 
  report=e:\corp\myreports\emp.xml
  destype=file desname=emp.pdf desformat=PDF
  server=repserver

If you were using Oracle Reports Runtime, then the equivalent command line would be:

rwrun60 userid=username/password@mydb
  report=e:\corp\myreports\emp.xml
  destype=file desname=emp.pdf desformat=PDF

When running an XML report definition in this way, the file extension must be .XML. You could also apply an XML customization file to this report using the CUSTOMIZE argument.

7.3.3 Performing Batch Modifications

If you have a large number of reports that need to be updated, then you can use the CUSTOMIZE command line argument with RWCON60 to perform modifications in batch. Batch modifications are particularly useful when you need to make a repetitive change to a large number of reports (for example, changing a field's format mask). Rather than opening each report and manually making the change in Oracle Report Builder, you can run RWCON60 once and make the same change to a large number of reports at once.

The following example applies two XML report definitions, translate.xml and customize.xml, to three .RDF files, inven.rdf, inven2.rdf, and manu.rdf, and saves the revised definitions to new files, inven1_new.rdf, inven2_new.rdf, and manu_new.rdf.

rwcon60 username/password@mydb
  stype=rdffile 
  source="(inven1.rdf, inven2.rdf, manu.rdf)" 
  dtype=rdffile 
  dest="(inven1_new.rdf, inven2_new.rdf, manu_new.rdf)" 
  customize="(e:\apps\trans\translate.xml, 
  e:\apps\custom\customize.xml)" batch=yes

7.4 Debugging XML Report Definitions

The following features can help you to debug your XML report definitions:

7.4.1 XML Parser Error Messages

The XML parser catches most syntax errors and displays an error message. The error message contains the line number in the XML where the error occurred as well as a brief description of the problem.

7.4.2 Tracing Options

When testing your XML report definition, it is sometimes useful to run your report requests with additional arguments to create a trace file. For example:

rwrun60 username/password@mydb
  report=e:\corp\myreports\emp.xml
  tracefile=emp.log 
  tracemode=trace_replace
  traceopt=trace_app

The last three arguments in this command line generates a trace file that provides a detailed listing of the fetching and formatting of the report. Below is a segment of an example trace file for a successfully run report.

LOG : 
      Report: d:\xml_reps\test1.xml
      Logged onto server: 
      Username: 
LOG : 
      Logged onto server: nt805
      Username: scott
+----------------------------------------+
| Report customization/generation begins |
+----------------------------------------+
  Processing XML report definition 1 of 1.
    *** Parsing the XML document ***
    Creating XML parser object...
    XML Parser Created!
    Parsing report definition from:
    d:\xml_reps\test1.xml
    Report definition parsed successfully!
    *** Setting Application Property ***
    Setting module name to "test"...
    Done with application level properties modification.
    *** Creating PL/SQL Program Units ***
    *** Defaulting the Data Model ***
Created query Q_depemp. 
  Applying SQL to query Q_depemp and creating columns...
    Done with queries and columns creation/modification.
    Done with groups creation/modification.
    *** Defaulting the Layout ***
    Start defaulting layout for main section...
    Defaulting field f_deptno for column deptno...
    Defaulting field f_mgr for column mgr...
    Defaulting field f_job for column job...
    Layout defaulted into new frame M_empform.
    *** Modifying report objects' properties ***
+-------------------------------------------------------+
| Report customization/generation finished successfully |
+-------------------------------------------------------+
11:22:59  APP  (  Frame                    
11:22:59  APP . (  Text Boilerplate         B_DATE1_SEC2
11:22:59  APP . )  Text Boilerplate         B_DATE1_SEC2
11:22:59  APP . (  Text Boilerplate         B_PAGENUM1_SEC2
11:22:59  APP . )  Text Boilerplate         B_PAGENUM1_SEC2
11:22:59  APP . (  Text Field               F_DATE1_SEC2
11:22:59  APP .. (  Database Column          Name unknown 
11:22:59  APP .. )  Database Column          Name unknown 
11:22:59  APP . )  Text Field               F_DATE1_SEC2
11:22:59  APP  )  Frame                    
11:22:59  APP  (  Frame                    
11:22:59  APP . (  Frame                    M_G_1_GRPFR
11:22:59  APP .. (  Frame                    M_G_1_HDR
11:22:59  APP ... (  Text Boilerplate         B_DEPTNO
11:22:59  APP ... )  Text Boilerplate         B_DEPTNO
11:22:59  APP ... (  Text Boilerplate         B_MGR
11:22:59  APP ... )  Text Boilerplate         B_MGR
11:22:59  APP ... (  Text Boilerplate         B_JOB
11:22:59  APP ... )  Text Boilerplate         B_JOB
11:22:59  APP .. )  Frame                    M_G_1_HDR
11:22:59  APP .. (  Repeating Frame          R_G_1
11:22:59  APP ... (  Group                    G_1  Local Break:  0  Global
Break:  0
11:22:59  APP .... (  Query                    Q_depemp
11:22:59  SQL         EXECUTE QUERY : select * from emp
11:22:59  APP .... )  Query                    Q_depemp
11:22:59  APP ... )  Group                    G_1
11:22:59  APP ... (  Text Field               F_DEPTNO
11:22:59  APP .... (  Database Column          DEPTNO
11:22:59  APP .... )  Database Column          DEPTNO
.
.
.
+-------------------------------------+
| Report Builder Profiler statistics  |
+-------------------------------------+
             TOTAL ELAPSED Time:      11.00 seconds
            Reports Time:      10.00 seconds (90.90% of TOTAL)
                    ORACLE Time:       1.00 seconds ( 9.09% of TOTAL)
                            UPI:       0.00 second
                            SQL:       1.00 seconds
 TOTAL CPU Time used by process: N/A

7.4.3 RWBLD60

When designing an XML report definition, it is sometimes useful to open it in Oracle Reports Builder. In Oracle Reports Builder, you can quickly determine if the objects are being created or modified as expected. For example, if you are creating summaries in an XML report definition, then opening the definition in Oracle Reports Builder enables you to quickly determine if the summaries are being placed in the appropriate group in the data model.

To open a full report definition in Oracle Reports Builder, you use the REPORT keyword. For example:

rwbld60 userid=username/password@mydb
  report=e:\corp\myreports\emp.xml

To open a partial report definition in Oracle Reports Builder, you use the CUSTOMIZE keyword. For example:

rwbld60 userid=username/password@mydb report=emp.rdf
   customize=e:\myreports\emp.xml

In both cases, the Oracle Report Builder is opened with the XML report definition in effect. You can then use the various views (including the Live Previewer) of the Oracle Reports Editor to quickly determine if the report is being created or modified as you expected.

7.4.4 TEXT_IO

If you are using SRW.ADD_DEFINTION to build an XML report definition in memory, then it can be helpful to write the XML to a file for debugging purposes. Following is an example of a procedure that writes each line that you pass it to the document buffer in memory and, optionally, to a file that you give it.

PROCEDURE addaline (newline VARCHAR, outfile Text_IO.File_Type) IS
BEGIN
  SRW.ADD_DEFINITION(newline);
  IF :WRITE_TO_FILE='Yes' THEN
    Text_IO.Put_Line(outfile, newline);
  END IF;
END;

For this example to work, the PL/SQL that calls this procedure would need to declare a variable of type TEXT_IO.File_Type. For example:

custom_summary  Text_IO.File_Type;

You would also need to open the file for writing and call the addaline procedure, passing it the string to be written and the file to which it should be written. For example:

custom_summary := Text_IO.Fopen(:file_directory || 'vid_summ_per.xml', 'w');
addaline('<report name="video_custom" author="Generated" DTDVersion="1.0">',
           custom_summary);

7.5 XML Tag Reference

The Document Type Definition (DTD) file incorporated into Oracle Reports Services defines the tags that can be used in an XML report definition. The sections that follow describe each of the tags and their syntax, and provide examples of their usage. The tags are listed in hierarchical order (from outermost to innermost).

WARNING:
THE XML TAGS AND THEIR ATTRIBUTES ARE CASE SENSITIVE, AND SHOULD BE ENTERED IN THE CASE SHOWN IN THE SYNTAX DESCRIPTIONS.

7.5.1

Description

tag enables you to include comments within your XML report definition. The parser ignores any text between the comment delimiters. If you are using PL/SQL (SRW.ADD_DEFINITION) to build your XML report definition, then you can incorporate comments in the program unit using the PL/SQL comment delimiters (for example, -- or /* */).

Syntax

Following is the syntax for this tag:

<!--
   comment_content
-->

Example

The following example shows a segment of an XML report definition that uses the  tag to include a comment.

<report name="cond" DTDVersion="1.0">
<!-- This report assumes that the file
     named header_example.html is located
     in d:\ORANT\TOOLS\DOC60\US\RBBR60.
     If it it not located there, the report
     will not run properly.
-->

7.5.2 <![CDATA[ ]]>

Description

The <!CDATA[]> tag enables you to include special characters within your XML report definition. The parser ignores any special characters it encounters within the <!CDATA[]> tag. This is particularly useful when including PL/SQL program units or SQL queries that might require special characters.

Syntax

Following is the syntax for this tag:

<![CDATA[
   content
]]>

Examples

The following example shows a segment of an XML report definition that uses the <![CDATA[]]> tag to protect a PL/SQL function that adds a hyperlink and hyperlink destination to an object in a report.

 <programUnits> 
 <function name="F_ssn1FormatTrigger"> 
   <![CDATA[
   function F_ssn1FormatTrigger return boolean is
   begin
     SRW.SET_HYPERlink('#EMP_DETAILS_&<' || LTRIM(TO_CHAR(:SSN)) || '>');
     return (TRUE);
   end;
  ]]>
  </function> 
  <function name="F_ssnFormatTrigger"> 
  <![CDATA[
   function F_ssnFormatTrigger return boolean is
   begin
     SRW.SET_linkTAG('EMP_DETAILS_&<' || LTRIM(TO_CHAR(:SSN)) || '>');
     return (TRUE);
   end;
  ]]>
  </function> 
 </programUnits>

The following example shows a segment of an XML report definition that uses the <![CDATA[]]> tag to protect a SQL statement that contains a greater than sign.

<select>
  <![CDATA[
   SELECT ALL VIDEO_CATEGORY_BY_QTR.QUARTER, 
          VIDEO_CATEGORY_BY_QTR.TOTAL_PROFIT
   FROM SCOTT.VIDEO_CATEGORY_BY_QTR
   WHERE (VIDEO_CATEGORY_BY_QTR.SALES_REGION='West'
         AND VIDEO_CATEGORY_BY_QTR.TOTAL_PROFIT>2000)    
  ]]>
</select>

7.5.3 <condition>

Description

The <condition> tag defines the conditions under which a formatting exception is applied to a field. The <condition> tag must be nested within an <exception> tag.

Refer to Section 7.5.7, "<exception>" for more information.

Syntax

Following is the syntax for this tag:

<condition 
  source="source_column_name"
  operator="eq | lt | lteq | neq | gt | gteq | btw | notBtw | like | notLike
     | null | notNull"
  [operand1="comparison_value"]
  [operand2="comparison_value"]
  [relation="and | or"]
/>

Attributes

The following table describes the attributes of the <condition> tag:

Table 7-2 <condition> Tag Attributes

Attribute	Required or Optional	Description
source	Required	Is the name of the source column to be used in the condition.
operator	Required	Is the operator to use in comparing other values to the source column. The valid operators are: eq (equal) lt (less than) lteq (less than or equal) neq (not equal) gt (greater than) gteq (greater than or equal) btw (between) notBtw (not between) like notLike null notNull
operand1	Optional	Is the value to which the source column is being compared. If the operator is null or notNull, then no operands are required. If the operator is btw or notBtw, then you must also specify operand2.
operand2	Optional	Is the second value to which the source column is being compared. You only need to use operand2 if the operator requires two values for comparison (that is, if the operator is btw or notBtw)
relation	Optional	Defines whether there are multiple conditions and, if there are, how they should be related. The and means that the formatting exception is applied only if both are met. The or means that the formatting exception is applied if either condition is met.

Usage Note

Two conditions can be joined by entering the relation attribute in the first condition tag, which must include either of the operators and or or.

Example

The following example shows two formatting exceptions for field f_ename. The first exception changes the text color to red if both of its conditions are met. The second exception changes the text color to blue if its condition is met.

<field name="f_ename" source="ename" label="Employee" textColor="green">
   <exception textColor="red">
     <condition source="deptno" operator="btw" operand1="20" 
                  operand2="30" relation="and"/>
     <condition source="sal" operator="gt" operand1="1000"/>
   </exception>
  <exception textColor="blue">
   <condition source="deptno" operator="eq" operand1="30"/>
  </exception>
</field>

7.5.4 <customize>

Description

The <customize> tag delimits any object properties that you want to specify as part of the report definition. The tags nested within the <customize> tag (<object> <properties> and <property>) enable you to set properties for certain objects in the report.

Syntax

Following is the syntax for this tag:

<customize>
   content_of_data_model
</customize>

Examples

The following example shows the object property segment of an XML report definition.

<customize>
   <object name="videosales" type="REP_REPORT">
   <properties>
    <property name="beforeReportType">File</property>
    <property name="beforeReportValue">
         d:\xml_reps\header_example.html
    </property>
    <property name="afterReportType">Text</property>
    <property name="afterReportValue">
     <![CDATA[
      <center>
      <font face="Arial,Helvetica"><font size=-1><font color="#000000">
        Send questions to <a href="mailto:your_email_id">YourNameHere</a>.
        <br>&nbsp;
      </font>
      </center>
      </body>
      </html>
     ]]>
    </property>
   </properties>
  </object>
 </customize>

The following example shows a segment of an XML report definition that changes some boilerplate text. This is useful for changing labels for existing fields.

<customize>
 <object name="B_high_365" type="REP_GRAPHIC_TEXT">
  <properties>
   <property name="textSegment">High</property>
  </properties>
 </object>
 <object name="B_low_365" type="REP_GRAPHIC_TEXT">
  <properties>
   <property name="textSegment">Low</property>
  </properties>
 </object>
</customize>

7.5.5 <data>

Description

The <data> tag delimits the beginning and ending of the data model of the report definition.

Syntax

Following is the syntax for this tag:

<data>
   content_of_data_model
</data>

Example

The following example shows the data model segment of an XML report definition:

<data>
 <dataSource name="q_category">
  <select>
    SELECT          ic.category,
                       SUM (h.sales),
                       AVG (h.high_365),
                       AVG (h.low_365),
                       AVG (h.div),
                       AVG (h.p_e)
    FROM stock_history h, indcat ic
    WHERE h.symbol=ic.symbol
    GROUP BY ic.category
   </select>
  </dataSource>
 </data>

The following example shows a segment of an XML report definition that uses the <![CDATA[]]> tag to protect a SQL statement that contains a greater than sign:

<data>
 <dataSource name="Q_1">
  <select>
    <![CDATA[
     SELECT ALL VIDEO_CATEGORY_BY_QTR.QUARTER, 
            VIDEO_CATEGORY_BY_QTR.TOTAL_PROFIT
     FROM SCOTT.VIDEO_CATEGORY_BY_QTR
     WHERE (VIDEO_CATEGORY_BY_QTR.SALES_REGION='West'
           AND VIDEO_CATEGORY_BY_QTR.TOTAL_PROFIT>2000)    
    ]]>
  </select>
 </dataSource>
</data>

7.5.6 <dataSource>

Description

The <dataSource> tag delimits the beginning and ending of a query in the data model. The <dataSource> tag must be nested within the <data> tag. All of the data sources supported by Oracle Reports Services (SQL and Express) are supported by this tag.

Syntax

Following is the syntax for this tag:

<dataSource>
   content_of_data_source
</dataSource>

Examples

The following example shows the data model segment of an XML report definition:

<data>
 <dataSource name="q_category">
  <select>
    SELECT          ic.category,
                       SUM (h.sales),
                       AVG (h.high_365),
                       AVG (h.low_365),
                       AVG (h.div),
                       AVG (h.p_e)
    FROM stock_history h, indcat ic
    WHERE h.symbol=ic.symbol
    GROUP BY ic.category
   </select>
  </dataSource>
 </data>

The following example shows a segment of an XML report definition that uses the <![CDATA[]]> tag to protect a SQL statement that contains a greater than sign:

<data>
 <dataSource name="Q_1">
  <select>
    <![CDATA[
     SELECT ALL VIDEO_CATEGORY_BY_QTR.QUARTER, 
            VIDEO_CATEGORY_BY_QTR.TOTAL_PROFIT
     FROM SCOTT.VIDEO_CATEGORY_BY_QTR
     WHERE (VIDEO_CATEGORY_BY_QTR.SALES_REGION='West'
           AND VIDEO_CATEGORY_BY_QTR.TOTAL_PROFIT>2000)    
    ]]>
  </select>
 </dataSource>
</data>

7.5.7 <exception>

Description

The <exception> tag delimits a formatting exception that you want to apply to a field (for example, the field should turn red when the value exceeds some limit). The <exception> tag must be nested within a <field> tag. It must also have a <condition> tag nested within it that defines the condition under which to apply the formatting exception.

For more information refer to:

Syntax

Following is the syntax for this tag:

<exception 
  [lineColor="color_name | noLine"]
  [fillColor="color_name | noFill"]
  [textColor="color_name"]
  [hide="yes | no"]
  [font="font_name"]
>
  condition_definition
</exception>

Attributes

The following table describes the attributes of the <exception> tag:

Table 7-3 <exception> Tag Attributes

Attribute	Required or Optional	Description
lineColor	Optional	Is the name of the border color to apply when the condition is met. If noLine is specified, then the border is transparent (that is, invisible).
fillColor	Optional	Is the name of the fill color to apply when the condition is met. If noFill is specified, then the background is transparent.
textColor	Optional	Is the name of the text color to apply when the condition is met.
hide	Optional	Determines whether to hide the field when the condition is met. A yes means the field is hidden when the condition is met. A no means the field is not be hidden when the condition is met.
font	Optional	Is the name of the font to apply when the condition is met.
fontSize	Optional	Is the size of the font to be used when the condition is met.
fontStyle	Optional	Is the style of the font to be used when the condition is met. The valid styles are: regular italic bold boldItalic
fontEffect	Optional	Is the effect of the font to be used when the condition is met. The valid values are: regular strikeout underline strikeoutUnderline

Usage Notes

The following usage notes apply:

Exceptions are processed in the order they appear in the field.
Each exception can have up to three conditions.
There is no limit on the number of exceptions that can be applied to a field, except for the PL/SQL maximum length restriction for the resulting format trigger.
If multiple exceptions exist, then they are controlled by an implicit OR relation, which means that as soon as one of the exceptions has been applied (that is, satisfied), no other exceptions will be processed.

Example

<field name="f_ename" source="ename" label="Employee" textColor="green">
   <exception textColor="red">
     <condition source="deptno" operator="btw" operand1="1" 
                  operand2="20" relation="and"/>
     <condition source="sal" operator="gt" operand1="1000"/>
   </exception>
  <exception textColor="blue">
   <condition source="deptno" operator="eq" operand1="30"/>
  </exception>
</field>

7.5.8 <field>

Description

The <field> tag defines a field in the layout of the report definition and assigns attributes to it. The <field> tag must be nested within the <layout> tag. Most of the other layout tags require a <field> nested within them (for example, <tabular>, <group>, and <matrixCell>). The <field> tag modifies existing fields in an .RDF file, if you use the same field name. Otherwise, it can be used to create an entirely new field in the report.

The <field> tag can also contain the <labelAttribute> and <exception> tags.

You can end the <field> tag with /> or </field>. The latter is the method you must use if you are including an <exception> or <labelAttribute> inside the <field> tag. The example below illustrates both methods of ending the <field> tag.

<field name="f_deptno" label="Department" source="deptno"/>
<field name="f_mgr" label="Manager" source="mgr">
  <labelAttribute textColor="red" alignment="center"/>
</field>

For more information refer to:

Syntax

<field
  name="field_name"
  source="source_column"
  [label="field_label"]
  [currency="currency_symbol"]
  [tsep="separator_character"]
  [formatTrigger="plsql_program_unit"]
  [font="font_name"]
  [fontSize="point_size"]
  [fontStyle="regular | italic | bold | boldItalic"]
  [fontEfffect="regular | strikeout | underline | strikeoutUnderline"]
  [lineColor="color_name | noLine"]
  [fillColor="color_name | noFill"]
  [textColor="color_name"]
  [alignment="start | left | center | right | end"]
  [hyperlink="URL"]
  [linkdest="hyperlink_target"]
  [formatMask="mask"]
/> | >[other_tags]</field>

Attributes

The following table describes the attributes of the <field> tag:

Table 7-4 <field> Tag Attributes

Attribute	Required or Optional	Description
name	Required	Is the identifier for the field. If the name matches that of a field in an `.RDF` file to which the XML is being applied, then the attributes specified overrides those in the `.RDF` file.
source	Required, for creating new fields Optional, for modifying existing fields	Is the source column from which the field gets its data. The source column must exist in the data model.
label	Optional	Is the boilerplate text to be associated with the field. To control the formatting attributes of the label, you must use the <labelAttribute> tag. Refer to Section 7.5.15, "<labelAttribute>", for more information. The label attribute only affects new fields, it does not change the label of an existing field in the `.RDF` file. To change the label of an existing field, you can use the <object> tag. Refer to Section 7.5.22, "<object>", for more information.
currency	Optional	Is the currency symbol to be used with the field (for example, $). You must still specify the formatMask attribute to indicate where you want the currency symbol placed.
tsep	Optional	Is the separator character that you want to use when generating delimited output. The most commonly used delimiter is a tab, which can be read by spreadsheet programs such as Microsoft Excel.
formatTrigger	Optional	Is the name of a PL/SQL program unit that is to be used as the format trigger for the field. Format triggers must be functions. For more information refer to the Oracle Reports Builder online help system and look for format trigger in the index.
font	Optional	Is the name of the font to be used for the field contents.
fontSize	Optional	Is the size of the font to be used for the field contents.
fontStyle	Optional	Is the style of the font to be used for the field contents. The valid values are: regular italic bold boldItalic
fontEffect	Optional	Is the effect of the font to be used for the field contents. The valid values are: regular strikeout underline strikeoutUnderline
lineColor	Optional	Is the name of the color to be used for the border of the field. If noLine is specified, then the field's border is transparent (that is, invisible).
fillColor	Optional	Is the name of the color to be used as the background for the field. If noFill is specified, then the background is transparent.
textColor	Optional	Is the name of the color to be used for the field contents.
alignment	Optional	Is how the text should be justified within the field. The valid values are: start left center right end
hyperlink	Optional	Is a URL to be associated with the field contents when HTML or PDF output is generated. This attribute is ignored for other types of output such as PostScript or ASCII.
linkdest	Optional	Is the target to be used when hyperlinking to this field's contents. This attribute is only used when generating HTML or PDF output. It is ignored for other types of output such as PostScript or ASCII.
formatMask	Optional	Is the mask to be applied when displaying the field's contents. For more information on the format mask syntax, refer to the Oracle Reports Builder online help system and look under format mask in the index.

Examples

The following example shows a section in the layout of a report definition that defines fields within two break groups for a matrix report:

<group>
   <field name="f_quarter" source="quarter" label="Quarter:" 
          font="Arial" fontSize="8"
          formatTrigger="F_quarterFormatTrigger">
          <labelAttribute font="Arial" fontSize="8" 
                          fontStyle="bold" textColor="black"/>
   </field>
   <field name="f_SumTOTAL_SALESPerQUARTER"
          source="SumTOTAL_SALESPerQUARTER"
          label="Qtrly:  Sales: " font="Arial" fontSize="8" fontStyle="bold"
          formatMask="LNNNGNNNGNNNGNN0D00">
          <labelAttribute font="Arial" fontSize="8" 
                             fontStyle="bold" textColor="black"/>
   </field>
   <field name="f_SumTOTAL_COSTPerQUARTER" source="SumTOTAL_COSTPerQUARTER"
          label="Costs: " font="Arial" fontSize="8" fontStyle="bold"
          formatMask="LNNNGNNNGNNNGNN0D00">
          <labelAttribute font="Arial" fontSize="8" 
                          fontStyle="bold" textColor="black"/>
   </field>
   <field name="f_SumTOTAL_PROFITPerQUARTER"
          source="SumTOTAL_PROFITPerQUARTER"
          label="Profits: " font="Arial" fontSize="8" fontStyle="bold"
          formatMask="LNNNGNNNGNNNGNN0D00">
          <labelAttribute font="Arial" fontSize="8" 
                          fontStyle="bold" textColor="black"/>
   </field>
</group>
<group>
   <field name="f_state" source="state" label="State:"
          font="Arial" fontSize="8">
         <labelAttribute font="Arial" fontSize="8" 
                         fontStyle="bold" textColor="black"/>
   </field> 
</group>

The following example shows a section in the layout of a report definition that defines a field within a break group for a group left report. The formatTrigger attribute points to a function that would be defined within the <programUnits> tag.

<group>
    <field name="f_quarter1" source="quarter1" label="Quarter" 
           font="Arial" fontSize="8"
           formatTrigger="F_quarter1FormatTrigger">
           <labelAttribute font="Arial" fontSize="8" 
                           fontStyle="bold" textColor="yellow"/>
    </field>
</group>

7.5.9 <formLike>

Description

The <formLike> tag delimits a form style within a section of the report's layout. If you use the <formLike> tag, then you must also nest <field> tags to list the fields you want to include in the form layout.

Refer to Section 7.5.8, "<field>" for more information on the <field> tag

Syntax

Following is the syntax for this tag:

<formLike> 
  <field>
  </field> 
  [...]
</formLike>

Example

The following example shows a segment of an XML report definition that defines a section with a form layout inside of it:

<section name="main">
   <formLike name="M_empform" template="corp2.tdf">
    <labelAttribute textColor="green" alignment="center"/>
    <field name="f_deptno" source="deptno" label="Department"/>
    <field name="f_mgr" source="mgr" label="Manager">
      <labelAttribute textColor="red" alignment="center"/>
    </field>
    <field name="f_job" label="Job" source="job"/>
   </formLike>
</section>

7.5.10 <formula>

Description

The <formula> tag defines a formula column in the data model of the report definition. A formula column uses a PL/SQL function to perform an operation, typically a complex calculation of some kind. If you are performing a common calculation (for example, sum, percent of total, or standard deviation), then you can use the <summary> tag, which requires no PL/SQL.

Refer to Section 7.5.29, "<summary>" for more information.

Syntax

Following is the syntax for this tag:

<formula
  name="column_name"
  source="plsql_function_name"
  dataType="number | character | date"
  width="number"
/>

Attributes

The following table describes the attributes of the <formula> tag:

Table 7-5 <formula> Tag Attributes

Attribute	Required or Optional	Description
name	Required	Is the name of the formula column.
source	Required	Is the name of a PL/SQL function defined within the <programUnits> tag that performs the desired operation for the formula.
dataType	Optional	Is the type of data that is generated by the formula. For example, if the formula performs a mathematical operation, then the result is a number. The possible values for dataType are: number character date
width	Optional	Is the number of characters wide of the result of the formula.

Example

The following example shows a segment of an XML report definition that defines a data model with a formula column in it. The defaulting algorithm places the column in the appropriate group based on where you place its associated fields in the <layout> section.

<data>
 <dataSource name="Q_1">
  <select>
   SELECT ALL VIDEO_CATEGORY_BY_QTR.QUARTER, 
          VIDEO_CATEGORY_BY_QTR.SALES_REGION,
          VIDEO_CATEGORY_BY_QTR.STATE, VIDEO_CATEGORY_BY_QTR.CITY, 
          VIDEO_CATEGORY_BY_QTR.PRODUCT_CATEGORY, 
          VIDEO_CATEGORY_BY_QTR.TOTAL_SALES,
          VIDEO_CATEGORY_BY_QTR.TOTAL_COST,VIDEO_CATEGORY_BY_QTR.TOTAL_PROFIT
   FROM SCOTT.VIDEO_CATEGORY_BY_QTR
   WHERE VIDEO_CATEGORY_BY_QTR.SALES_REGION='West'
  </select>
 </dataSource>
 <dataSource name="Q_2">
  <select>
   SELECT ALL VIDEO_CATEGORY_BY_QTR.QUARTER, VIDEO_CATEGORY_BY_QTR.CITY, 
          VIDEO_CATEGORY_BY_QTR.PRODUCT_CATEGORY, 
          VIDEO_CATEGORY_BY_QTR.TOTAL_PROFIT,
          VIDEO_CATEGORY_BY_QTR.TOTAL_SALES,
          VIDEO_CATEGORY_BY_QTR.TOTAL_COST
   FROM SCOTT.VIDEO_CATEGORY_BY_QTR
   WHERE VIDEO_CATEGORY_BY_QTR.SALES_REGION='West'
  </select> 
 </dataSource>
 <formula name="Profit_Margin" source="FormulaProfitMargin" 
           datatype="number" width="9"/>
</data>
<programUnits> 
 <function name="FormulaProfitMargin"> 
  <![CDATA[ 
  FUNCTION FormulaProfitMargin RETURN number IS 
  BEGIN 
    return ((:TOTAL_PROFIT1 / (:TOTAL_SALES1 - (0.07 * :TOTAL_SALES1))) *
100); 
  END; 
  ]]> 
 </function> 
</programUnits>

7.5.11 <function>

The <function> tag defines a PL/SQL function that you want to add to the report definition. The <function> tag must be nested within a <programUnits> tag. To reference a function, you use the formatTrigger attribute of the <field> tag.

For more information refer to:

Syntax

Following is the syntax for this tag:

<function 
  name="function_name"
>
   PLSQL_function
</function>

Attributes

The following table describes the attributes of the <function> tag:

Table 7-6 <function> Tag Attributes

Attribute	Required or Optional	Description
name	Required	Is the identifier for the function. This is the name that should be used when referencing the function (for example, from the formatTrigger attribute of the <field> tag).

Example

The following example shows a segment of an XML report definition that defines some PL/SQL functions. The functions are referenced from fields in the layout through the formatTrigger attribute.

<layout>
  <section name="header"> 
    <field name="F_ssn1" 
           source="ssn1" 
           formatTrigger="F_ssn1FormatTrigger"/>
  </section>
  <section name="main">
    <field name="F_ssn" 
           source="ssn" 
           formatTrigger="F_ssnFormatTrigger"/>     
  </section>
</layout>
<programUnits> 
 <function name="F_ssn1FormatTrigger"> 
  <![CDATA[
     function F_ssn1FormatTrigger return boolean is
       begin
         SRW.SET_HYPERLINK('#EMP_DETAILS_&<' || LTRIM(TO_CHAR(:SSN)) ||
'>');
         return (TRUE);
       end;
  ]]>
 </function> 
 <function name="F_ssnFormatTrigger"> 
 <![CDATA[
    function F_ssnFormatTrigger return boolean is
      begin
        SRW.SET_LINKTAG('EMP_DETAILS_&<' || LTRIM(TO_CHAR(:SSN)) || '>');
        return (TRUE);
      end;
  ]]>
 </function> 
</programUnits>

7.5.12 <group>

Description

The <group> tag delimits the master group in a master-detail style layout. The <group> tag can only be nested within a <groupLeft>, <groupAbove>, or <matrix> tag. You must nest <field> tags within the <group> tag to list the fields you want to include in the master group.

For more information refer to:

Syntax

Following is the syntax for this tag:

<group>
   master_group_content
</group>

Example

The following example shows a section in the layout of a report definition that defines fields within two break groups for a matrix report.

<group>
   <field name="f_quarter" source="quarter" label="Quarter:" 
          font="Arial" fontSize="8"
          formatTrigger="F_quarterFormatTrigger">
          <labelAttribute font="Arial" fontSize="8" 
                          fontStyle="bold" textColor="black"/>
   </field>
   <field name="f_SumTOTAL_SALESPerQUARTER"
          source="SumTOTAL_SALESPerQUARTER"
          label="Qtrly:  Sales: " font="Arial" fontSize="8" fontStyle="bold"
          formatMask="LNNNGNNNGNNNGNN0D00">
          <labelAttribute font="Arial" fontSize="8" 
                             fontStyle="bold" textColor="black"/>
   </field>
   <field name="f_SumTOTAL_COSTPerQUARTER" source="SumTOTAL_COSTPerQUARTER"
          label="Costs: " font="Arial" fontSize="8" fontStyle="bold"
          formatMask="LNNNGNNNGNNNGNN0D00">
          <labelAttribute font="Arial" fontSize="8" 
                          fontStyle="bold" textColor="black"/>
   </field>
   <field name="f_SumTOTAL_PROFITPerQUARTER"
          source="SumTOTAL_PROFITPerQUARTER"
          label="Profits: " font="Arial" fontSize="8" fontStyle="bold"
          formatMask="LNNNGNNNGNNNGNN0D00">
          <labelAttribute font="Arial" fontSize="8" 
                          fontStyle="bold" textColor="black"/>
   </field>
</group>
<group>
   <field name="f_state" source="state" label="State:"
          font="Arial" fontSize="8">
         <labelAttribute font="Arial" fontSize="8" 
                         fontStyle="bold" textColor="black"/>
   </field> 
</group>

7.5.13 <groupAbove>

Description

The <groupAbove> tag delimits a master-detail style within a section of the report's layout. The master records are placed above the detail records. If you use the <groupAbove> tag, then you must also nest a <group> tag to identify the master group as well as <field> tags to list the fields you want to include in the group above layout.

For more information refer to:

Syntax

Following is the syntax for this tag:

<groupAbove
   name="style_name"
>
   <group>
      master_group_content
   </group>
   detail_group_content
</groupAbove>

Example

The following example shows a segment of an XML report definition that defines a section with a <groupAbove> layout inside of it:

<section name="main">
   <groupAbove name="m_emp">
    <labelAttribute font="Arial" fontSize="10" fontStyle="bold"/>
    <group>
      <field name="f_deptno" source="deptno" label="Department "
             font="Arial" fontSize="10"/>
      <field name="f_sumsal" label="Total Salary" source="sumsal" 
             textColor="red" font="Arial" fontSize="10" 
             fontStyle="bold">
        <labelAttribute font="Arial" fontSize="10" fontStyle="bold" 
                        textColor="red"/>
      </field>
    </group>
    <field name="f_ename" source="ename" label="Name"
           font="Arial" fontSize="10"/>
    <field name="f_sal" source="sal" label="Salary"
           font="Arial" fontSize="10"/>
   </groupAbove>
</section>

7.5.14 <groupLeft>

Description

The <groupLeft> tag delimits a master-detail style within a section of the report's layout. The master records are placed to the left of the detail records. If you use the <groupLeft> tag, then you must also nest a <group> tag to identify the master group as well as <field> tags to list the fields you want to include in the <groupLeft> layout.

For more information refer to:

Syntax

Following is the syntax for this tag:

<groupLeft
   name="style_name"
>
   <group>
      master_group_content
   </group>
   detail_group_content
</groupLeft>

Example

The following example shows a segment of an XML report definition that defines a section with a group left layout inside of it:

<section name="main">
   <groupLeft name="m_emp">
    <labelAttribute font="Arial" fontSize="10" fontStyle="bold"/>
    <group>
      <field name="f_deptno" source="deptno" label="Department "
             font="Arial" fontSize="10"/>
      <field name="f_sumsal" label="Total Salary" source="sumsal" 
             textColor="red" font="Arial" fontSize="10" 
             fontStyle="bold">
        <labelAttribute font="Arial" fontSize="10" fontStyle="bold" 
                        textColor="red"/>
      </field>
    </group>
    <field name="f_ename" source="ename" label="Name"
           font="Arial" fontSize="10"/>
    <field name="f_sal" source="sal" label="Salary"
           font="Arial" fontSize="10"/>
   </groupLeft>
</section>

7.5.15 <labelAttribute>

Description

The <labelAttribute> tag defines the formatting attributes for field labels. The <labelAttribute> tag can be nested within a <field> tag or within a layout style tag (for example, <tabular> or <matrix>). If <labelAttribute> is nested inside a <field> tag, then it applies only to the labels for that field.

The <labelAttribute> tag only affects new fields, it does not change the label of an existing field in the .RDF file. To change the text of an existing label, you should use the textSegment attribute of the <property> tag.

For more information refer to:

Syntax

Following is the syntax for this tag:

<labelAttribute 
  [font="font_name"]
  [fontSize="point_size"]
  [fontStyle="regular | italic | bold | boldItalic"]
  [fontEfffect="regular | strikeout | underline | strikeoutUnderline"]
  [lineColor="color_name | noLine"]
  [fillColor="color_name | noFill"]
  [textColor="color_name"]
  [alignment="start | left | center | right | end"]
>
</labelAttribute>

Attributes

The following table describes the attributes of the <labelAttribute> tag:

Table 7-7 <labelAttribute> Tag Attributes

Attribute	Required or Optional	Description
font	Optional	Is the name of the font to be used for the field label.
fontSize	Optional	Is the size of the font to be used for the field label.
fontStyle	Optional	Is the style of the font to be used for the field label. The valid values are: regular italic bold boldItalic
fontEffect	Optional	Is the effect of the font to be used for the field contents. The valid values are: regular strikeout underline strikeoutUnderline
lineColor	Optional	Is the name of the color to be used for the border of the field. If noLine is specified, then the field's border is transparent (that is, invisible).
fillColor	Optional	Is the name of the color to be used as the background for the field. If noFill is specified, then the background is transparent.
textColor	Optional	Is the name of the color to be used for the field contents.
alignment	Optional	Is how the text should be justified within the field. The valid values are: start left center right end

Example

The following example shows a segment of an XML report definition that defines a section with a group left layout inside of it. The first <labelAttribute> tag would apply to all of the fields in the layout except for f_sumsal, which has its own embedded <labelAttribute> tag.

<section name="main">
   <groupLeft name="m_emp">
    <labelAttribute font="Arial" fontSize="10" fontStyle="bold"/>
    <group>
      <field name="f_deptno" source="deptno" label="Department "
             font="Arial" fontSize="10"/>
      <field name="f_sumsal" label="Total Salary" source="sumsal" 
             textColor="red" font="Arial" fontSize="10" 
             fontStyle="bold">
        <labelAttribute font="Arial" fontSize="10" fontStyle="bold" 
                        textColor="red"/>
      </field>
    </group>
    <field name="f_ename" source="ename" label="Name"
           font="Arial" fontSize="10"/>
    <field name="f_sal" source="sal" label="Salary"
           font="Arial" fontSize="10"/>
   </groupLeft>
</section>

7.5.16 <layout>

Description

The <layout> tag delimits the beginning and ending of the layout of the report definition.

Syntax

Following is the syntax for this tag:

<layout>
   content_of_layout
</layout>

Examples

The following example shows the layout segment of an XML report definition. This is not a complete layout model and would have to be applied as a customization to an .RDF file:

<layout>
   <section name="main">
     <field name="f_trade_date" 
            source="trade_date" 
            formatMask="MM/DD/RR"/>
     <field name="F_Mincurrent_pricePersymbol" 
            source="Mincurrent_pricePersymbol" 
            lineColor="black" 
      fillColor="r100g50b50"/>
     <field name="F_Maxcurrent_pricePersymbol"
            source="Maxcurrent_pricePersymbol"
            lineColor="black" 
            fillColor="r100g50b50"/>
   </section>
 </layout>

The following example shows another layout segment of an XML report definition. This is a complete layout and, assuming the appropriate data model is in place, it could stand by itself, without being applied to an .RDF file.

<layout>
  <section name="main"> 
   <matrix name="M_video_sales" template="corp10.tdf">
    <group>
       <field name="f_quarter" source="quarter" label="Quarter:" 
              font="Arial" fontSize="8"
              formatTrigger="F_quarterFormatTrigger">
         <labelAttribute font="Arial" fontSize="8" 
                         fontStyle="bold" textColor="black"/>
       </field>
       <field name="f_SumTOTAL_SALESPerQUARTER" 
              source="SumTOTAL_SALESPerQUARTER"
              label="Qtrly:  Sales: " font="Arial" fontSize="8"
              fontStyle="bold"
              formatMask="LNNNGNNNGNNNGNN0D00">
          <labelAttribute font="Arial" fontSize="8" 
                          fontStyle="bold" textColor="black"/>
       </field>
       <field name="f_SumTOTAL_COSTPerQUARTER"
              source="SumTOTAL_COSTPerQUARTER"
              label="Costs: " font="Arial" fontSize="8" fontStyle="bold"
              formatMask="LNNNGNNNGNNNGNN0D00">
          <labelAttribute font="Arial" fontSize="8" 
                          fontStyle="bold" textColor="black"/>
       </field>
       <field name="f_SumTOTAL_PROFITPerQUARTER" 
              source="SumTOTAL_PROFITPerQUARTER"
              label="Profits: " font="Arial" fontSize="8" fontStyle="bold"
              formatMask="LNNNGNNNGNNNGNN0D00">
          <labelAttribute font="Arial" fontSize="8" 
                          fontStyle="bold" textColor="black"/>
       </field>
    </group>
    <group>
       <field name="f_state" source="state" label="State:"
              font="Arial" fontSize="8">
         <labelAttribute font="Arial" fontSize="8" 
                         fontStyle="bold" textColor="black"/>
       </field> 
    </group>
    <matrixCol name="g_city">
       <field name="f_city" source="city" label="City: "
              font="Arial" fontSize="8" textColor="yellow"
              formatTrigger="F_cityFormatTrigger"/>
       <field name="f_SumTOTAL_SALESPerCITY" source="SumTOTAL_SALESPerCITY"
              label="Sales: " font="Arial" fontSize="8" fontStyle="bold"
              textColor="yellow" formatMask="LNNNGNNNGNNNGNN0D00">
          <labelAttribute font="Arial" fontSize="8" 
                          fontStyle="bold" textColor="yellow"/>
       </field>
       <field name="f_SumTOTAL_COSTPerCITY" source="SumTOTAL_COSTPerCITY"
              label="Sales: " font="Arial" fontSize="8" fontStyle="bold"
              textColor="yellow" formatMask="LNNNGNNNGNNNGNN0D00">
          <labelAttribute font="Arial" fontSize="8" 
                          fontStyle="bold" textColor="yellow"/>
       </field>
       <field name="f_SumTOTAL_PROFITPerCITY"
              source="SumTOTAL_PROFITPerCITY"
              label="Sales: " font="Arial" fontSize="8" fontStyle="bold"
              textColor="yellow" formatMask="LNNNGNNNGNNNGNN0D00">
          <labelAttribute font="Arial" fontSize="8" 
                          fontStyle="bold" textColor="yellow"/>
       </field>
    </matrixCol>
    <matrixRow name="g_product_category">
       <field name="f_product_category" source="product_category" 
              label="Product Category" font="Arial" fontSize="8"/>       
    </matrixRow>
    <matrixCell name="g_total_sales">
     <field name="f_total_sales" source="total_sales" label="Total Sales"
            font="Arial" fontSize="8" lineColor="noLine"
            formatMask="LNNNGNNNGNNNGNN0D00"/>
     <field name="f_total_cost" source="total_cost" label="Total Cost"
            font="Arial" fontSize="8" lineColor="noLine"
            formatMask="LNNNGNNNGNNNGNN0D00"/>
     <field name="f_total_profit" source="total_profit" label="Total Profit"
            font="Arial" fontSize="8" lineColor="noLine"
            formatMask="LNNNGNNNGNNNGNN0D00"/>
    </matrixCell>
   </matrix>
  </section>
 </layout>

7.5.17 <link>

Description

The <link> tag defines a link between data sources in the data model. The <link> tag must be nested within the <data> tag. Data sources are linked by columns. Hence each column link requires parent and child column attributes and a condition attribute that relates the columns. In order to join two tables or views, the foreign key columns must have a column alias in the SELECT statements. (These aliases are used to reference the parent and child column in the column link specification.)

Syntax

Following is the syntax for this tag:

<link 
     parentGroup="parent_group_name"
     parentColumn="parent_column_name" 
     childQuery="child_query_name"
     childColumn="child_column_name" 
     condition="eq  | lt | lteq | neq | gt | gteq | like | notLike"
     sqlClause="startWith | having | where"
     name="link_name"
> 
</link>

Attributes

The following table describes the attributes of the <link> tag:

Table 7-8 <link> Tag Attributes

Attribute	Required or Optional	Description
parentGroup	Required for group links Optional for column links	Is the name of the parent group that you want to relate to the child query.
parentColumn	Required for column links Ignored for group links	Is the name of a column in the parent query that relates to a column in the child query (that is, child column).
childQuery	Required for group links Optional for column links	Is the name of the child query that relates to the parent group.
childColumn	Required for column links Ignored for group links	Is the name of a column in the child query that relates to a column in the parent query (that is, parent column).
condition	Required	Is a SQL operator that defines the relationship between parent column and child column. Condition can have the following values: eq (equal to) lt (less than) lteq (less than or equal to) neq (not equal to) gt (greater than) gteq (greater than or equal to) Like (means that the condition is true when the value in one column matches the pattern in the other column. The pattern can contain % and _ as wildcard characters.) notLike (means that the condition is true when the value in one column does not match the pattern in the other column. The pattern can contain % and _ as wildcard characters.)
sqlClause	Required	Is the type of SQL clause that relates the parent group to the child query. The default is a WHERE clause.

Example

The following example shows the data model segment of a report definition with a link between two queries:

<data>
  <dataSource name="Q_dept">
   <select>
     select deptno deptno_dept from dept
   </select>
  </dataSource>
  <dataSource name="Q_emp">  
   <select>
     select deptno deptno_emp, ename, empno, sal from emp
   </select>
  </dataSource>
  <link       parentColumn="deptno_dept" 
              childColumn="deptno_emp" 
              condition="eq" 
              sqlClause="where"/>
</data>

7.5.18 <matrix>

Description

The <matrix> tag delimits a matrix style within a section of the report's layout. If you use the <matrix> tag, then you must also nest <matrixRow>, <matrixCol>, and <matrixCell> tags to identify the parts of the matrix as well as <field> tags to list the fields you want to include in the matrix layout.

A <group> tag can also be used in conjunction with <matrix> tags to create a matrix with group style.

For more information refer to:

Syntax

Following is the syntax for this tag:

<matrix
   name="style_name"
>
   [<group>
      master_group_content
   </group>]
   <matrixCol>
       matrix_column content
   </matrixCol>
   <matrixRow>
       matrix_row_content
   </matrixRow>
   <matrixCell>
       matrix_cell_content
   </matrixCell>
</matrix>

Example

The following example shows a segment of an XML report definition that defines a matrix with group layout:

<matrix name="M_video_sales" template="corp10.tdf">
 <group>
    <field name="f_quarter" source="quarter" label="Quarter:" 
           font="Arial" fontSize="8"
           formatTrigger="F_quarterFormatTrigger">
      <labelAttribute font="Arial" fontSize="8" 
                      fontStyle="bold" textColor="black"/>
    </field>
    <field name="f_SumTOTAL_SALESPerQUARTER" 
           source="SumTOTAL_SALESPerQUARTER"
           label="Qtrly:  Sales: " font="Arial" fontSize="8"
           fontStyle="bold"
           formatMask="LNNNGNNNGNNNGNN0D00">
       <labelAttribute font="Arial" fontSize="8" 
                       fontStyle="bold" textColor="black"/>
    </field>
    <field name="f_SumTOTAL_COSTPerQUARTER" source="SumTOTAL_COSTPerQUARTER"
           label="Costs: " font="Arial" fontSize="8" fontStyle="bold"
           formatMask="LNNNGNNNGNNNGNN0D00">
       <labelAttribute font="Arial" fontSize="8" 
                       fontStyle="bold" textColor="black"/>
    </field>
    <field name="f_SumTOTAL_PROFITPerQUARTER" 
           source="SumTOTAL_PROFITPerQUARTER"
           label="Profits: " font="Arial" fontSize="8" fontStyle="bold"
           formatMask="LNNNGNNNGNNNGNN0D00">
       <labelAttribute font="Arial" fontSize="8" 
                       fontStyle="bold" textColor="black"/>
    </field>
 </group>
 <group>
    <field name="f_state" source="state" label="State:"
           font="Arial" fontSize="8">
      <labelAttribute font="Arial" fontSize="8" 
                      fontStyle="bold" textColor="black"/>
    </field> 
 </group>
 <matrixCol name="g_city">
    <field name="f_city" source="city" label="City: "
           font="Arial" fontSize="8" textColor="yellow"
           formatTrigger="F_cityFormatTrigger"/>
    <field name="f_SumTOTAL_SALESPerCITY" source="SumTOTAL_SALESPerCITY"
           label="Sales: " font="Arial" fontSize="8" fontStyle="bold"
           textColor="yellow" formatMask="LNNNGNNNGNNNGNN0D00">
       <labelAttribute font="Arial" fontSize="8" 
                       fontStyle="bold" textColor="yellow"/>
    </field>
    <field name="f_SumTOTAL_COSTPerCITY" source="SumTOTAL_COSTPerCITY"
           label="Sales: " font="Arial" fontSize="8" fontStyle="bold"
           textColor="yellow" formatMask="LNNNGNNNGNNNGNN0D00">
       <labelAttribute font="Arial" fontSize="8" 
                       fontStyle="bold" textColor="yellow"/>
    </field>
    <field name="f_SumTOTAL_PROFITPerCITY" source="SumTOTAL_PROFITPerCITY"
           label="Sales: " font="Arial" fontSize="8" fontStyle="bold"
           textColor="yellow" formatMask="LNNNGNNNGNNNGNN0D00">
       <labelAttribute font="Arial" fontSize="8" 
                       fontStyle="bold" textColor="yellow"/>
    </field>
 </matrixCol>
 <matrixRow name="g_product_category">
    <field name="f_product_category" source="product_category" 
           label="Product Category" font="Arial" fontSize="8"/>       
 </matrixRow>
 <matrixCell name="g_total_sales">
  <field name="f_total_sales" source="total_sales" label="Total Sales"
         font="Arial" fontSize="8" lineColor="noLine"
         formatMask="LNNNGNNNGNNNGNN0D00"/>
  <field name="f_total_cost" source="total_cost" label="Total Cost"
         font="Arial" fontSize="8" lineColor="noLine"
         formatMask="LNNNGNNNGNNNGNN0D00"/>
  <field name="f_total_profit" source="total_profit" label="Total Profit"
         font="Arial" fontSize="8" lineColor="noLine"
         formatMask="LNNNGNNNGNNNGNN0D00"/>
 </matrixCell>
</matrix>

7.5.19 <matrixCell>

Description

The <matrixCell> tag delimits the cells in a matrix style layout. The <matrixCell> tag can only be nested within a <matrix> tag. You must nest <field> tags within the <matrixCell> tag to list the fields you want to include as matrix cells.

For more information refer to:

Syntax

Following is the syntax for this tag:

<matrixCell>
   master_group_content
</matrixCell>

Example

The following example shows a segment of an XML report definition that defines a matrix cell:

<matrixCell name="g_total_sales">
 <field name="f_total_sales" source="total_sales" label="Total Sales"
        font="Arial" fontSize="8" lineColor="noLine"
        formatMask="LNNNGNNNGNNNGNN0D00"/>
 <field name="f_total_cost" source="total_cost" label="Total Cost"
        font="Arial" fontSize="8" lineColor="noLine"
        formatMask="LNNNGNNNGNNNGNN0D00"/>
 <field name="f_total_profit" source="total_profit" label="Total Profit"
        font="Arial" fontSize="8" lineColor="noLine"
        formatMask="LNNNGNNNGNNNGNN0D00"/>
</matrixCell>

7.5.20 <matrixCol>

Description

The <matrixCol> tag delimits the column fields in a matrix style layout. The <matrixCol> tag can only be nested within a <matrix> tag. You must nest <field> tags within the <matrixCol> tag to list the fields you want to include as matrix columns.

For more information refer to:

Syntax

Following is the syntax for this tag:

<matrixCol> 
     master_group_content
</matrixol>

Example

The following example shows a segment of an XML report definition that defines the column dimension of a matrix layout:

<matrixCol name="g_city">
   <field name="f_city" source="city" label="City: "
          font="Arial" fontSize="8" textColor="yellow"
          formatTrigger="F_cityFormatTrigger"/>
   <field name="f_SumTOTAL_SALESPerCITY" source="SumTOTAL_SALESPerCITY"
          label="Sales: " font="Arial" fontSize="8" fontStyle="bold"
          textColor="yellow" formatMask="LNNNGNNNGNNNGNN0D00">
      <labelAttribute font="Arial" fontSize="8" 
                      fontStyle="bold" textColor="yellow"/>
   </field>
   <field name="f_SumTOTAL_COSTPerCITY" source="SumTOTAL_COSTPerCITY"
          label="Sales: " font="Arial" fontSize="8" fontStyle="bold"
          textColor="yellow" formatMask="LNNNGNNNGNNNGNN0D00">
      <labelAttribute font="Arial" fontSize="8" 
                      fontStyle="bold" textColor="yellow"/>
   </field>
   <field name="f_SumTOTAL_PROFITPerCITY" source="SumTOTAL_PROFITPerCITY"
          label="Sales: " font="Arial" fontSize="8" fontStyle="bold"
          textColor="yellow" formatMask="LNNNGNNNGNNNGNN0D00">
      <labelAttribute font="Arial" fontSize="8" 
                      fontStyle="bold" textColor="yellow"/>
   </field>
</matrixCol>

7.5.21 <matrixRow>

Description

The <matrixRow> tag delimits the row fields in a matrix style layout. The <matrixRow> tag can only be nested within a <matrix> tag. You must nest <field> tags within the <matrixRow> tag to list the fields you want to include as matrix rows.

For more information refer to:

Syntax

Following is the syntax for this tag:

<matrixRow>
   master_group_content
</matrixRow>

Example

The following example shows a segment of an XML report definition that defines the row dimension of a matrix layout:

<matrixRow name="g_product_category">
   <field name="f_product_category" source="product_category" 
          label="Product Category" font="Arial" fontSize="8"/>       
</matrixRow>

7.5.22 <object>

Description

The <object> tag identifies an object in the report whose properties you want to change. The <object> tag typically has <properties> and <property> tags nested within it.

Syntax

Following is the syntax for this tag:

<object
   name="object_name"
   type="REP_REPORT | REP_GROUP | REP_COL_MAP | REP_GRAPHIC_TEXT"
>
    property_definitions
</object>

Attributes

The following table describes the attributes of the <object> tag:

Table 7-9 <object> Tag Properties

Attribute	Required or Optional	Description
name	Required	Is the identifier for the object to which you want to apply the properties.
type	Required	Is the kind of object to which you want to apply the properties: REP_REPORT is the report itself. REP_GROUP is a group in the data model of the report. REP_COL_MAP is a column in the data model of the report. REP_GRAPHIC_TEXT is a boilerplate object in the layout of the report.

Attribute

Required or Optional

Description

name

Required

Is the identifier for the object to which you want to apply the properties.

type

Required

Is the kind of object to which you want to apply the properties:

REP_REPORT is the report itself.
REP_GROUP is a group in the data model of the report.
REP_COL_MAP is a column in the data model of the report.
REP_GRAPHIC_TEXT is a boilerplate object in the layout of the report.

Examples

The following example shows a segment of an XML report definition that defines some object properties:

<customize>
   <object name="videosales" type="REP_REPORT">
   <properties>
    <property name="beforeReportType">File</property>
    <property name="beforeReportValue">
         d:\xml_reps\header_example.html
    </property>
    <property name="afterReportType">Text</property>
    <property name="afterReportValue">
     <![CDATA[
      <center>
      <font face="Arial,Helvetica"><font size=-1><font color="#000000">
        Send questions to <a href="mailto:your_email_id">YourNameHere</a>.
        <br>&nbsp;
      </font>
      </center>
      </body>
      </html>
     ]]>
    </property>
   </properties>
  </object>
 </customize>

The following example shows a segment of an XML report definition that changes some boilerplate text. This is useful for changing labels for existing fields.

<customize>
 <object name="B_high_365" type="REP_GRAPHIC_TEXT">
  <properties>
   <property name="textSegment">High</property>
  </properties>
 </object>
 <object name="B_low_365" type="REP_GRAPHIC_TEXT">
  <properties>
   <property name="textSegment">Low</property>
  </properties>
 </object>
</customize>

7.5.23 <programUnits>

Description

The <programUnits> tag delimits any PL/SQL that you want to add to the report definition. The <programUnits> tag typically has <function> tags nested within it.

Refer to Section 7.5.11, "<function>" for more information.

Syntax

Following is the syntax for this tag:

<programUnits>
    program_unit_definitions
</programUnits>

Example

The following example shows a segment of an XML report definition that defines some PL/SQL. The <programUnits> tag is outside of the <layout> tag and that the functions are referenced from fields in the layout through the formatTrigger attribute.

<layout>
  <section name="header"> 
    <field name="F_ssn1" 
           source="ssn1" 
           formatTrigger="F_ssn1FormatTrigger"/>
  </section>
  <section name="main">
    <field name="F_ssn" 
           source="ssn" 
           formatTrigger="F_ssnFormatTrigger"/>     
  </section>
</layout>
<programUnits> 
 <function name="F_ssn1FormatTrigger"> 
  <![CDATA[
     function F_ssn1FormatTrigger return boolean is
       begin
         SRW.SET_HYPERLINK('#EMP_DETAILS_&<' || LTRIM(TO_CHAR(:SSN)) ||
'>');
         return (TRUE);
       end;
  ]]>
 </function> 
 <function name="F_ssnFormatTrigger"> 
 <![CDATA[
    function F_ssnFormatTrigger return boolean is
      begin
        SRW.SET_LINKTAG('EMP_DETAILS_&<' || LTRIM(TO_CHAR(:SSN)) || '>');
        return (TRUE);
      end;
  ]]>
 </function> 
</programUnits>

7.5.24 <properties>

Description

The <properties> tag delimits the properties of the object. The <properties> tag must be nested inside of the <object> tag and typically has <property> tags nested within it.

Syntax

Following is the syntax for this tag:

<properties>
    property_definitions
</properties>

Examples

The following example shows a segment of an XML report definition that defines an object's properties:

<customize>
   <object name="videosales" type="REP_REPORT">
   <properties>
    <property name="beforeReportType">File</property>
    <property name="beforeReportValue">
         d:\xml_reps\header_example.html
    </property>
    <property name="afterReportType">Text</property>
    <property name="afterReportValue">
     <![CDATA[
      <center>
      <font face="Arial,Helvetica"><font size=-1><font color="#000000">
        Send questions to <a href="mailto:your_email_id">YourNameHere</a>.
        <br>&nbsp;
      </font>
      </center>
      </body>
      </html>
     ]]>
    </property>
   </properties>
  </object>
 </customize>

The following example shows a segment of an XML report definition that changes some boilerplate text. This is useful for changing labels for existing fields.

<customize>
 <object name="B_high_365" type="REP_GRAPHIC_TEXT">
  <properties>
   <property name="textSegment">High</property>
  </properties>
 </object>
 <object name="B_low_365" type="REP_GRAPHIC_TEXT">
  <properties>
   <property name="textSegment">Low</property>
  </properties>
 </object>
</customize>

7.5.25 <property>

Description

The <property> tag delimits a single property of the object. The <property> tag must be nested inside of the <properties> tag and typically has some text nested within it to define the value of the property.

Syntax

Following is the syntax for this tag:

<property
   name="xmlTag | xmlAttribute | xmlSuppress | prologType | prolog |
     beforeReportValue | beforeReportType | afterReportValue | afterReportType |
     beforePageValue | beforePageType | afterPageValue | afterPageType
     beforeFormValue | beforeFormType | afterFormValue | afterFormType | 
     pageNavigationControlValue | pageNavigationControlType | textSegment
>
    property_value
</property>

Attributes

The following table describes the attributes of the <property> tag:

Table 7-10 <property> Tag Attributes

Attribute	Required or Optional	Description
name	Required	Is the name of the property that you want to specify. The available properties vary depending upon the type of object. Refer to the "Usage Notes" for more information.

Usage Notes

The following table lists the properties that are available for each type of object:

Table 7-11 Valid Properties for Object Types

Object	Valid Properties
Report object (REP_REPORT)	xmlTag xmlAttribute xmlSuppress prologType prolog beforeReportValue beforeReportType afterReportValue afterReportType beforePageValue beforePageType afterPageValue afterPageType beforeFormValue beforeFormType afterFormValue afterFormType pageNavigationControlValue pageNavigationControlType
Group object (REP_GROUP)	xmlTag xmlAttribute outerXMLTag outerXMLAttribute xmlSuppress
Column object (REP_COL_MAP)	xmlTag xmlAttribute XMLSuppress containXML
Boilerplate object (REP_GRAPHIC_TEXT)	textSegment

Examples

The following example shows a segment of an XML report definition that defines an object's properties.

<customize>
   <object name="videosales" type="REP_REPORT">
   <properties>
    <property name="beforeReportType">File</property>
    <property name="beforeReportValue">
         d:\xml_reps\header_example.html
    </property>
    <property name="afterReportType">Text</property>
    <property name="afterReportValue">
     <![CDATA[
      <center>
      <font face="Arial,Helvetica"><font size=-1><font color="#000000">
        Send questions to <a href="mailto:your_email_id">YourNameHere</a>.
        <br>&nbsp;
      </font>
      </center>
      </body>
      </html>
     ]]>
    </property>
   </properties>
  </object>
 </customize>

The following example shows a customization section that changes the text in a boilerplate object. This is useful for changing labels for existing fields.

<customize>
 <object name="B_high_365" type="REP_GRAPHIC_TEXT">
  <properties>
   <property name="textSegment">High</property>
  </properties>
 </object>
 <object name="B_low_365" type="REP_GRAPHIC_TEXT">
  <properties>
   <property name="textSegment">Low</property>
  </properties>
 </object>
</customize>

7.5.26 <report>

Description

The <report> tag delimits the beginning and ending of the report definition. You can append attributes that apply to the entire report to the <report> tag.

Syntax

Following is the syntax for this tag:

<report DTDVersion=1.0"
     [name="report_name"]
     [title="report_title"]
     [author="author_name"]
>
   content_of_report
</report>

Example

This example shows an XML customization document designed to be applied to an .RDF file named cond.rdf. This example does not touch the data model. It only changes the formatting of some of the fields in the layout.

<report name="cond" DTDVersion="1.0">
<!-- This report assumes that the file
     named header_example.html is located
     in d:\ORANT\TOOLS\DOC60\US\RBBR60.
     If it it not located there, the report
     will not run properly.
-->
 <layout>
   <section name="main">
     <field name="f_trade_date" 
            source="trade_date" 
            formatMask="MM/DD/RR"/>
     <field name="F_Mincurrent_pricePersymbol" 
            source="Mincurrent_pricePersymbol" 
            lineColor="black" 
      fillColor="r100g50b50"/>
     <field name="F_Maxcurrent_pricePersymbol"
            source="Maxcurrent_pricePersymbol"
            lineColor="black" 
      fillColor="r100g50b50"/>
   </section>
 </layout>
 <customize>
   <object name="videosales" type="REP_REPORT">
   <properties>
    <property name="beforeReportType">File</property>
    <property name="beforeReportValue">
         d:\xml_reps\header_example.html
    </property>
    <property name="afterReportType">Text</property>
    <property name="afterReportValue">
     <![CDATA[
      <center>
      <font face="Arial,Helvetica"><font size=-1><font color="#000000">
        Send questions to <a href="mailto:your_email_id">YourNameHere</a>.
        <br>&nbsp;
      </font>
      </center>
      </body>
      </html>
     ]]>
    </property>
   </properties>
  </object>
 </customize>
</report>

Attributes

The following table describes the attributes of the <report> tag:

Table 7-12 <report> Tag Attributes

Attribute	Required or Optional	Description
name	Optional	Records the name of the report. If the name is not specified, then the default is UNTITLED. If you plan to apply the report definition to an `.RDF` file, then this name should be the same as the file name without the `.RDF` extension.
dtdVer	Required	Records the version of the Oracle Reports DTD used to generate this XML report definition. Since the DTD can change between versions, any new reports definition must include information about which version was used. This permits backward compatibility in future releases.
title	Optional	Places the specified title at the beginning of the report. When applying the definition title at an `.RDF` file, this title overrides the existing report title.
author	Optional	Records the name of the author.

7.5.27 <section>

Description

The <section> tag delimits the beginning and ending of a section in the layout of the report definition. The <section> tag must be nested within the <layout> tag. A report might have up to three sections in its layout.

For each section, you might also define a layout style using the following tags:

Syntax

Following is the syntax for this tag:

<section
  name= "header | main | trailer"
  width="section_width"
  height="section_height"
> 
   section_contents 
</section>

Attributes

The following table describes the attributes of the <section> tag:

Table 7-13 <section> Tag Attributes

Attribute	Required or Optional	Description
name	Required	Is the section's name: header, main, or trailer.
width	Optional	Is the width of one physical page (including the margin) in the unit of measurement of the report (for example, 8.5 inches).
height	Optional	Is the height of one physical page (including the margin) in the unit of measurement of the report (for example, 11 inches).

Example

The following is an example of a <section> definition:

<layout>
   <section name="header"> 
     <field name="F_ssn1" 
            source="ssn" 
            formatTrigger="F_ssn1FormatTrigger"/>
   </section>
   <section name="main">
     <field name="F_ssn" 
            source="ssn" 
            formatTrigger="F_ssnFormatTrigger"/>     
   </section>
 </layout>

7.5.28 <select>

Description

The <select> tag delimits the beginning and ending of a SELECT statement within the data model. <select> must be nested within the <dataSource> tag.

Syntax

Following is the syntax for this tag:

<select>
   content_of_SELECT
</select>

Examples

The following example shows the data source segment of an XML report definition:

<data>
 <dataSource name="q_category">
  <select>
    SELECT          ic.category,
                       SUM (h.sales),
                       AVG (h.high_365),
                       AVG (h.low_365),
                       AVG (h.div),
                       AVG (h.p_e)
    FROM stock_history h, indcat ic
    WHERE h.symbol=ic.symbol
    GROUP BY ic.category
   </select>
  </dataSource>
 </data>

A user parameter is automatically generated for you if you include it as a bind reference in a SELECT statement. For example:

<select>
  select * from dept where deptno > :p_dept;
</select>

This SELECT statement would cause a user parameter named p_dept to be automatically generated. Therefore, you would not need to manually create it in the report definition.

The following example shows a segment of an XML report definition that uses the <![CDATA[]]> tag to protect a SQL statement that contains a greater than sign:

<select>
  <![CDATA[
   SELECT ALL VIDEO_CATEGORY_BY_QTR.QUARTER, 
          VIDEO_CATEGORY_BY_QTR.TOTAL_PROFIT
   FROM SCOTT.VIDEO_CATEGORY_BY_QTR
   WHERE (VIDEO_CATEGORY_BY_QTR.SALES_REGION='West'
         AND VIDEO_CATEGORY_BY_QTR.TOTAL_PROFIT>2000)    
  ]]>
</select>

7.5.29 <summary>

Description

The <summary> tag defines a summary column in the data model of the report definition. Summary columns are used to perform some mathematical function on the data values of another column. If you want to perform a function that is not one of the standard summary functions, then you can use the <formula> tag to create a formula column that uses PL/SQL to perform more complex calculations.

Refer to Section 7.5.10, "<formula>" for more information.

Syntax

Following is the syntax for this tag:

<summary
  source="src_col_name"
function="sum|average|minimum|maximum|count|first|last|pctTotal|stddeviation
          |variance"
  compute="group+names"
  reset="group_name"
  productOrder="group_name"
  nullval="value_if_null"
/>

Attributes

The following table describes the attributes of the <summary> tag:

Table 7-14 <summary> Tag Attributes

Attribute	Required or Optional	Description
source	Required	Is the name of the column whose values are summarized.
function	Optional	Is the mathematical operation to be applied to produce the summary values: average calculates the average of the column's values within the reset group. count counts the number of records within the reset group. first prints the column's first value fetched for the reset group. last prints the column's last value fetched for the reset group. maximum calculates the column's highest value within the reset group. minimum calculates the column's lowest value within the reset group. pctTotal calculates the column's percent of the total within the reset group. stddeviation calculates the column's positive square root of the variance for the reset group. sum calculates the total of the column's values within the reset group. variance sums the squares of each column value's distance from the mean value of the reset group and divides the total by the number of values minus 1.
compute	Optional	Is the group over which a % of Total summary column is computed. Compute is used only for columns with a function of % of Total. This value determines the total of which each source column value is a percentage. When you calculate a percentage, you divide a value by a total (for example, SMITH's salary/total department salaries). Compute defines the total for a percentage calculation. For matrix reports, Compute At can be multiple groups. You can also set this attribute to page or report if you want to compute percentages over the total values on each page or over the entire report.
reset	Optional	Is the group at which the summary column value resets to zero (if Function is Count), null (if Function is not Count), or nullval (if the summary has one). Reset determines if the summary is a running summary or a periodic (for example, group-level) summary. You can also set this attribute to page or report if you want to compute percentages over the total values on each page or over the entire report.
productOrder	Optional	Is the order in which groups are evaluated in the cross product for a summary. ProductOrder also defines the frequency of a summary, formula, or placeholder in a cross product group. That is, the summary, formula, or placeholder has one value for each combination of values of the groups in its productOrder. The productOrder attribute is used only for columns owned by cross-product groups. Because a cross product relates multiple groups, the groups in the cross product could be evaluated in any one of many different orders. Therefore, when creating a summary for a cross product, you must use productOrder to specify which group should be evaluated first, which second, and so on. You must also use productOrder to specify the frequency of a summary, formula, or placeholder within the cross product.
nullval	Optional	Is a value to be substituted for any null values of the column. For example, if you enter X in this field, then an X is displayed for null values fetched for the column. If left blank, then no substitution is done for null values.

Default Values

Typically, you should not need to specify anything for the optional attributes of the <summary> tag because their values are defaulted at runtime. The only time you should need to specify the optional values is when you want to override their defaults. The following tables describe the defaulting for each of the optional attributes for each layout style.

Table 7-15 Default Values for Summaries in Break Groups

Optional Attribute	Default Value
function	sum
compute	The parent group of the summary column's group
reset	The parent group of the summary column's group

Table 7-16 Default Values for Summaries in a Matrix Report

Optional Attribute	Default Value
function	sum
compute	The cross product group
productOrder	The group containing the summary (for dimension summaries) A list of groups that define the matrix row (for cell summaries)
reset	The highest frequency group of the productOrder

Example

The following is an example of some summaries for a data model that contains two queries. The first three summaries are for a tabular layout and the last six are for a matrix break report. Because only the name, source column, and function are specified, the defaulting algorithm will place the columns in the appropriate groups based on where we place their associated fields in the layout.

<data>
  <dataSource name="Q_1">
  <select>
   SELECT ALL VIDEO_CATEGORY_BY_QTR.QUARTER,
          VIDEO_CATEGORY_BY_QTR.SALES_REGION,
          VIDEO_CATEGORY_BY_QTR.STATE, VIDEO_CATEGORY_BY_QTR.CITY, 
          VIDEO_CATEGORY_BY_QTR.PRODUCT_CATEGORY, 
          VIDEO_CATEGORY_BY_QTR.TOTAL_SALES, 
          VIDEO_CATEGORY_BY_QTR.TOTAL_COST,
          VIDEO_CATEGORY_BY_QTR.TOTAL_PROFIT
   FROM SCOTT.VIDEO_CATEGORY_BY_QTR
   WHERE VIDEO_CATEGORY_BY_QTR.SALES_REGION='West'
  </select>
 </dataSource>
 <dataSource name="Q_2">
  <select>
   SELECT ALL VIDEO_CATEGORY_BY_QTR.QUARTER, VIDEO_CATEGORY_BY_QTR.CITY, 
          VIDEO_CATEGORY_BY_QTR.PRODUCT_CATEGORY, 
          VIDEO_CATEGORY_BY_QTR.TOTAL_PROFIT,
          VIDEO_CATEGORY_BY_QTR.TOTAL_SALES,
          VIDEO_CATEGORY_BY_QTR.TOTAL_COST
   FROM SCOTT.VIDEO_CATEGORY_BY_QTR
   WHERE VIDEO_CATEGORY_BY_QTR.SALES_REGION='West'
  </select> 
 </dataSource>
 <summary name="SumTOTAL_SALESPerCITY1" source="total_sales1"/> 
 <summary name="SumTOTAL_COSTPerCITY1" source="total_cost1"/> 
 <summary name="SumTOTAL_PROFITPerCITY1" source="total_profit1"/> 
 <summary name="SumTOTAL_SALESPerQUARTER" source="total_sales"/> 
 <summary name="SumTOTAL_COSTPerQUARTER" source="total_cost"/> 
 <summary name="SumTOTAL_PROFITPerQUARTER" source="total_profit"/> 
 <summary name="SumTOTAL_SALESPerCITY" source="total_sales"/> 
 <summary name="SumTOTAL_COSTPerCITY" source="total_cost"/> 
 <summary name="SumTOTAL_PROFITPerCITY" source="total_profit"/> 
 <formula name="Profit_Margin" source="FormulaProfitMargin"
datatype="number"
          width="9"/>
</data>

7.5.30 <tabular>

Description

The <tabular> tag delimits a tabular style within a section of the report's layout. If you use the <tabular> tag, then you must also nest <field> tags to list the fields you want to include in the tabular layout.

Refer to Section 7.5.8, "<field>" for more information.

Syntax

Following is the syntax for this tag:

<tabular> 
   <field>
    </field> 
   [...]
</tabular>

Example

The following example shows a segment of an XML report definition that defines a section with a tabular layout inside of it:

<section name="header"> "
<tabular name="M_summary" template="corp2.tdf">
  <labelAttribute font="Arial" 
         fontSize="10"
         fontStyle="bold"
         textColor="white"/>
  <field name="F_ports" 
         source="ports" 
         label="Port IDs" 
         font="Arial" 
         fontSize="10"/>
  <field name="F_locations" 
         source="locations" 
         label="Port Names" 
         font="Arial" 
         fontSize="10"/>
</tabular>
</section>

¹ Creating the definition programmatically would allow you to build up a report definition on the fly based on user input.
² You can also use XML report definitions with the Oracle Reports Runtime and Oracle Reports Builder.
³ It should be noted that this XML report definition would have a null effect if applied to another report because it contains nothing. It can be parsed because it has the needed tags, but it is only useful to look at this definition to see the required tags.
⁴ DTD files are what give XML tags their meanings. Oracle Reports Services includes a DTD file that defines the XML tags that can be used in a report definition. For more information about the supported XML tags, refer to Section 7.5, "XML Tag Reference".
⁵ It is possible to save the combined .RDF file and XML report definition as a new .RDF file. This technique is discussed later in this chapter.

7 Customizing Reports at Runtime

7.1 Overview

7.1.1 Creating and Using XML Report Definitions

7.2 Creating an XML Report Definition

7.2.1 Required Tags

7.2.2 Partial Report Definitions

Table 7-1 XML Report Definitions for Building Reports

7.2.2.1 Formatting Modifications Example

Tips on this Example

7.2.2.2 Formatting Exception Example

Tips on this Example

7.2.2.3 Program Unit and Hyperlink Example

Tips on this Example

7.2.2.4 Data Model and Formatting Modifications Example

Tips on this Example

7.2.3 Full Report Definitions

Tips on this Example

7.3 Running XML Report Definitions

7.3.1 Applying an XML Report Definition at Runtime

7.3.1.1 Applying One XML Report Definition

7.3.1.2 Applying Multiple XML Report Definitions

7.3.1.3 Applying an XML Report Definition in PL/SQL

7.3.1.3.1 Applying an XML Definition Stored in a File

7.3.1.3.2 Applying an XML Definition Stored in Memory

Tips on this Example

7.3.2 Running an XML Report Definition by Itself

7.3.3 Performing Batch Modifications

7.4 Debugging XML Report Definitions

7.4.1 XML Parser Error Messages

7.4.2 Tracing Options

7.4.3 RWBLD60

7.4.4 TEXT_IO

7.5 XML Tag Reference

7.5.1

Description

Syntax

Example

7.5.2 <![CDATA[ ]]>

Description

Syntax

Examples

7.5.3 <condition>

Description

Syntax

Attributes

Table 7-2 <condition> Tag Attributes

Usage Note

Example

7.5.4 <customize>

Description

Syntax

Examples

7.5.5 <data>

Description

Syntax

Example

7.5.6 <dataSource>

Description

Syntax

Examples

7.5.7 <exception>

Description

Syntax

Attributes

Table 7-3 <exception> Tag Attributes

Usage Notes

Example

7.5.8 <field>

Description

Syntax

Attributes

Table 7-4 <field> Tag Attributes

Examples

7.5.9 <formLike>

Description

Syntax

Example

7.5.10 <formula>

Description

Syntax

7
Customizing Reports at Runtime