Using XML Files at Runtime

Once you have created your 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 theCUSTOMIZEcommand line argument or theSRW.APPLY_

DEFINITIONbuilt-in. Refer to"Applying an XML Report Definition at Runtime"for more information.

You can run an XML report definition by itself (without another report) by specifying theREPORT(orMODULE) command line argument. Refer to"Running an XML Report Definition by Itself"for more information.

You can useRWCONVERTERto make batch modifications using theCUSTOMIZE command line argument. Refer to"Performing Batch Modifications"for more information.

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

10.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 theCUSTOMIZEcommand line argument or theSRW.APPLY_DEFINITIONbuilt-in.

CUSTOMIZEcan be used withRWCLIENT,RWRUN,RWBUILDER,RWCONVERTER, and URL report requests.

10.4.1.1 Applying One XML Report Definition

The following command line sends a job request to Oracle9iAS Reports Services and applies an XML report definition,EMP.XML, to an RDF file,EMP.RDF. In this example, theCUSTOMIZEcommand refers to a file located in a Windows directory path. For UNIX, specify the path according to UNIX standards (i.e.,

myreports/emp.xml).

RWCLIENT REPORT=emp.rdf CUSTOMIZE=\myreports\emp.xml

USERID=<username>/<password>@<my_db> DESTYPE=file DESNAME=emp.pdf Note: Refer to"Performing Batch Modifications"for more information about usingCUSTOMIZEwithRWCONVERTER.

DESFORMAT=PDF SERVER=<server_name>

When you useRWRUN, the Oracle9iAS Reports Services 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

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.

10.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 theCUSTOMIZEcommand line argument. The following command line sends a job request to Oracle9iAS Reports Services that applies two XML report definitions,EMP0.XMLandEMP1.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>

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

RWRUN REPORT=emp.rdf

Note: Unless you care to change the default, it isn't necessary to include a trace in the command line if you have specified a default trace option in the Reports Server configuration file.

Note: In this example, theCUSTOMIZEcommand entry demonstrates a directory path to files stored on a Windows platform. For UNIX, use that platform's standard for specifying directory paths (i.e., forward slashes instead of backward).

CUSTOMIZE="(D:\CORP\MYREPOORTS\EMP0.XML,D:\CORP\MYREPORTS\EMP1.XML)"

USERID=<username>/<password>@<my_db> DESTYPE=file DESNAME=emp.pdf DESFORMAT=PDF

10.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 theSRW.APPLY_

DEFINITIONandSRW.ADD_DEFINITIONbuilt-ins in the BeforeForm or AfterForm trigger. The following sections provide examples of these built-ins.

10.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 theSRW.APPLY_DEFINITIONbuilt-in in the BeforeForm or AfterForm 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.

10.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_DEFINITIONbefore applying it usingSRW.APPLY_DEFINITION.

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 AfterParameterForm trigger of a report calledvideosales_

custom.rdf.

Thevideosales_custom.rdffile 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.

The following tips are useful when looking at this example:

Each time you useSRW.APPLY_DEFINITION, the document buffer is flushed and you must begin building a new XML report definition withSRW.ADD_

DEFINITION.

Notice the use of the parametershilite_profits,hilite_costs,hilite_

sales, andmoney_formatto determine what to include in the XML report definition. Thehilite_profits,hilite_costs, andhilite_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">');

ELSIF :MONEY_FORMAT='$NNNN' THEN SRW.ADD_DEFINITION('<layout>');

SRW.ADD_DEFINITION('<section name="main">');

formatMask="LNNNNNNNNNNN0"/>');

IF :HILITE_COSTS <> 'None' THEN SRW.ADD_DEFINITION('<layout>');

SRW.ADD_DEFINITION('<section name="main">');

IF :HILITE_SALES <> 'None' THEN SRW.ADD_DEFINITION('<layout>');

SRW.ADD_DEFINITION('<section name="main">');

IF :HILITE_PROFITS <> 'None' THEN SRW.ADD_DEFINITION('<layout>');