21.4 Using XML Files at Runtime

Once you have created your Oracle Reports XML customization file, you can use it in the following ways:

You can apply XML report definitions to RDF or other XML files at runtime by specifying the CUSTOMIZE command line keyword or the SRW.APPLY_DEFINITION built-in procedure. Refer to Section 21.4.1, "Applying an XML Report Definition at Runtime" for more information.

Note:
Oracle Reports does not support XML customizations of REP files.
You can run an XML report definition by itself (without another report) by specifying the REPORT (or MODULE) command line keyword. Refer to Section 21.4.2, "Running an XML Report Definition by Itself" for more information.
You can use rwconverter to make batch modifications using the CUSTOMIZE command line keyword. Refer to Section 21.4.3, "Performing Batch Modifications" for more information.

The following sections describe each of the cases in more detail and provide examples.

21.4.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 keyword or the SRW.APPLY_DEFINITION built-in procedure. CUSTOMIZE can be used with rwclient, rwrun, rwbuilder, rwconverter, and URL report requests.

Note:

Refer to Section 21.4.3, "Performing Batch Modifications" for more information about using CUSTOMIZE with rwconverter.

21.4.1.1 Applying One XML Report Definition

The following command line sends a job request to Oracle Reports Services and applies an XML report definition, emp.xml, to an RDF file, emp.rdf. In this example, the CUSTOMIZE keyword refers to a file located in a Windows directory path. For UNIX, specify the path according to UNIX standards (that is, myreports/emp.xml).

rwclient REPORT=emp.rdf CUSTOMIZE=\myreports\emp.xml
  USERID=username/password@my_db DESTYPE=file DESNAME=emp.pdf
  DESFORMAT=PDF SERVER=server_name

When you use rwrun, the Reports Runtime command, the equivalent command line would be:

rwrun USERID=username/password@my_db REPORT=emp.rdf
   CUSTOMIZE=\myreports\emp.xml DESTYPE=file DESNAME=emp.pdf
   DESFORMAT=PDF

21.4.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 keyword. 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:

rwclient REPORT=emp.rdf 
  CUSTOMIZE="(d:\corp\myreports\emp0.xml,d:\corp\myreports\emp1.xml)"
  USERID=username/password@my_db DESTYPE=file DESNAME=emp.pdf
  DESFORMAT=PDF SERVER=server_name

Note:

In this example, the CUSTOMIZE value demonstrates a directory path to files stored on a Windows platform. For UNIX, use that platform's standard for specifying directory paths (that is, forward slashes instead of backward).

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

rwrun REPORT=emp.rdf 
  CUSTOMIZE="(D:\CORP\MYREPOORTS\EMP0.XML,D:\CORP\MYREPORTS\EMP1.XML)"
  USERID=username/password@my_db DESTYPE=file DESNAME=emp.pdf
  DESFORMAT=PDF

21.4.1.3 Applying an XML Report Definition in PL/SQL

To apply an XML report definition to an RDF file in PL/SQL, use the SRW.APPLY_DEFINITION and SRW.ADD_DEFINITION built-in procedures in the Before Parameter Form or After Parameter Form trigger. The following sections provide examples of these built-in procedures.

Note:

For a description of the SRW built-in package, including the SRW.APPLY_DEFINITION and SRW.ADD_DEFINITION built-in procedures, and more information about report triggers, see the Oracle Reports online Help.

21.4.1.3.1 Applying an XML Definition Stored in a File

To apply XML that is stored in the file system to a report, use the SRW.APPLY_DEFINITION built-in procedure in the Before Parameter Form or After Parameter Form triggers of the report.

On Windows:

SRW.APPLY_DEFINITION ('%ORACLE_HOME%\TOOLS\DOC\US\RBBR\COND.XML');

On UNIX:

SRW.APPLY_DEFINITION ('$ORACLE_HOME/TOOLS/DOC/US/RBBR/COND.XML');

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

21.4.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 the SRW.APPLY_DEFINITION built-in procedure.

The following example illustrates how to build up and apply several definitions in memory based upon parameter values entered by the user. The PL/SQL in this example is used in the After Parameter Form trigger of a report called videosales_custom.rdf.

The videosales_custom.rdf file contains PL/SQL in its After Parameter Form 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.

The following tips are useful when looking at this example:

Each time you use the SRW.APPLY_DEFINITION built-in procedure, 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 (4000 bytes), 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="9.0.2.0.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="9.0.2.0.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="9.0.2.0.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="9.0.2.0.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;

21.4.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 (or MODULE) option. The following command line sends a job request to Oracle Reports Services to run a report, emp.xml, by itself:

rwclient USERID=username/password@my_db
  REPORT=c:\corp\myreports\emp.xml
  DESTYPE=file desname=emp.pdf DESFORMAT=pdf
  SERVER=server_name

When you use rwrun, the Reports Runtime command, the equivalent command line would be:

rwrun USERID=username/password@my_db
  REPORT=c:\corp\myreports\emp.xml
  DESTYPE=file DESNAME=emp.pdf DESFORMAT=PDF

When you run an XML report definition in this way, you must specify an XML file extension. You could also apply an XML customization file to this report using the CUSTOMIZE command line keyword.

21.4.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 keyword with rwconverter to perform modifications in batch. Batch modifications are particularly useful when you must 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 Reports Builder, you can run rwconverter once and make the same change to a large number of reports at once.

Note:

The rwconverter.bat file uses the start keyword to start the rwconverter process. If the start keyword is specified, then the process starts in asynchronous mode. The spawned rwconverter continues execution until completion. For using batch conversion of a large number of rdfs, all the processes start simultaneously. Therefore, it is recommended that you modify the rwconverter.bat file manually to remove the start keyword for running rwconverter in batch mode.

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

rwconverter username/password@my_db
  STYPE=rdffile SOURCE="(inven1.rdf, inven2.rdf, manu.rdf)" 
  DTYPE=rdffile DEST="(inven1_new.rdf, inven2_new.rdf, manu_new.rdf)" 
  CUSTOMIZE="(d:\apps\trans\translate.xml,d:\apps\custom\customize.xml)"
  BATCH=yes

Note: