16
XMLによるレポートのカスタマイズ

Extensible Markup Language（XML）は、情報をより詳細に識別する方法を実現することにより、Webの機能を向上させることを目的として設計された言語です。XMLはメタ言語（他の言語を定義するための言語）です。XMLを使用して、様々なタイプのドキュメント用にカスタマイズされたマークアップ言語を設計できます。

XMLドキュメントは、マークアップとその内容の両方で構成されます。

要素は、XMLのビルディング・ブロックです。要素インスタンスは、タグ（メインのタグと適切にネストされたタグ）、属性、タグとタグの間にネストされた要素内容からなる構造を持ちます。
タグは、要素とその内容を定義するために使用されます。
属性は、各タグの追加情報を提供するものです。

XMLカスタマイズを使用すると、実行時に元のレポートを変更することなくレポートをカスタマイズできます。ランタイム・コマンドラインにCUSTOMIZEキーワードを追加し、カスタマイズ・ファイルを呼び出して、レポートのレイアウトやデータ・モデルへの追加や変更を実行できます。1つのXMLカスタマイズ・ファイルで、これらすべての作業または任意の作業の組合せを実行できます。XMLを使用して、カスタムのJSPベース・レポートに取り込むレポート・データ・モデルを作成することも可能です。

様々なXMLカスタマイズを作成して適用すると、レポート出力をユーザー単位またはユーザー・グループ単位で変更できます。同じレポートを使用して、利用対象者ごとに異なる出力を生成できます。

XMLカスタマイズをレポートに適用するときに、結合した定義をファイルに保存することができます。このため、XMLカスタマイズを使用して、既存のレポート定義をバッチ更新できます。Reports Builderで1つずつファイルを開くことなく、大量のレポート定義をすばやく更新できます。

OracleAS Reports Servicesでは、XMLでレポート・データ・モデル全体を作成できるようになり、Oracle Reports XMLによるカスタマイズのタイプが拡張されました。これには、複数データソースの作成、データソース間のリンク、および各データソース内でのグループ階層が含まれます。Oracle Reports XMLカスタマイズによるデータ・モデルのサポートを通じて、Reports Builderで作成可能なすべてのデータ・モデルを、XMLを指定して作成できるようになりました。さらに、データ・モデル・オブジェクトに設定可能なすべてのプロパティを、XMLで設定できるようになりました。

この章では、XMLを使用して実行中にレポートをカスタマイズする方法、およびXMLでデータ・モデルを作成する方法について説明します。この章には、次の項があります。

この章では、reports.dtdファイルでサポートされる要素を紹介し、その例を示します。ただし、これらの要素の属性については、一部のみを紹介します。

追加属性、またはOracle Reports XMLの要素、タグおよび属性の詳細は、次を参照してください。

reports.dtdファイルには、Oracle Reports XMLのすべての要素、タグと属性、そして存在する場合は属性のデフォルト値が含まれます。reports.dtdファイルは、WindowsとUNIXどちらの場合も、ORACLE_HOME¥reports¥dtd¥ にあります。サブ要素の多くは、使用時の規則を示す記号を含んでいます。次に例を示します。
- プラス記号（+）は、XMLファイルでそのタイプの要素を1つ以上使用できることを意味します。
- アスタリスク（*）は、XMLファイルでそのタイプの要素を0～多数の範囲で使用できることを意味します。
- 疑問符（?）は、XMLファイルでそのタイプの要素を0または1つだけ使用できることを意味します。
- 記号が付いていない場合は、XMLファイルでそのタイプの要素を1つだけ使用する必要がある（必須である）ことを意味します。
複数のサブ要素が括弧で囲まれ、その直後に記号が付いている場合は、その記号が括弧内のすべてのサブ要素に適用されます。
選択したOracle Reports XMLタグの詳細は、Oracle Reportsのオンライン・ヘルプの「リファレンス」の項のトピック「Oracle Reports XMLタグ」を参照してください。
作成しようとするカスタマイズのタイプを含んだレポートを作成し、レポートをXMLとして保存し、さらにテキスト・エディタで保存したファイルを表示します。これは、実際のOracle Reports XMLを参照する優れた手段であると同時に、より複雑なモデルを構築する場合の参考になります。

16.1 カスタマイズの概要

Oracle Reports XMLタグを使用して、Reports Builderを使用して作成したレポートをカスタマイズできます。

注意
Oracle Reports XMLのタグを使用してレポート全体を手動で作成することも可能ですが、ドキュメントに記載され、サポートされているのは、手動で作成されるカスタマイズおよびデータ・モデルのみです。

XMLカスタマイズの作成と適用は、3つのステップで行われます。

Oracle Reports XMLのタグを使用してカスタマイズ・ファイルを作成します。

このカスタマイズは、Reports Builderでレポートを作成し、そのレポートをXMLとして保存することで作成できます。任意のテキスト・エディタまたは高機能のXMLエディタを使用して、手動でカスタマイズを作成することもできます。これは、特別なOracle Reportsカスタマイズに必要なXMLタグを使用する場合にかぎられます。
XMLカスタマイズを、OracleAS Reports Servicesでアクセス可能な場所に格納します。

XMLカスタマイズを、CUSTOMIZEコマンドライン・キーワードまたはSRW.APPLY_DEFINITIONビルトイン・プロシージャを使用して、別のレポートに適用します。カスタマイズに完全なレポート定義が含まれている場合は、REPORT（またはMODULE）コマンドライン・キーワードを使用してXMLカスタマイズを単独で実行できます。

関連項目
第A.3.20項「CUSTOMIZE」

注意
SRW.APPLY_DEFINITIONビルトイン・プロシージャを含んだSRWビルトイン・パッケージの説明については、Oracle Reportsのオンライン・ヘルプを参照してください。

16.2 XMLカスタマイズの作成

この項では、様々なレポート・カスタマイズの例を示します。ここで取り上げる例は、次のとおりです。

16.2.1 必須XMLタグ

すべてのXMLカスタマイズには、次のタグ・ペアが必要です。

<report></report>

たとえば、最小限のXMLカスタマイズは次のとおりです。

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

このXMLカスタマイズには何も含まれていないので、レポートに適用しても効果は一切ありません。必要なタグがあるので解析はできますが、単に必須タグの例として示しています。

<report>タグは、レポート・カスタマイズの開始、レポート・カスタマイズ名およびこのXMLカスタマイズで使用するデータ型ディクショナリ（DTD）ファイルのバージョンを示します。</report>タグは、レポート・カスタマイズの終了を示します。

reportタグのname属性には、任意の名前を指定できます。たとえば、XMLファイルでカスタマイズするレポートの名前でも、それ以外の名前でもかまいません。

この例では、<report>タグが最小限で使用されています。<report>タグにも多数の属性がありますが、そのほとんどは暗黙的に示されており、指定する必要はありません。<report>に唯一必要な属性は、DTDVersionです。

注意
XMLカスタマイズ・ファイルを適用して、既存のレポート・トリガーを変更するか新しいレポート・トリガーを作成するには、<report>タグの関連トリガー属性を指定する必要があります。
たとえば、Before Reportトリガーを変更または作成するには、beforeReportTrigger属性を使用します。
<report DTDVersion="9.0.2.0.0" beforeReportTrigger="BeforeReport">

XMLカスタマイズ・ファイルを適用してレポート・トリガーを変更または作成するときにこの属性を指定しないと、XMLカスタマイズ・ファイルがレポートに適用されたときに、レポート・トリガーのPL/SQLコードがローカル(依存しない)ファンクションとして扱われます。

完全なレポート定義には、データ・モデルとレイアウトの両方が必要です。したがって、次のタグとその内容を定義する必要があります。

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

dataタグには、属性がありません。layoutタグには、panelPrintOrderとdirectionの2つの属性があり、その両方が必須です。これらの属性にデフォルト値（それぞれacrossDownとdefault）を使用する場合は、属性を指定する必要がありません。data要素とlayout要素の例は、次の各項で示します。

16.2.2 スタイルの変更

この項の例では、XMLを使用して、レポート・フィールドF_Mincurrent_pricePersymbolおよびF_Maxcurrent_pricePersymbolに使用されている塗りつぶしカラーと線カラーを変更しています。

<report name="anyName" DTDVersion="9.0.2.0.0">
  <layout>
    <section name="main">
      <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>
</report>

この例では、sectionタグとfieldタグのname属性が、このXMLファイルでカスタマイズされるレポートのメイン・セクションに含まれるフィールドの名前と一致していることが前提となっています。この前提を踏まえて、fieldタグのその他の属性は、レポートのメイン・セクション内にある同じ名前のフィールドのみに適用されます。

16.2.3 書式マスクの変更

この項の例では、XMLを使用して、レポート・フィールドf_trade_dateに使用される書式マスクを変更しています。

<report name="anyName" DTDVersion="9.0.2.0.0">
  <layout>
    <section name="main">
      <field name="f_trade_date"
             source="trade_date"
             formatMask="MM/DD/RR"/>
    </section>
  </layout>
</report>

fieldタグが独自の終了書式（/>）を使用していることに注意してください。fieldタグが追加の子タグを使用する場合は、fiieldタグを</field>で閉じます。

16.2.4 書式例外の追加

この項の例では、XMLを使用して、レポートのf_p_eおよびf_p_e1フィールドで10より大きな値をハイライトする書式例外を追加しています。

<report name="anyName" DTDVersion="9.0.2.0.0">
  <layout>
    <section name="main">
      <field name="f_p_e" source="p_e">
      <exception textColor="red">
       <condition source="p_e" operator="gt" operand1="10"/>
        </exception>
      </field>
      <field name="f_p_e1" source="p_e">
        <exception textColor="blue">
       <condition source="p_e" operator="gt" operand1="10"/>
        </exception>
      </field>
    </section>
  </layout>
</report>

この例では、operatorの値が、"大なり"を示すgtに設定されています。operatorには、表16-1に示すものを指定できます。

表16-1 operator属性の値

演算子	使用方法
`eq`	等しい
`lt`	より小さい
`lteq`	以下
`neq`	等しくない
`gt`	より大きい
`gteq`	以上
`btw`	範囲内
`notBtw`	範囲外
`like`	類似
`notLike`	非類似
`null`	NULL
`notNull`	非NULL

前の例とは異なり、この例のfieldタグは、子タグを使用しているために、自己完結型の終了書式（/>）ではなく、</field>で閉じられていることにも注意してください。

16.2.5 プログラム・ユニットとハイパーリンクの追加

この項の例では、XMLを使用してレポートにプログラム・ユニットを追加しています。このプログラム・ユニットによって、従業員の社会保障番号（SSN）から従業員の詳細にアクセスするハイパーリンクが追加されます。

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

CDATAタグは、PL/SQLをXMLと区別する目的で、PL/SQLの周辺で使用されています。XMLファイルにHTMLを埋め込むときも、同じタグ・シーケンスを使用します。この例では、advancedLayoutタグのformatTrigger属性の名前でファンクションが参照されています。

16.2.6 新規問合せの追加と新規ヘッダー・セクションでの結果の使用

この項の例では、XMLを使用して、レポートに新しい問合せを追加するとともに、その問合せの結果を利用する新しいヘッダー・セクションを追加しています。

<report name="ref" DTDVersion="9.0.2.0.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="BLAFbeige.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>

この例のXMLは、データ・モデルと完全なレイアウトを備えているため、単独で実行できます。

列名が必ず一意となるように、SELECT文では別名を使用します。別名を使用しなかった場合は、レポート列のデフォルト名が使用されるため、予定外の名前になる可能性があります（たとえば、portidではなくportid1など）。fieldタグのsource属性を指定する場合は、ソース列（フィールド）の正しい名前を使用する必要があるので、この名前の指定は重要なポイントになります。

labelAttribute要素は、レイアウト内のフィールド・ラベルの書式を定義します。これはfieldタグの開始と終了タグの外側にあるため、表形式レイアウトのすべてのラベルに適用されます。この書式をいずれか1つのフィールドに関連付ける場合は、この要素を<field></field>タグ・ペアの内側に配置します。グローバルおよびローカルのlabelAttribute要素が両方とも（1つは<field></field>タグ・ペアの外側に、もう1つは内側に）存在する場合は、ローカルなラベル属性がグローバルな属性より優先されます。

16.2.7 URLのエンコード

スペースおよび制御文字が正しく渡されるようにするには、レポートの各フィールドに対してURLエンコードをオンまたはオフにする必要があります。URLエンコードのオンとオフの切替えは、レポートにRW:FIELDタグを使用します。

<rw:field
...
urlEncode=yes|no
...
/>

urlEncodeのデフォルト値は、noです。

16.3 XMLデータ・モデルの作成

OracleAS Reports Servicesでは、Oracle Reports XMLのタグを使用して、より高度なデータ・モデルのタイプを作成できるようになりました。次の処理にOracle Reports XMLを使用できます。

この項では、Oracle Reports XMLを使用した処理の例を示します。

これらのデータ・モデル・タイプに加えて、OracleAS Reports ServicesではXMLでのPL/SQLの使用をサポートしています。これには、ローカルなプログラム・ユニット、レポートレベルのトリガーおよび連結PL/SQLライブラリに対するサポートが含まれます。

16.3.1 複数のデータソースの作成

<data>タグが、新しいプラッガブル・データソースと複数のデータソースの作成をサポートするようになりました。各データソースは、それぞれの<dataSource>タグ内に記述されます。dataSource要素のデータ型定義は、次のとおりです。

<!ELEMENT dataSource
  ((select|plugin|plsql),
  comment?,
  displayInfo?,
  formula*,
  group*)>
<!ATTLIST dataSource
  name CDATA #IMPLIED
  defaultGroupName CDATA #IMPLIED
  maximumRowsToFetch CDATA #IMPLIED>

次の例では、2つのSQLデータソースを作成し、それぞれにQ_1およびQ_2という名前を付けます。また、各データソースに必要なすべての列を作成するとともに、デフォルト・グループを作成します。このグループの名前には、指定のdefaultGroupNameが設定されます。defaultGroupNameが指定されていない場合は、デフォルトで独自の名前が設定されます。

<report name="anyname" DTDVersion="9.0.2.0.0">
  <data>
    <dataSource name="Q_1" defaultGroupName="G_DEPARTMENTS">
      <select>
      select * from departments
      </select>
    </dataSource>
    <dataSource name="Q_2" defaultGroupName="G_EMPLOYEES">
      <select>
      select * from employees
    </select>
    </dataSource>
  </data>
</report>

16.3.2 データソース間のリンク

複数のデータソースが存在するときは、それらのデータソースをリンクして適切なデータ・モデルを作成することが必要となる場合もあります。Oracle Reports XMLでは、Oracle Reportsデータ・モデル・リンク・オブジェクトも公開されています。このオブジェクトは、グループレベルおよび列レベルのリンクをサポートします。任意の数のリンクを指定して、必要なデータ・モデルを作成できます。

link要素のデータ型定義は、次のとおりです。

<!ELEMENT link EMPTY>
<!ATTLIST link
  name CDATA #IMPLIED
  parentGroup CDATA #IMPLIED
  parentColumn CDATA #IMPLIED
  childQuery CDATA #IMPLIED
  childColumn CDATA #IMPLIED
  condition (eq|lt|neq|gt|gteq|like|notLike) "eq"
  sqlClause (startWith|having|where) "where">

link要素は、data要素の内部に配置され、data要素内に定義されているdataSourceオブジェクトのうち任意の2つをリンクします。次に例を示します。

<report name="anyname" DTDVersion="9.0.2.0.0">
  <data>
    <dataSource name="Q_1" defaultGroupName="G_DEPARTMENTS">
      <select>
        select * from departments
      </select>
    </dataSource>
    <dataSource name="Q_2" defaultGroupName="G_EMPLOYEES">
      <select>
        select * from employees
      </select>
    </dataSource>
    <link name="L_1" parentGroup="G_DEPARTMENTS"
          parentColumn="DEPARTMENT_ID" childQuery="Q_2"
          childColumn="DEPARTMENT_ID1" condition="eq" sqlClause="where"/>
  </data>
</report>

link要素の内部では、Oracle Reportsのデフォルト設定メカニズムによって、DEPARTMENT_ID1がEMPLOYEES表におけるDEPARTMENT_ID列の別名と認識されます。この場合、ユーザーが明示的に別名を作成する必要はありません。

16.3.3 各データソース内でのグループ階層の作成

OracleAS Reports Servicesでは、完全なグループ階層を利用することができます。各グループ内ですべての列を指定し、それらの列の順序をブレークすることができます。式、サマリーおよびプレースホルダを使用して、グループ内でさらにオブジェクトをカスタマイズできます。

group要素のデータ型定義は、次のとおりです。

<!ELEMENT group
  (field|exception|rowDelimiter|xmlSettings|displayInfo|dataItem|formula|
  summary|placeholder|filter|comment)*>
<!ATTLIST group
  name CDATA #IMPLIED
  fillColor CDATA #IMPLIED
  lineColor CDATA #IMPLIED
  formatTrigger CDATA #IMPLIED>

次の例では、group要素を使用して、データソースの下にブレーク・グループを作成しています。

<report name="anyname" DTDVersion="9.0.2.0.0">
  <data>
    <dataSource name="Q_1">
      <select>
        select * from employees
      </select>
      <group name="G_DEPARTMENTS">
        <dataItem name="DEPARTMENT_ID"/>
      </group>
      <group name="G_EMPLOYEES">
        <dataItem="EMPLOYEE_ID"/>
        <dataItem="FIRST_NAME"/>
        <dataItem="LAST_NAME"/>
        <dataItem="JOB_ID"/>
        <dataItem="MANAGER_ID"/>
        <dataItem="HIRE_DATE"/>
        <dataItem="SALARY"/>
        <dataItem="COMMISSION_PCT"/>
      </group>
    </dataSource>
  </data>
</report>

16.3.4 クロス積（マトリックス）グループの作成

クロス積グループを使用すると、データ・モデルに任意の数のグループのマトリックスを定義できます。クロス積の各ディメンション・グループは、同じデータソースに属している場合でも、様々なデータソースから結合されている場合でも、マトリックスを作成できます。この柔軟性に対応して、<crossProduct>タグは、すべてのデータソースとグループが作成された後で、<data>タグ内に配置されます。

crossProduct要素のデータ型定義は、次のとおりです。

<!ELEMENT crossProduct
  (xmlSettings|displayInfo|dimension|(formula|summary|placeholder)*|comment)*>
<ATTLIST crossProduct
  name CDDATA #IMPLIED
  mailText CDDATA #IMPLIED>

次の例では、単一問合せマトリックスを作成しています。

<report name="anyname" DTDVersion="9.0.2.0.0">
  <data>
    <dataSource name="Q_1">
      <select>
        select * from employees
      </select>
      <group name="G_DEPARTMENTS">
        <dataItem name="DEPARTMENT_ID"/>
      </group>
      <group name="G_JOB_ID>
        <dataItem name="JOB_ID"/>
      </group>
      <group name="G_MANAGER_ID">
        <dataItem name="MANAGER_ID"
      </group>
      <group name="G_EMPLOYEE_ID">
        <dataItem name="EMPLOYEE_ID"/>
      <dataItem name="FIRST_NAME"/>
        <dataItem name="LAST_NAME"/>
        <dataItem name="HIRE_DATE"/>
        <dataItem name="SALARY"/>
        <dataItem name="COMMISSION_PCT"/>
      </group>
    </dataSource>
    <crossProduct name="G_Matrix">
      <dimension>
        <group name="G_DEPARTMENTS">
      </dimension>
      <dimension>
      <group name="G_JOB_ID">
      </dimension>
      <dimension>
      <group name="G_MANAGER_ID">
      </dimension>
    </crossProduct>
  </data>
</report>

16.3.5 あらゆるレベルでの式、サマリーおよびプレースホルダの作成

式、サマリーおよびプレースホルダは、データ・モデル内のあらゆるレベルに配置できます。さらに、これらの各オブジェクトの属性は、どれも完全に制御することができます。

次の例では、ソースがグループ・レベルの式列に基づいている、レポートレベルのサマリーを作成しています。

<report name="anyname" DTDVersion="9.0.2.0.0">
  <data>
    <dataSource name="Q_1">
      <select>
        select * from employees
      </select>
      <group name="G_EMPLOYEES">
        <dataItem="EMPLOYEE_ID"/>
        <dataItem name="EMPLOYEE_ID"/>
        <dataItem name="FIRST_NAME"/>
        <dataItem name="LAST_NAME"/>
        <dataItem name="HIRE_DATE"/>
        <dataItem name="SALARY"/>
        <dataItem name="COMMISSION_PCT"/>
        <dataItem name="DEPARTMENT_ID"/>
        <formula name="CF_REMUNERATION" source="cf_1formula"
          datatype="number" width="20" precision="10"/>
      </group>
    </dataSource>
    <summary name="CS_REPORT_LEVEL_SUMMARY" function="sum" width="20"
      precision="10" reset="report" compute="report"/>
  </data>
  <programUnits>
    <function name="cf_1formula" returnType="number">
      <textSource>
        <![CDATA[
          function CF_1Formula return Number is
          begin
          return (:salary + nvl(:commission_pct,0));
          end;
        ]]>
      </textSource>
    </function>
  </programUnits>
</report>

16.3.6 パラメータの作成

Oracle Reports XMLでは、parameter要素がdataタグの開始と終了の間に配置されます。parameter要素のデータ型定義は、次のとおりです。

<!ELEMENT parameter (comment?|listOfValues?)>
<!ATTLIST parameter
  name CDATA #REQUIRED
  datatype (number|character|date) "number"
  width CDATA "20"
  scale CDATA "0"
  precision CDATA "0"
  initialValue CDATA #IMPLIED
  inputMask CDATA #IMPLIED
  validationTrigger CDATA #IMPLIED
  label CDATA #IMPLIED
  defaultWidth CDATA #IMPLIED
  defaultHeight CDATA #IMPLIED>

次の例は、動的値リスト（LOV）、初期値および妥当性チェックトリガーを示しています。

<report name="anyname" DTDVersion="9.0.2.0.0">
  <data>
    <dataSource name="Q_1" defaultGroupName="G_DEPARTMENTS">
      <select>
        select * from departments
      </select>
      </dataSource>
        <parameter name="P_LAST_NAME" datatype="character" precision="10"
          initialValue="SMITH" validationTrigger="p_last_namevalidtrigger"
          defaultWidth="0" defaultHeight="0">
          <listOfValues restrictToList="yes">
            <selectStatement hideFirstColumn="yes">
              <![CDATA[select last_name, 'last_name||'-'||employee_id'
                from employees]]>
            </selectStatement>
          </listOfValues>
        </parameter>
  </data>
  <programUnits>
    <function name="p_last_namevalidtrigger" returnType="character">
      <textSource>
        <![CDATA[function P_LAST_NAMEValidTrigger return boolean is
          last_name char(20);
          begin
            select count(*) into last_name from employees
              where upper(last_name)=upper(:p_last_name);
            exception when OTHERS then return(FALSE);
            end;
            return(TRUE);
          end;
        ]]>
      </textSource>
    </function>
  </programUnits>
</report>

16.4 実行時のXMLファイルの使用方法

作成したOracle Reports XMLカスタマイズ・ファイルは、次の方法で使用できます。

CUSTOMIZEコマンドライン・キーワードまたはSRW.APPLY_DEFINITIONビルトイン・プロシージャを指定して、実行時にXMLレポート定義をRDFまたはその他のXMLファイルに適用します。詳細は、第16.4.1項「実行時のXMLレポート定義の適用」を参照してください。

注意
Oracle Reportsでは、REPファイルのXMLカスタマイズはサポートされません。
REPORT（またはMODULE）コマンドライン・キーワードを指定して、XMLレポート定義を単独で（他のレポートなしで）実行します。詳細は、第16.4.2項「XMLレポート定義の単独での実行」を参照してください。
CUSTOMIZEコマンドライン・キーワードを使用して、rwconverterによるバッチ変更を実行します。詳細は、第16.4.3項「バッチ変更の実行」を参照してください。

この後の項では、各ケースを詳しく説明するとともに、例を示します。

16.4.1 実行時のXMLレポート定義の適用

実行時にXMLレポート定義をRDFまたはその他のXMLファイルに適用するには、CUSTOMIZEコマンドライン・キーワードまたはSRW.APPLY_DEFINITIONビルトイン・プロシージャを使用します。CUSTOMIZEは、rwclient、rwrun、rwbuilder、rwconverterおよびURLレポート・リクエストとともに使用できます。

注意
CUSTOMIZEをrwconverterとともに使用する方法の詳細は、第16.4.3項「バッチ変更の実行」を参照してください。

16.4.1.1 1つのXMLレポート定義の適用

次に示すコマンドラインは、ジョブ・リクエストをOracleAS Reports Servicesに送信し、XMLレポート定義（emp.xml）をRDFファイル（emp.rdf）に適用します。この例では、CUSTOMIZEキーワードがWindowsのディレクトリ・パスにあるファイルを参照しています。UNIXの場合は、UNIXの標準に従ってパスを指定してください（つまり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

Reports Runtimeのコマンドであるrwrunを使用する場合のコマンドラインは、次のとおりです。

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

XMLレポート定義をテストするときは、トレース・ファイルを作成するオプションを追加してレポート・リクエストを実行すると便利な場合があります。次に例を示します。

TRACEFILE=emp.log TRACEMODE=trace_replace TRACEOPTS=trace_app

注意
Reports Server構成ファイルにデフォルトのトレース・オプションを指定した場合は、そのデフォルトを変更する必要がないかぎり、コマンドラインにトレースを含める必要はありません。

トレース・ファイルにより、レポート・オブジェクトの作成および書式に関する詳細なリストが得られます。

16.4.1.2 複数のXMLレポート定義の適用

実行時に複数のXMLレポート定義をレポートに適用するには、CUSTOMIZEコマンドライン・キーワードにリストを指定します。次に示すコマンドラインは、2つのXMLレポート定義EMP0.XMLおよびEMP1.XMLをRDFファイルEMP.RDFに適用するジョブ・リクエストを、OracleAS Reports Servicesに送信します。

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

注意
この例では、CUSTOMIZEの値に、Windowsプラットフォームに格納されているファイルへのディレクトリ・パスが示されています。UNIXの場合は、そのプラットフォームの標準に従ってディレクトリ・パスを指定してください（つまり円記号（¥）のかわりに通常のスラッシュを使用）。

Reports Runtimeを使用する場合のコマンドラインは、次のとおりです。

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

16.4.1.3 PL/SQLでのXMLレポート定義の適用

PL/SQLでRDFファイルにXMLレポート定義を適用するには、Before Parameter FormまたはAfter Parameter FormトリガーでSRW.APPLY_DEFINITIONおよびSRW.ADD_DEFINITIONビルトイン・プロシージャを使用します。この後の項では、これらのビルトイン・プロシージャの例を示します。

注意
SRW.APPLY_DEFINITIONおよびSRW.ADD_DEFINITIONビルトイン・プロシージャを含んだSRWビルトイン・パッケージの説明、およびレポート・トリガーの詳細は、Oracle Reportsのオンライン・ヘルプを参照してください。

16.4.1.3.1 ファイルに保存されたXML定義の適用

ファイル・システムに保存されたXMLをレポートに適用するには、レポートのBefore Parameter FormまたはAfter Parameter FormトリガーでSRW.APPLY_DEFINITIONビルトイン・プロシージャを使用します。

Windowsの場合:

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

UNIXの場合:

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

レポートの実行時に、トリガーが実行され、指定したXMLファイルがレポートに適用されます。

16.4.1.3.2 メモリーに保存されたXML定義の適用

メモリー内にXMLレポート定義を作成するには、SRW.ADD_DEFINITIONを使用してドキュメント・バッファに定義を追加した後に、SRW.APPLY_DEFINITIONビルトイン・プロシージャを使用してその定義を適用する必要があります。

次の例では、ユーザーが入力したパラメータ値に基づいてメモリー内にいくつかの定義を作成し、それらを適用する方法を示します。この例のPL/SQLは、videosales_custom.rdfというレポートのAfter Parameter Formトリガーで使用されます。

videosales_custom.rdfファイルのAfter Parameter Formトリガーに入っているPL/SQLが実行する内容は、次のとおりです。

実行時にユーザーによって入力されたパラメータ値に基づいて、条件と合致したフィールドをハイライトします。
実行時にユーザーによって入力されたパラメータ値に基づいて、数値書式マスクを変更します。

次のヒントは、この例を参照する際に役立ちます。

SRW.APPLY_DEFINITIONビルトイン・プロシージャを使用するたびに、ドキュメント・バッファがフラッシュされるので、そのたびにSRW.ADD_DEFINITIONを使用してXMLレポート定義を新規作成する必要があります。
パラメータhilite_profits、hilite_costs、hilite_salesおよびmoney_formatを使用して、XMLレポート定義に入れる内容を決定している点に注意してください。hilite_profits、hilite_costsおよびhilite_salesパラメータは、書式例外でも使用されており、これによってハイライトする値が決定します。

VARCHAR2列のサイズには上限があるため（4000バイト）、かなり大きなXMLレポート定義の場合は、複数の列にまたがって指定しなければならない場合もあります。その場合は、1つの大きな定義を作成して一度に適用するのではなく、メモリー内に定義をいくつか作成し、別々に適用する必要があります。

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;

16.4.2 XMLレポート定義の単独での実行

XMLレポート定義を単独で実行するには、REPORT（またはMODULE）オプションにXMLファイルを指定してリクエストを送信します。次のコマンドラインは、レポートemp.xmlを単独で実行するジョブ・リクエストをOracleAS Reports Servicesに送信します。

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

Reports Runtimeのコマンドであるrwrunを使用する場合のコマンドラインは、次のとおりです。

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

この方法でXMLレポート定義を実行する場合は、必ずXMLファイルの拡張子を指定します。また、CUSTOMIZEコマンドライン・キーワードを使用して、XMLカスタマイズ・ファイルをこのレポートに適用することもできます。

16.4.3 バッチ変更の実行

更新を必要とするレポートが大量にある場合は、rwconverterでCUSTOMIZEコマンドライン・キーワードを使用して、バッチ変更を実行できます。バッチ変更は、多数のレポートに同じ変更を繰り返し実行する必要がある場合に特に便利です（たとえば、フィールドの書式マスクの変更など）。Reports Builderでレポートを1つずつオープンして手動で変更するかわりに、rwconverterを1回実行するだけで、一度に多数のレポートに同じ変更を加えることができます。

次の例では、2つのXMLレポート定義translate.xmlおよびcustomize.xmlを3つのRDFファイルinven1.rdf、inven2.rdfおよびmanu.rdfに適用し、変更後の定義を新しいファイルinven1_new.rdf、inven2_new.rdfおよび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

16.5 XMLレポート定義のデバッグ

次の機能は、XMLレポート・ファイルをデバッグする際に役立ちます。

16.5.1 XMLパーサーのエラー・メッセージ

XMLパーサーは、Oracleデータベース・リリースに付属するOracle XML Development Kit（XDK）に含まれています。XMLパーサーは、XML構文の妥当性をチェックするJavaパッケージです。XMLパーサーを含むJARファイルは、インストール時に自動的に設定され、Oracle Reportsで使用可能となります。

XMLパーサーは、ほとんどの構文エラーを検出し、エラー・メッセージを表示します。エラー・メッセージは、エラーが発生したXMLファイルの行番号と、エラーの簡単な説明から成ります。

XMLパーサーの詳細は、Oracle Technology Network（http://www.oracle.com/technology/index.html）を参照してください。その場合、XML parserまたはXDKで検索します。Oracleデータベース付属のドキュメントにも情報が記載されています。

16.5.2 トレース・オプション

XMLレポート定義をテストする際に、トレース・ファイルを作成するオプションを追加してレポートを実行すると便利です。次に例を示します。

rwrun username/password@my_db REPORT=¥CORP¥MYREPORTS¥EMP.XML
  TRACEFILE=emp.log TRACEMODE=trace_replace TRACEOPTS=trace_app

このコマンドラインの最後の3つのオプションによって、レポート処理の詳細リストを含むトレース・ファイルが生成されます。トレース・ファイル・ログのデフォルトの位置は、WindowsとUNIXで同じです。

ORACLE_HOME¥reports¥logs¥

注意
この例では、REPORTオプションおよびトレース・ログへのパスに、Windowsプラットフォームに格納されているファイルへのディレクトリ・パスが示されています。UNIXの場合は、そのプラットフォームの標準に従ってディレクトリ・パスを指定してください（つまり円記号（¥）のかわりに通常のスラッシュを使用）。

16.5.3 rwbuilder

XMLレポート定義の設計時には、Reports Builderでオープンしたほうが便利な場合があります。Reports Builderでは、オブジェクトが期待どおりに作成または変更されているかをすぐに確認できます。たとえば、XMLレポート定義にサマリーを作成する場合、Reports Builderで定義をオープンすると、サマリーがデータ・モデルの適切なグループに配置されているかどうかが一目でわかります。

Reports Builderで完全なレポート定義をオープンするには、REPORT（またはMODULE）キーワードを使用します。次に例を示します。

rwbuilder USERID=username/password@my_db REPORT=c:¥corp¥myreports¥emp.xml

Reports Builderで部分レポート定義をオープンするには、CUSTOMIZEキーワードを使用します。次に例を示します。

rwbuilder USERID=username/password@my_db REPORT=emp.rdf 

CUSTOMIZE=c:¥myreports¥emp.xml

注意
この例では、REPORTオプションによって、Windowsプラットフォームに格納されているファイルへのディレクトリ・パスが指定されます。UNIXの場合は、そのプラットフォームの標準に従ってディレクトリ・パスを指定してください（つまり円記号（¥）のかわりに通常のスラッシュを使用）。

どちらの場合も、Reports Builderで有効なXMLレポート定義がオープンします。その後、Reports Builderの様々なビューを使用して、レポートが期待どおりに作成または変更されているかどうかを確認できます。

16.5.4 デバッグを目的とした、ファイルへのXMLの書込み

SRW.ADD_DEFINTIONを使用してXMLレポート定義をメモリー内に作成する場合は、XMLをファイルに書込むとデバッグに役立ちます。次の例は、各行をメモリー内のドキュメント・バッファおよび（ファイルへの書込みを選択した場合は）指定したファイルに書き込むプロシージャを示しています。

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;

この例が実際に機能するには、プロシージャをコールするPL/SQLでTEXT_IO.File_Typeタイプの変数を宣言する必要があります。次に例を示します。

custom_summary  Text_IO.File_Type;

また、書込み用のファイルをオープンし、addalineプロシージャをコールして、書き込む文字列と書込み先ファイルを渡す必要があります。次に例を示します。

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

16 XMLによるレポートのカスタマイズ