Skip Headers

Oracle® Application Server Reports Services Publishing Reports to the Web 10g (9.0.4) Part Number B13673-01 |
| Home | Contents | Index

# 15 Creating Advanced Distributions

When you wish to define an advanced distribution for your report, you can design the distribution by developing a distribution XML file. This file can specify which section or sections of a report should go to what destination via what format of output. In one distribution XML file, you can specify many different destinations, including custom (pluggable) destinations you design.

This chapter provides information on creating a distribution XML file and some example use cases. It includes the following main sections:

- Distribution Overview

- Introduction to Distribution XML Files

- Elements of a Distribution XML File

- Distribution XML File Examples

- Defining Custom/Pluggable Destinations

- Limitations with using distribution

## 15.1 Distribution Overview

Although distribution XML files are not required for specifying the distribution of report output, they are useful for complex distributions. For example, there may be times when you want to publish the output of one report in a variety of ways. You might want to send an executive summary of a report to senior management while mailing detailed breakdowns to individual managers. In this case, you might produce a single report with two report sections: a portrait-sized summary section and a landscape-sized detail section. You would associate the detail section with a data model group that lists the managers, then alter the destination on each instance of the group to send each department's output to its related manager.

The distribution XML file tames distribution complexity by enabling you to define multiple outputs for a given report in one XML file, then call that file from a command line or URL.

## 15.2 Introduction to Distribution XML Files

This section outlines the various XML files related to distribution.

### 15.2.1 The distribution.dtd File

When you create a distribution XML file, you follow the syntax defined in the `distribution.dtd` file located in the following directory (Windows and UNIX use the same path):

    ORACLE_HOME\reports\dtd

As you look through the following sections, it may be useful to you to print the distribution.dtd file and refer to it as various elements and attributes are described.

Note: information provided in distribution XML file is case sensitive. The user must preserve case of various elements and attributes as specified in the `distribution.dtd` file.

The `distribution.dtd` file lists all elements that are valid within a distribution XML file. Each of these elements have attributes. Attributes that come with default values need not be specified, unless you wish to override the default.

You can create a dynamic distribution by introducing variable values into many different attributes. Variable values reference columns that are present in the report that is using the distribution XML file.

### 15.2.2 Using Variables Within Attributes

You can use variables within attributes by entering `&amp;column_name` or `&amp;&lt;column_name&gt;` in the place of a static value.

Usage Note

The ampersand (&) and less-than symbol (<) have specific meanings in XML, but they are also required symbols for certain Oracle Reports Developer command line options (for example, lexical parameters require the ampersand symbol). To avoid conflict with the XML meanings of these symbols when you set up variables, specify the encoded version of the ampersand (&amp;) and less-than and greater-than symbols (&lt; and &gt;). For example,Here is what the variable looks like improperly coded in an XML file:

    <mail id="a1" to="&<manager>@mycompany.com" …

Here is what the variable looks like properly coded in an XML file:

    <mail id="a1" to="&amp;&lt;manager&gt;@mycompany.com" …>

There is no special requirement for the greater-than symbol (>) used with variables, but for consistency, we recommend that you use the encoded version (&gt;).

The variable syntax you use depends on whether the value is expressed by itself or in combination with other values or strings. For example, a value for a "to" attribute in a mail element might be expressed as either:

    <mail id="a2" to="&amp;email" …>

OR

    <mail id="a3" to="&amp;&lt;first_name&gt;.&amp;&lt;last_name&gt;@myco.com …>

In the first example (id="a2"), the variable's referenced column (`email`) contains a full e-mail address and does not require additional information. The second example (id="a3") uses a combination of variable values (`first_name` and `last_name`) and static text to construct an e-mail address (static text is the period after first_name and @myco.com). In both cases, you will get dynamic e-mail addressing. The example you use will depend on whether the variable contains all the information you need or requires additional information in order to be complete.

For even more complex layouts, you can also reference report columns you created with PL/SQL formulas. For example, in your report you may define the PL/SQL column:

    PL/SQL formula CF_MAILID: return(:first_name||'.'||:last_name)

You'd reference this column in the distribution XML file as:

    to="&amp;&lt;CF_MAILID&gt;@mycompany.com"

## 15.3 Elements of a Distribution XML File

The elements of a distribution XML file include:

- destinations

- foreach

- mail

- body

- include

- file

- printer

- destype

- attach

- property

Most of these elements have attributes that define the behavior of the element. The following sections describe the distribution XML file elements and their associated attributes. Distribution XML File Examples provides use cases that demonstrate the distribution XML file elements and attributes in action.

### 15.3.1 destinations

Example

    <destinations>

    [One or more distribution specifications]

    </destinations>

Required/Optional

Required. You must have no more or less than one `destinations` element in your distribution XML file.

Description

The `destinations` element opens and closes the content area of the distribution XML file. In terms of the distribution XML file's tagging hierarchy, all the other elements are subordinate to the `destinations` element.

The `destinations` element has the following sub-elements:

- foreach

- mail

- file

- printer

- destype

Each of these is discussed in the following subsections.

### 15.3.2 foreach

Example

    <foreach>

    <mail id="a1" to="my_addressee@mycompany.com" subject="Fourth Quarter Results">

    <attach format="pdf" name="dept_&amp;department_ID&gt;.pdf" srcType="report" instance="this">

    <include src="mainSection"/>

    </attach>

    </mail>

    </foreach>

    OR

    <mail id="a4" to="recipient@mycompany.com" subject="Regional Results">

    <foreach>

    <attach format="pdf" name="report.pdf" srcType="report" instance="all">

    <include src="mainSection"/>

    </attach>

    </foreach>

    </mail>

Required/Optional

Optional. You can have as many `foreach` elements as you require.

Description

Use the `foreach` element to burst your distribution against a repeating group. You can use `foreach` only when the associated report definition file (either RDF, JSP, or XML) has its "Repeat On" property for the section that will be burst set to an appropriate group. The `foreach` element specifies that the distribution defined between its open and close parameters should be performed for each repeating group.

The Repeat On property can be set for a report section (Header, Main, and Trailer) to associate a data model break group to a section. By setting the Repeat On property for a section, you can generate multiple instances of a section, or a repeating section.

When you implement bursting and distribution in a report, you can generate section-level distribution by setting the Repeat On property for a section to a data model break group, which generates an instance of the section for each column record of that break group. Then, you can distribute each instance of the section as appropriate (for example, to individual managers in the MANAGER group).

If you set the Repeat On property for more than one of the Header, Main, and Trailer sections of a report, all Repeat On property values must be set to the same data model break group. If the Repeat On property for any one of the Header, Main, and Trailer sections is set to a different data model break group, Oracle Reports raises any of the following messages:

    REP-0069: Internal Error
    REP-57054: In-Process job terminated: Terminated with error
    REP-594: No report output generated.

The `foreach` element has the following sub-elements:

- mail

- file

- printer

- destype

- attach

Each of these is discussed in the following subsections.

You can also use the `foreach` element as a sub-element of the mail element, as depicted in the second example provided at the start of this section. (In this example, assuming that `mainSection` repeats on G_DEPARTMENT_ID, the example will produce a single attachment with all the instances of the report's mainSection in a single file.)

The `foreach` element works closely with the `instance` attribute of the attach and file elements. While `foreach` specifies that the distribution should be performed according to record groups, `instance` specifies whether the burst groups should be distributed in one file (`instance="all"`) or distributed as separate files: one file for each group instance (`instance="this"`).

When used with the `mail` element, `foreach` can mean different things according to its position relative to the `mail` element:

- When `foreach` precedes the `mail` element and `instance="this"`, each group instance is dispatched as a separate mail. For example:

      <foreach>

    <mail id="a1" to="managers@mycompany.com" subject="results">

    <attach name="department_&amp;&lt;department_id&gt;.pdf" instance="this">
    <include src="mainSection" />
    </attach>

    </mail>

    </foreach>

If the report is grouped according to department_id, and there are four departments, then there are four group instances. This means four e-mails per recipient, each e-mail with its own group instance attached: one e-mail has department 10's report attached; another e-mail has department 20's report attached; and so on. Each recipient receives all four e-mails.

- When `foreach` follows the mail element and `instance="this"`, each group instance is attached to one e-mail going to each recipient. For example:

      <mail id="a1" to="managers@mycompany.com" subject="results">

    <foreach>

    <attach name="department_&amp;&lt;department_id&gt;.pdf" instance="this">
    <include src="mainSection" />
    </attach>

    </foreach>

    </mail>

### 15.3.3 mail

Example

    <mail id="a1" to="jsmith@foo.com" subject="Results">

    <body srcType="text">

    Attached are quarterly results.

    </body>
    <attach srcType="report">

    <include src="headerSection"/>
    <include src="mainSection"/>

    </attach>

    </mail>

    OR

    <mail id="a4" to="recipient@mycompany.com" subject="Regional Results">

    <foreach>

    <attach format="pdf" name="report.pdf" srcType="report" instance="this">

    <include src="mainSection"/>

    </attach>

    </foreach>

    </mail>

Required/Optional

Optional. You can have as many `mail` elements as you require.

Description

Use the `mail` element to specify distributions via an outgoing SMTP-based mail server. Use it to specify the recipients, the subject, and the priority of the e-mail.

The `mail` element has three sub-elements:

- body

- attach

- foreach

Between an open and close `mail` element, there can be only one `body` sub-element and anywhere from zero to multiple `attach` and`foreach` sub-elements.

The`mail` element also has a set of related attributes. These are expressed within the `mail` tag. For example, the `id`, `to`, and `subject` attributes are expressed:

    <mail id="a1" to="jsmith@foo.com" subject="Recent Hires">

Table 15-1 lists and describes the attributes associated with the mail element.

Table 15-1 Attributes of the mail element

Attribute | Valid values | Description
--- | --- | ---
`id` | string | Required. A keyword, unique within a given distribution XML file, that identifies a particular mail element. This can be a combination of a text string and one or more numbers, for example `id="a1"`. The `id` value must always start with an alpha character.
`to` | string | Required. Variable values allowed. The recipient(s) of the e-mail. Contains the full, formal e-mail address, for example: `to="jsmith@foo.com"` Multiple recipients must be separated with commas. Can also contain variable values that reference columns used in the associated report. See Section 15.2.2 for more information.
`cc` | string | Optional. Variable values allowed. The recipient(s) to receive a copy of the e-mail.
`bcc` | string | Optional. Variable values allowed. The recipient(s) to receive a blind copy of the e-mail.
`from` | string | Optional. Variable values allowed. The sender of the e-mail.
`replyTo` | string | Optional. Variable values allowed. The e-mail account where replies should be sent.
`subject` | string | Default: Mail Sent from `&amp;Report` Optional. Variable values allowed. The subject of the e-mail. In the absence of a specified subject, the subject line will read: Mail Sent from [`Name of Report`]
`priority` | `highest|high|normal|low|lowest` | Default: `normal` The e-mail's delivery priority.
`returnReceipt` | `true|false` | Default: `false` Indication of whether the replyto individual or account should be notified when the e-mail is received.
`organization` | string | Optional. Variable values allowed. The name of the organization distributing the e-mail, for example: organization="Region 10 Sales" Or organization="&amp;department_name"

Note: For the mail element to work properly, the Reports Server must know which outgoing SMTP mail server to send mail to. You specify this information in the Reports Server configuration file (`server_name``.conf`). This file has a `pluginParam` element where you can enter the name of a mail server. For example:
    <pluginParam name=mailServer>smtp01.mycorp.com</pluginParam>
For more information, see Configuring OracleAS Reports Services.

### 15.3.4 body

Example
On Windows

    <mail id="a1" to="jsmith@foo.com" subject="Results">

    <body srcType="file">

    <include src="c:\mail\body.html"/>

    </body>

    </mail>

On UNIX

    <mail id="a1" to="jsmith@foo.com" subject="Results">

    <body srcType="file">

    <include src="/mail/body.html"/>

    </body>

    </mail>

Required/Optional

Optional. You can have a maximum of one body element associated with a given mail element.

Description

The `body` element acts as a sub-element to the `mail` element. It specifies the content (or `body`) of the e-mail. With `body`, you can type a text string between the open and close `body` tag or use an include sub-element to specify either an external file, a report, or a section of a report. For example:

    <mail id="a1" to="jsmith@foo.com" subject="Results">

    <body srcType="text">

    Attached are quarterly results.

    </body>
    …

Or

    <mail id="a1" to="jsmith@foo.com" subject="Results">

    <body srcType="file">

    <include src="d:/reports/admin/results.html"/>

    </body>
    …

Or

    <mail id="a1" to="&amp;&lt;first_name&gt;.&amp;&lt;last_name&gt;@myco.com" subject="Quarterly Results">

    <body srcType="report" format="html">

    <include src="headerSection"/>

    </body>
    …

`Body` has three attributes: `srcType`, `format`, and `instance`. They are described in Table 15-2.

Table 15-2 Attributes of the body sub-element of mail

Attribute | Valid values | Description
--- | --- | ---
`srcType` | `file|report|text` | Default: `report` The source for content of an e-mail. The content is displayed in the body of the e-mail. In the absence of a specified `srcType`, the default is used.
`format` | `html|htmlcss|ascii` | Default: `html` Required when `srcType` is `report` with a `format` other than `html`, the default; otherwise `format` is optional. The format of the content.
`instance` | `this|all` | Default: `all` Used when the foreach element is also present. With a grouped report that is burst into separate reports, `instance` specifies whether the groups will be broken into separate content according to each group instance (this) or all contained within the same content (all).

### 15.3.5 attach

Example

    <mail id="a1" to="jsmith@foo.com" subject="Results">

    <body srcType="text">

    Attached are quarterly results.

    </body>
    <foreach>

    <attach format="html" name="contacts.htm" srcType="report" instance="all">

    <include src="headerSection"/>
    <include src="mainSection"/>

    </attach>

    </foreach>

    </mail>

Required/Optional

Optional. You can have as many `attach` elements as you require with a `mail` element. Note that `attach` is also a sub-element of foreach, and `foreach` requires that at least one of its sub-elements be used (out of `mail,file,printer,destype,`and `attach`).

Description

`Attach` specifies attachments to the e-mail. Additionally, `attach` must have at least one include sub-element, and can have more than one if `srcType="report"`. `Attach` attributes are listed and described in Table 15-3.

Table 15-3 Attributes of the attach sub-element of mail

Attribute | Valid values | Description
--- | --- | ---
`format` | `pdf|html|htmlcss|rtf|` `ascii|xml|dflt` | Default: `pdf` Required when `srcType` is report and the report format is other than `pdf`, the default; otherwise `format` is optional. The format of the attached material, for example `format="htmlcss"`.
`name` | `string` | Optional. Variable values allowed. The filename of the attached material. Can also contain variable values that reference columns used in the associated report. See Section 15.2.2 for more information.
`srcType` | `file|report|text` | Default: `report` The source of the attachment, either a file, a report, or text.
`instance` | `this|all` | Default: `all` Used when the foreach element is also present. With a grouped report that is burst into separate reports, `instance` specifies whether the groups will be broken into separate content according to each group instance (this) or all contained within the same content (all).

Using these attributes in conjunction with the foreach element, you can design a destination that will repeat on a group instance and generate an e-mail for each group attachment. For example:

    <foreach>

    <mail id="a2" to="first.name@myco.com,second.name@myco.com, third.name@myco.com, fourth.name@myco.com" subject="Department Summaries">

    <body srcType="text">

    Attached is the breakdown of department summaries for the last quarter.

    </body>
    <attach format="htmlcss" name="deptsum.html" srcType="report" instance="this">

    <include src="report"/>

    </attach>

    </mail>

    </foreach>

By moving the location of the `foreach` element, you can generate one e-mail with multiple attachments: a separate one for each group instance.

    <mail id="a2" to="first.name@myco.com,second.name@myco.com, third.name@myco.com, fourth.name@myco.com" subject="Department Summaries">

    <body srcType="text">

    Attached is the breakdown of department summaries for the last quarter.

    </body>
    <foreach>

    <attach format="htmlcss" name="deptsum.html" srcType="report" instance="this">

    <include src="report"/>

    </attach>

    </foreach>

    </mail>

### 15.3.6 include

Example

    <mail id="a1" to="jsmith@foo.com" subject="Q4">

    <body srcType="text">

    Attached are quarterly results.

    </body>
    <attach srcType="report" format="pdf">

    <include src="report"/>

    </attach>

    </mail>

Or

    <mail id="a1" to="jsmith@foo.com" subject="Q4">

    <body srcType="text">

    Attached are quarterly results.

    </body>
    <attach srcType="report" format="htmlcss">

    <include src="headerSection"/>

    </attach>

    </mail>

Or

    <mail id="a1" to="jsmith@foo.com" subject="Q4">

    <body srcType="text">

    Attached are quarterly results.

    </body>
    <attach srcType="file">

    <include src="d:/management/reports/current/Q4.htm"/>

    </attach>

    </mail>

Required/Optional

Required when used with `body` and `attach` when `srcType` is `report` or `file`, but not when `srcType` is `text`. Also required for `file`, `printer`, and `destype`. In the instances where it is required, you must have one and can have more than one `includes`.

Description

The `include` element is available for use with the body, attach, file, printer, and destype elements. It specifies the file, report, or report section to be included in the body of an e-mail, as an attachment to an e-mail, in the content of a file, in the printer output, or in the content of a custom destination type.

If you want to specify more than one section, but not the entire report, enter an `include` for each required section. For example:

    <mail id="a1" to="jsmith@foo.com" subject="Results">

    <body srcType="text">

    Attached are quarterly results.

    </body>
    <attach srcType="report" format="htmlcss">

    <include src="headerSection"/>
    <include src="mainSection"/>

    </attach>

    </mail>

If the preceding `body` or `attach` element has `srcType` of `file`, the subsequent `include` can specify the file either with a directory path and filename or with just the filename, provided the file is located in a directory listed in the `REPORTS_PATH` environment variable. For example:

    <mail id="a1" to="jsmith@foo.com">

    <body srcType="file">

    <include src="q4sales.pdf"/>

    </body>

    </mail>

If you do specify a path, use the appropriate standard for your platform. For example:

On Windows:

    <include src="c:\management\reports\current\Q4.htm"/>

On UNIX:

    <include src="/management/reports/current/Q4.htm"/>

No other XML elements are placed between an `include` element’s open and close tags; however, `include` does have one attribute: `src`, described in Table 15-4.

Table 15-4 Attributes of the include sub-element when used with mail's body or attach

Attribute | Valid values | Description
--- | --- | ---
`src` | (path and) filename `report` `headerSection` `mainSection` `trailerSection` | Required. The source of material specified in the preceding `attach`, `body`, `file`, `printer`, or `destype` element. Because the distribution XML file is called when you run a specific report, there is no need to specify the report's name or location in the `src` attribute when `src="report"`. When the preceding `body` or `attach` element specifies a `file` `srcType`, provide the directory path and filename or just a filename, provided the file is located in a directory listed in the `REPORTS_PATH` environment variable. When the preceding `body` or `attach` element specifies a `report` `srcType`, specify the entire report (report) or provide the section(s) of the report to be included in the body or to be attached (e.g., `headerSection,mainSection,` and/or `trailerSection`).

### 15.3.7 file

Example
On Windows

    <file id="a7" name="c:\management\reports\report.pdf" format="pdf">

    <include src="report"/>

    </file>

On UNIX

    <file id="a7" name="/management/reports/report.pdf" format="pdf">

    <include src="report"/>

    </file>

Or

    <foreach>

    <file id="a7" name="section&amp;&lt;department_id&gt;.pdf" format="pdf" instance="this">

    <include src="mainSection"/>

    </file>

    </foreach>

Required/Optional

Optional. You can have as many `file` elements as you require.

Description

Use the `file` element to specify distributions to a file. `File` elements have one sub-element: include. There must be at least one `include` sub-element and there may be more between an open and close `file` element.

When used with the foreach element and the `instance="this"` attribute, the `file` element can distribute each group instance of a grouped report to separate files. For example, if you group a report on department_id, and there are four departments, you can use the `foreach`/`file`/`instance="this"` combination to generate four files, each with a separate department's report. In this case, the `file` entry in the distribution XML file might look like this:

    <foreach>

    <file id="a3" name="dept_&amp;&lt;department_id&gt;.pdf" format="pdf" instance="this">

    <include="report"/>

    </file>

    </foreach>

In this example, all report sections (header, main, and trailer) must repeat on the same group instance (e.g., department_id).

`File` elements also have a set of related attributes. These are expressed within the file tag. For example, the "id" and "name" `file` attributes are expressed:

Windows:

    <file id="a7" name="d:\reports\2001\q4sales.pdf">

UNIX:

    <file id="a7" name="/reports/2001/q4sales.pdf">

Table 15-5 lists and describes the attributes associated with a `file` element.

Table 15-5 Attributes of the file element

Attribute | Valid values | Description
--- | --- | ---
`id` | string | Required. A keyword, unique within a given distribution XML file, that identifies a particular file element. This can be a combination of a text string and one or more numbers, for example `id="a1"`. The `id` value must always start with an alpha character.
`name` | string | Required. Variable values allowed. The location and filename of the destination file. Enter a directory path. Include the filename. For example: Windows: `name="d:\reports\file.pdf"` UNIX: `name="reports/file.pdf` Can also contain variable values that reference columns used in the associated report. See Section 15.2.2 for more information.
`format` | `pdf|html|htmlcss|rtf|ascii|xml|bitmap` | Default: `pdf` The destination file format, for example: format="htmlcss"
`instance` | `this|all` | Default: `all` Used when the foreach element is also present. With a grouped report that is burst into separate reports, `instance` specifies whether the groups will be broken into separate files according to each group instance (this) or all contained within the same file (all).

### 15.3.8 printer

Example
On Windows

    <printer id="a1" name="\\server_name\printer_name" copies="5">

    <include src="report"/>

    </printer>

On UNIX

    <printer id="a1" name="alias_to_registered_printer" copies="5" instance="all">

    <include src="report"/>

    </printer>

Required/Optional

Optional. You can have as many `printer` elements as you require.

Description

Use the `printer` element to specify distributions to a printer. `Printer` elements have one sub-element: include. There must be at least one `include` sub-element and there may be more between an open and close `printer` element.

When used with the foreach element and the `instance="this"` attribute, the `printer` element can distribute each group instance of a grouped report to a separate print job. For example, if you group a report on department_id, and there are four departments, you can use the `foreach`/`printer`/`instance="this"` combination to generate four printed reports, each containing a separate department's report. In this case, the `printer` entry in the distribution XML file might look like this:

    <foreach>

    <printer id="a7" name="\\server_name\printer_name" instance="this">

    <include="report"/>

    </printer>

    </foreach>

In this example, all report sections (header, main, and trailer) must repeat on the same group instance (e.g., department_id).

Table 15-6 lists and describes the attributes associated with a `printer` element.

Table 15-6 Attributes of the printer element

Attribute | Valid values | Description
--- | --- | ---
`id` | string | Required. A keyword, unique within a given distribution XML file, that identifies a particular file element. This can be a combination of a text string and one or more numbers, for example `id="a1"`. The `id` value must always start with an alpha character.
`name` | string | Required. Variable values allowed. The destination printer. How you enter this information differs between Windows and UNIX. For Windows, specify the printer server name and the printer name. For example: name="\\server_name\printer_name" For UNIX, specify the alias assigned to a registered printer. For example: name="sales_printer" Can also contain variable values that reference columns used in the associated report. See Section 15.2.2 for more information.
`copies` | string | Default: `1` Number of copies of each report or each report group instance to print.
`instance` | `this|all` | Default: `all` Used when the foreach element is also present. With a grouped report that is burst into separate reports, `instance` specifies whether the groups will be broken into separate printed reports according to each group instance (`this`) or all contained within the same printed report (`all`).

### 15.3.9 destype

Example

    <destype id="acustom1" name="fax">

    <include src="headerSection"/>
    <property name="number" value="914925551212"/>

    </destype>

Required/Optional

Optional. You can have as many `destype` elements as you require.

Description

Use the `destype` element to specify distribution to a custom destination, such as to a fax machine or an FTP site. You also use `destype` to specify distribution to a portal created with OracleAS Portal. The `destype` element allows for the use of two sub-elements: property include and . At least one include is required.

The inclusion of a custom destination type requires that you have a defined distribution handler in place to usher report content to the custom output destination.

Note: Build a custom destination type via the OracleAS Reports Services Destinations API. Look for upcoming information about Reports APIs on the Oracle Technology Network, (`http://otn.oracle.com`).

When used with the foreach element and the `instance="this"` attribute, the `destype` element can distribute each group instance of a grouped report to a separate `destype` instance (e.g., a separate fax). For example, if you group a report on department_id, and there are four departments, you can use the `foreach`/`printer`/`instance="this"` combination to generate four `destype` instances, each containing a separate department's report. In this case, the `destype` entry in the distribution XML file might look like this:

    <foreach>

    <destype id="a9" name="fax" instance="this">

    <include="report"/>
    <property name="number" value="&amp;&lt;fax_number&gt;"/>

    </destype>

    </foreach>

In this example, all report sections (header, main, and trailer) must repeat on the same group instance (e.g., department_id).

Custom destination types also have a set of related attributes. These are expressed within the `destype` tag. For example, the "id", "name", and "instance" `destype` attributes are expressed:

    <foreach>

    <destype id="a1" name="name_of_destination_type" instance="all">

    </foreach>

Table 15-7 lists and describes the attributes associated with a `destype` element.

Table 15-7 Attributes of the destype element

Attribute | Valid values | Description
--- | --- | ---
`id` | string | Required. A keyword, unique within a given distribution XML file, that identifies a particular file element. This can be a combination of a text string and one or more numbers, for example `id="a1"`. The `id` value must always start with an alpha character.
`name` | string | Required. The name of the custom destination. For example, for a fax, this might be: name="fax" For a portal built with OracleAS Portal: name="oraclePortal"
`instance` | `this|all` | Default: `all` Used when the foreach element is also present. With a grouped report that is burst into separate reports, `instance` specifies whether the groups will be broken into separate `destype` instances according to each group instance (`this`) or all contained within the same `destype` instance (`all`). For example, if you custom destination type is a fax, `instance="this"` would mean a separate fax for each group instance, and `instance="all"` would mean one fax for all groups.

OracleAS Reports Services supports the creation and use of custom destination types (pluggable destinations) in the Reports Services environment. One way it does this is by allowing you to include calls to custom destinations in your distribution XML file. The distribution XML file provides a way to define custom destinations through property name/value pairs used in conjunction with the destype element.

### 15.3.10 property

Example

    <foreach>

    <destype id="custom1" name="fax" instance="all">

    <include src="headerSection"/>
    <property name="number" value="914925551212"/>

    </destype>

    </foreach>

Required/Optional

Optional. You can have as many properties as you require under a `destype` element.

Description

The `property` element allows for the inclusion of name/value pairs expressed in terms recognized by a custom destination type (destype). Properties are merely passed along to the destination handler. They serve no function within Reports Services. How you specify properties is entirely dependent on the requirements of your custom destination.

## 15.4 Distribution XML File Examples

This section provides examples, from simple to complex, of distribution XML elements. They are organized according to the main distribution.dtd elements:

- foreach Examples

- mail Examples

- file Examples

- printer Examples

### 15.4.1 foreach Examples

The examples in this section include:

- Single E-Mail with Report Groups as Separate Attachments

- Separate E-Mail for Each Group Instance

- Separate E-Mails with Separate Sections as Attachments

- Separate File for Each Section

- Separate Print Run for Each Report

#### 15.4.1.1 Single E-Mail with Report Groups as Separate Attachments

In this example, each attachment contains the corresponding instance from the header, main, and trailer sections. That is, if the report is grouped on department_id, and the first department is department 10, the first attachment will be a report with header, main, and trailer sections all containing department 10 information. This example is valid only if the header, main, and trailer sections repeat on the same group instance, in this case department_id.

    <mail id="a1" to="managers@mycompany.com" subject="New Hires">

    <foreach>

    <attach format="html" srcType="report" instance="this">

    <include src="report"/>

    </attach>

    </foreach>

    </mail>

First of all, assume in this example that "managers@mycompany.com" goes to a mailing list that distributes to each department manager. If there are four departments: 10, 20, 30, and 40, the first attachment will contain header, main, and trailer sections corresponding to department 10; the second to 20; and so on. This example will yield one e-mail per recipient, each with four attachments.

#### 15.4.1.2 Separate E-Mail for Each Group Instance

In this example, each recipient will receive a separate e-mail for each grouped report. For example, if the report is grouped on department_id, and there are four departments, one recipient will receive four e-mails, each with a separate department's report attached.

    <foreach>

    <mail id="weeklies" to="managers@mycompany.com">

    <attach format="htmlcss" srcType="report" instance="this">

    <include src="mainSection"/>

    </attach>

    </mail>

    </foreach>

#### 15.4.1.3 Separate E-Mails with Separate Sections as Attachments

In this example, different sections repeat on different groups. The distribution is set up so that each recipient will receive a separate e-mail with attachment for each grouped main section and for each grouped trailer section.

    <foreach>

    <mail id="a6" to="managers@mycompany.com" subject="Personnel Reports">

    <attach format="pdf" name="attach.pdf" srcType="report" instance="this">

    <include src="mainSection"/>

    </attach>
    <attach format="rtf" name="attach.rtf" srcType="report" instance="this">

    <include src="trailerSection"/>

    </attach>

    </mail>

    </foreach>

#### 15.4.1.4 Separate File for Each Section

In this example, a separate file is generated for each group instance. Groups repeat on department_id. Each file is named with the relevant department ID.

    <foreach>

    <file id="a10" name="department_&amp;&lt;department_id&gt;.pdf" instance="this">

    <include src="mainSection"/>

    </file>

    </foreach>

Assuming that there are four departments, 10 through 40, this example will result in the creation of four files, named in turn department_10.pdf, department_20.pdf, and so on.

The `format` attribute is not included in the `file` element because it is not required when the `srcType` is `file` or `text`. It is required when the `srcType` is `report`.

Note: If you do not specify unique filenames through the use of variable values (see Section 15.2.2), in this example, each successively created file will overwrite the previously created file. That is, the department.pdf file for department 20 will overwrite the department.pdf file for department 10, and so on, until there is only one file left, department.pdf, with information from the last department report created (e.g., department 40).

#### 15.4.1.5 Separate Print Run for Each Report

The way you specify a printer name differs between Windows and UNIX. The first example is for Windows. The second is for UNIX.

##### 15.4.1.5.1 Windows

In this example, assuming that the report is grouped on department_id, a report will be printed for each department.

    <foreach>

    <printer id="a7" name="\\server_name\printer_name" instance="this"

    <include src="report"/>

    </printer>

    </foreach>

##### 15.4.1.5.2 UNIX

In this example, assuming that the report is grouped on department_id, a report will be printed for each department.

    <foreach>

    <printer id="a7" name="printer_alias" instance="this"

    <include src="report"/>

    </printer>

    </foreach>

### 15.4.2 mail Examples

The examples in this section include:

- E-Mail with a Whole Report as the Body

- E-Mail with a Section of a Report as the Body

- E-Mail with Two Report Sections as the Body

- E-Mail with External File as Body and Report as Attachment

- E-Mail with Whole Report and Grouped Sections Attached

- E-Mail to Relevant Manager and Department

#### 15.4.2.1 E-Mail with a Whole Report as the Body

The report will comprise the content of this e-mail. That is, when recipients open this e-mail, they will see the report.

    <mail id="a5" to="managers@mycompany.com" subject="Quarterly Report">

    <body srcType="report" format="html">

    <include src="report"/>

    </body>

    </mail>

#### 15.4.2.2 E-Mail with a Section of a Report as the Body

A section of a report will comprise the content of this e-mail. That is, when recipients open this e-mail, they will see a section of the report.

    <mail id="a6" to="employees@mycompany.com">

    <body srcType="report" format="html">

    <include src="mainSection"/>

    </body>

    </mail>

The `subject` attribute is not included in this `mail` element, so the default subject will be used: `Mail Sent From &amp;Report`. At runtime, the variable `&amp;Report` will be replaced with the name of the report.

#### 15.4.2.3 E-Mail with Two Report Sections as the Body

Two sections of a report will comprise the body of this e-mail. That is, when recipients open this e-mail, they'll see two sections, headerSection and mainSection, joined together in one report.

    <mail id="emp_addresses" to="employees@mycompany.com" subject="Employee Address List">

    <body srcType="report" format="html">

    <include src="headerSection"/>
    <include src="mainSection"/>

    </body>

    </mail>

#### 15.4.2.4 E-Mail with External File as Body and Report as Attachment

The contents of the body for this email will be an external file, and the report will go along as an attachment. The path to the file is expressed differently for Windows and UNIX.

##### 15.4.2.4.1 Windows

    <mail id="XQRSN" to="accounting@mycompany.com" subject="Salaries"

    <body srcType="file">

    <include src="c:\mail\body.html"/>

    </body>
    <attach format="pdf" name="salaries.pdf" srcType="report">

    <include src="report"/>

    </attach>

    </mail>

##### 15.4.2.4.2 UNIX

    <mail id="XQRSN" to="accounting@mycompany.com" subject="Salaries"

    <body srcType="file">

    <include src="/mail/body.html"/>

    </body>
    <attach format="pdf" name="salaries.pdf" srcType="report">

    <include src="report"/>

    </attach>

    </mail>

#### 15.4.2.5 E-Mail with Whole Report and Grouped Sections Attached

In this example, recipients receive one e-mail with multiple attachments: one attachment for each group instance and an additional attachment that contains the entire report. If the report is grouped on department_id and there are four departments, recipients will receive five attachments: one for each department and one whole report.

    <mail id="grx90" to="sales@mycompany.com">

    <body srcType="text">
    Attached you will find the summary report and breakdown by department of weekly totals.
    </body>
    <attach format="rtf" name="myAttach.rtf" srcType="report">

    <include src="report"/>

    </attach>
    <foreach>

    <attach format="pdf" name="myattach.pdf" srcType="report" instance="this">

    <include src="mainSection"/>

    </attach>

    </foreach>

    </mail>

#### 15.4.2.6 E-Mail to Relevant Manager and Department

In this example, the manager for department 10 gets department 10's report; the manager for department 20 gets department 20's report; and so on. For this tag set to be valid, the variable must refer to a column that is included in the "repeat on" group used with the attached section. That is, if the section repeats on G_department_id, `manager` must be a column in that group.

    <foreach>

    <mail id="mgr1090" to="&amp;&lt;manager&gt;@mycompany.com">

    <attach format="pdf" name="attach.pdf" srcType="report" instance="this">

    <include src="mainSection"/>

    </attach>

    </mail>

    </foreach>

### 15.4.3 file Examples

Whenever you burst and distribute grouped reports to files, be sure to specify filenames with variable values based on the repeating group or some other variable information. Otherwise, you run the risk of having each successive file that is created overwrite the previously created file. For example, if you specify an output filename of `department.pdf`, and you output separate instances of each department's report, the second `department.pdf` file will overwrite the first department.pdf file; the third will overwrite the second; an so on. You will end up with only one report, that of the final department to be output. Instead, with grouped reports that you want to output separately according to each group instance, use variable values to specify filenames, for example: `name="department_&amp;&lt;department_id&gt;.pdf"`.

The examples in this section include:

- File for Whole Report

- File for Combined Report Sections

- File for Each Group of Combined Sections

- File for Each Report Group Instance

#### 15.4.3.1 File for Whole Report

This example will yield one file named report.pdf that contains the entire report.

##### 15.4.3.1.1 Windows

    <file id="a1" name="c:\reports\report.pdf" format="pdf">

    <include src="report"/>

    </file>

##### 15.4.3.1.2 UNIX

    <file id="a1" name="/reports/report.pdf" format="pdf">

    <include src="report"/>

    </file>

#### 15.4.3.2 File for Combined Report Sections

This example will yield one file named sections.pdf that contains a report consisting of the header section and the main section of the report.

    <file id="a2" name="sections.pdf" format="pdf">

    <include="headerSection"/>
    <include="mainSection"/>

    </file>

#### 15.4.3.3 File for Each Group of Combined Sections

In this example, a separate file will be created for each repeating group. Each file will contain a report that combines the relevant group main and trailer sections. The main and trailer sections must repeat on the same group, and the variable file name must refer to a column contained within the "repeat on" group. That is, if the report repeats on department_id, and you have four departments, 10 through 40, then one file will contain the main and trailer sections of department 10; the next will contain the main and trailer sections of department 20; and so on. The variable value under `name` must refer to a column that is within the G_department_id group.

    <foreach>

    <file id="file9" name="department_&amp;&lt;department_id&gt;.pdf" instance="this">

    <include src="mainSection"/>
    <include src="trailerSection"/>

    </file>

    </foreach>

#### 15.4.3.4 File for Each Report Group Instance

In this example, assuming the report is grouped on department_id and there are four departments, 10 through 40, you will end up with four files respectively named: department_10.pdf, department_20.pdf, department_30.pdf, and department_40.pdf.

    <foreach>

    <file id="a20" name="department_&amp;&lt;department_id&gt;.pdf" instance="this">

    <include src="report"/>

    </file>

    </foreach>

### 15.4.4 printer Examples

The examples in this section include:

- Print Whole Report

- Print Two Sections of a Report

- Print Grouped Report

- Print Combined Sections for Each Group Instance

- Print Relevant Instance of a Report to Its Relevant Printer

The way printer names are specified, differs between Windows and UNIX. Each example demonstrates both ways.

#### 15.4.4.1 Print Whole Report

In this example, the entire report will be sent to the specified printer.

##### 15.4.4.1.1 Windows

    <printer id="a80" name="\\neptune\prtr20">

    <include src="report"/>

    </printer>

##### 15.4.4.1.2 UNIX

    <printer id="a80" name="10th_floor_printer">

    <include src="report"/>

    </printer>

#### 15.4.4.2 Print Two Sections of a Report

In this example, two sections of a report will be sent to the printer.

##### 15.4.4.2.1 Windows

    <printer id="a1" name="\\neptune\prtr20">

    <include src="headerSection"/>
    <include src="mainSection"/>

    </printer>

##### 15.4.4.2.2 UNIX

    <printer id="a1" name="10th_floor_printer">

    <include src="headerSection"/>
    <include src="mainSection"/>

    </printer>

#### 15.4.4.3 Print Grouped Report

In this example, one report will be printed. The report will be grouped by, for example, department_id. For this to work, all sections of the report must repeat on the same group.

##### 15.4.4.3.1 Windows

    <foreach>

    <printer id="prt20" name="\\neptune\prtr20" instance="all">

    <include src="report"/>

    </printer>

    </foreach>

##### 15.4.4.3.2 UNIX

    <foreach>

    <printer id="prt20" name="10th_floor_printer" instance="all">

    <include src="report"/>

    </printer>

    </foreach>

#### 15.4.4.4 Print Combined Sections for Each Group Instance

This example will yield a number of print jobs: one for each group instance. The combined sections must repeat on the same group. If the report repeats on department_id, and you have four departments, 10 through 40, you will end up with four print jobs: one for department 10; one for department 20; and so on. The main and trailer sections must both repeat on department_id.

##### 15.4.4.4.1 Windows

    <foreach>

    <printer id="prt20" name="\\neptune\prtr20" instance="this">

    <include src="mainSection"/>
    <include src="trailerSection"/>

    </printer>

    </foreach>

##### 15.4.4.4.2 UNIX

    <foreach>

    <printer id="prt20" name="10th_floor_printer" instance="this">

    <include src="mainSection"/>
    <include src="trailerSection"/>

    </printer>

    </foreach>

#### 15.4.4.5 Print Relevant Instance of a Report to Its Relevant Printer

For this example to work, the `repeat on` group must contain a column of printer names appropriate to the host platform (e.g., the printer_name column must contain an appropriate printer alias on UNIX and a printer server/name combination on Windows). For example, if the report is grouped by department_id, then G_department_id must also have a printer_name column. Assuming the printer_names are tied to departments, then department 10's report would be printed on department 10's printer; department 20's report would be printed on department 20's printer; and so on.

    <foreach>

    <printer id="a60" name="&amp;printer_name" instance="this">

    <include src="mainSection"/>

    </printer>

    </foreach>

Each group instance equals a separate print job. Each print job goes to the relevant department's printer

## 15.5 Using a Distribution XML File at Runtime

The method for using a distribution XML file at runtime is essentially the same whether you use it in a URL or a command line. Use the commands:

    distribute=yes destination=filename.xml

Where filename is the name of the distribution XML file. You are required to specify either the relative or absolute path of the XML file. For example, for Windows, you might specify:

    distribute=yes destination=c:\ORACLE_HOME\reports\distribution\filename.xml

For UNIX, you might specify:

    distribute=yes destination=ORACLE_HOME/reports/distribution/filename.xml

The paths in these examples are used for illustrative purposes only. There is no requirement for where you store your distribution XML files. You can store them wherever you like.

Note: In some cases, Microsoft Internet Explorer ignores the mimetype of a URL's return stream and instead sets the type by looking at the URL. This can be a problem when you are using the distribution feature of OracleAS Reports Services because your URL might end with the destination parameter, for example: `...distribute=yes destination=c:\oracle\reports\distribution\mydist.xml` In this scenario, your URL ends with the extension `.xml` and Internet Explorer treats the return stream as XML, when in fact it is HTML. As a result, you will receive a browser error. To work around this issue, you should never use recognized file extensions at the end of a URL. In the example above, you could switch the positions of the distribute and destination parameters in your URL.

For detailed information on running reports from command lines and URLs and using the `cgicmd.dat` file, see Chapter 13, " Running Report Requests ".

## 15.6 Defining Custom/Pluggable Destinations

You can define a custom pluggable destination that can be used by Oracle Reports during distribution. The following examples illustrate the outlined destinations:

- Fax destination

- oraclePortal Destination

Fax destination

You can specify the destination as per the generic tag structure in the distribution XML file as follows:

Example 15-1 Generic Fax Destination

    <destype id="faxdest" name="fax">

    <property name="number" value="123456789"/>
    <include src="report"/>

    </destype>

oraclePortal Destination

You can specify the destination as per the generic tag structure in the distribution XML file as outlined in Example 15-2.

Example 15-2 illustrates a sample structure for `DESTYPE=ORACLEPORTAL.` When you push a report output to Portal using `DESTYPE=ORACLEPORTAL`, the report output will be created in the PAGEGROUP folder.

See Also: Command Line Options For more information on the properties outlined in the examples.

Example 15-2 Simple Portal Destination

    <destinations>

    <destype id="customforPortal" name="oraclePortal">

    <property name="outputpage" value="sample_report"/>
    <property name="statuspage" value="Reports_Status"/>
    <property name="desformat" value="pdf"/>
    <property name="pagegroup" value="REPORTS_OUTPUT"/>
    <property name="itemtitle" value="MyReport"/>

        <include src="report"/>
      </destype>

    </destinations>

You can specify the custom destination in accordance with the generic `destype` tag structure for a pluggable destination. Alternatively, for ease of use, you can specify a custom, more specific tag structure.

Example 15-3 Custom Fax Destination

    <fax id="faxdest" number="123456789">

    <include src="report"/>

</fax>

These tags are unknown to the `distribution.dtd`, therefore, they need to be mapped to the generic `destype` tag structure specified in the `distribution.dtd`.

Reports runtime cannot process the `<fax>` tag structure as illustrated here because the `<fax>` tag is not a standard destination specified in the `distribution.dtd` file. The custom tag structure must therefore be converted to the generic format as shown in Example 15-1.

Use the `distribution.xsl` file to transform user-defined custom tags in the distribution XML file to a format required by Reports runtime. Reports can understand only the generic `destype` tag structure for any pluggable destination.

The distribution.xsl file is an XML style sheet, located on both Windows and UNIX at `ORACLE_HOME``\reports\conf\distribution.xsl`. You can modify this file by adding a template for translating your `destype` tag format to the required format defined in the `distribution.dtd` file.

To achieve this, you must specify a template for the fax destination in the `distribution.xsl` file. The template will be used to convert the `<fax>` tag structure to the generic `destype` structure. Your `distribution.xsl` entry might look like this:

    <xsl:output doctype-system="distribution.dtd"/>

    <xsl:template match = "/">

    <xsl:apply-templates match = "destinations" />

    </xsl:template>

    <xsl:template match="destinations">

    <destinations>

    <!--
    The Standard mail/file/printer/destype and foreach must be copied to the transformed xml. The foreach tag must be copied only if it is specified with file/mail/printer/destype tags.
    -->

    <xsl:copy-of select="mail"/>
    <xsl:copy-of select="file"/>
    <xsl:copy-of select="printer"/>
    <xsl:copy-of select="destype"/>
    <xsl:copy-of select="foreach"/>

    <!-- apply template for the sample FAX destination -->
    <xsl:apply-templates match = "fax" />

    </destinations>

    </xsl:template>

    <!--

    Sample Transformation Template for a FAX destination specified in the distribution.xml file

    <fax id="FAXDEST" number="123456789">

    <include src="report"/>

    </fax>

    -->

    <xsl:template match="fax">

    <!-- create a new destype element -->
    <xsl:element name="destype">

    <!--
    create an ID attribute and copy the value from the ID given for the fax destination
    -->

    <xsl:attribute name="id">

    <xsl:value-of select="@id"/>

    </xsl:attribute>

    <!-- create a Name attribute with a fax as it's value -->
    <xsl:attribute name="name">fax</xsl:attribute>
    <!--
    create a Property Attribute with name / value attribute pairs property tag is created for number attribute. Similarly create more property tags for any other attribute you add to the FAX destination
    -->
    <xsl:element name="property">

    <xsl:attribute name="name">number</xsl:attribute>
    <xsl:attribute name="value">

    <xsl:value-of select="@number"/>

    </xsl:attribute>

    </xsl:element>

    <!-- copy the include tag as it is -->
    <xsl:copy-of select="include"/>

    </xsl:element>
    <!-- end of template -->

    </xsl:template>

    </xsl:stylesheet>

Note: All you need to do after you modify the XSL file is save it back to the same location under the same file name. Reports will automatically look for this XSL file when resolving distributions.

## 15.7 Limitations with using distribution

This section outlines the various limitations with using distribution in Oracle Reports.

### 15.7.1 destype=oraclePortal

From Oracle9i Reports Release 2 (9.0.2) onwards, Reports Server supports OracleAS Portal as a destination. By using `DESTYPE=ORACLEPORTAL`, you can push a report to an output page specified in OracleAS Portal.

See Also: Command Line Options and the Reports Builder Online Help for more information on the `DESTYPE` command line keyword.

However, there are a few limitations in using this destination:

- The `ORACLEPORTAL` destination cannot be used with distribution. Instead, you can use `DESTYPE=WEBDAV` for advanced XML based distribution to OracleAS Portal.

  Note: Ensure that the OracleAS Portal instance should be WebDAV-enabled. Refer to the OracleAS Portal online help for more information on how to enable WebDAV. For more information on how to use WebDAV for distribution to OracleAS Portal, refer to the Tech note at:`http://webiv.oraclecorp.com/cgi-bin/webiv/do.pl/Get?WwwID=note:241821`

- The `DESTYPE=ORACLEPORTAL` destination cannot be used with the `rwrun` executable as it causes Reports Server to stop responding. Use this destination only with `rwservlet`, `rwclient`, or `rwcgi`.

### 15.7.2 XML and delimited outputs

Using reference parameters for report bursting (that is, by specifying `instance=this`) is not supported for `DESFORMAT=XML` and `DESFORMAT=DELIMITED`. If used, it results in the following error message:

    REP-34310 "Reference parameter not allowed in distribution list for XML destination files"

However, these formats can be used in distribution without specifying a reference parameter.

This limitation will be resolved in a future release.

### 15.7.3 Distribution and dynamic format values

XML distribution supports only static values for the `format` attribute (as seen in `distribution.dtd`). Thus, you cannot specify lexical parameters (to be resolved at runtime) for the format attribute. Hence the format cannot be dynamically determined either for the entire report or for a specific section.

This limitation will be resolved in a future release.