テンプレートビルダーでのフォント・マッピング (Font mapping on Template Builder)

テンプレート・ビルダーでのフォント・マッピングの方法が紹介されていました。
http://flexfields.blogspot.com/2010/12/how-to-configure-new-font-on-bi-desktop.html


手順は、構成ファイル xdo.cfg を作成するのみです。標準構成では、以下のディレクトリに xdo example.cfg が配置されていますので、コピーした上で名前を変更します。
C:\Program Files\Oracle\BI Publisher\BI Publisher Desktop\Template Builder for Word\config

フォントに関する設定部分を追加・編集します。
※なお、xdo example.cfg にはWindowsのシステムディレクトリが C:\WINNT と記載されています。コピー&ペーストする場合には留意してください。

以下の例では、Times New Roman と郵便バーコードフォントを設定しています。

   <!-- Font setting -->
    <fonts>
      <font family="Times New Roman" style="normal" weight="normal">
       <truetype path="C:\WINDOWS\Fonts\TIMES.ttf" /> 
      </font>


      <font family="yubinbcd" style="normal" weight="normal">
       <truetype path="C:\WINDOWS\Fonts\YUBINBCD.TTF" /> 
      </font>
    </fonts>

なお、xdo example.cfg にはテンポラリ領域として C:\Temp ディレクトリが定義されていますので、必要に応じて定義を編集するか、ディレクトリを作成してください。

その他、フォントマッピングについては過去の記事を参照して下さい。
PDF出力でのフォント・マッピング (Font Mapping)
11g でのフォント・マッピング (Font mapping on BI Publisher 11g)

---

[Summary]
Not only on the BI Publisher server, font mapping is also available on Template Builder.


Save the configuration file xdo.cfg.  You can copy xdo example.cfg to create the file.  Please see the example above for the font setting.  By default, these files are in:

C:\Program Files\Oracle\BI Publisher\BI Publisher Desktop\Template Builder for Word\config

Note: xdo example.cfg defines work area as C:/Temp.  You need to modify this setting, or create that directory to avoid runtime error.

ページ数のリセット (Resetting page number)

RTFテンプレートでセクションを分割した場合、セクション毎にページ番号をリセットしたいという要件があります。
または、月次のレポート出力において、ページ数を累積して出力したい（つまり、最初のページが１ではなく、たとえば30ページから開始する等）という要件も考えられます。

このような要件に対しては、initial-page-number を使用します。以下の例では、ページ番号は30ページから開始します。
<?initial-page-number:’30’?>

または、セクション区切りの後に以下のコードを埋め込むことで、ページは1から再開します。
<?initial-page-number:’1’?>

データフィールドの値を使用する場合は、以下の様に直接記載します。

<?initial-page-number:DEPTNO?>

詳細は以下のマニュアルを参照して下さい。
http://download.oracle.com/docs/cd/E14571_01/bi.1111/e13881/T421739T481157.htm#T481182


なお上記マニュアルによれば、この機能はPDFおよびPPT形式の出力でのみ、サポートされるようです。

---

[Summary]
initial-page-number resets, or setup the start number of the section.  If you want to start the report from 30, instead of 1, you set:
<?initial-page-number:’30’?>

If you simply want to reset the page number by the section, set '1' after the section break.

<?initial-page-number:’1’?>

To apply data field, write its name as follow:

<?initial-page-number:DEPTNO?>

For more details, please refer the manual:
http://download.oracle.com/docs/cd/E14571_01/bi.1111/e13881/T421739T481157.htm#T481182

MS-Wordでのページ設定 (Page setup on MS-Word)

BI Publisher はMS-Wordでのページ設定、セクション区切りもサポートしています。
セクションはそれぞれ異なるページ設定（用紙サイズ、用紙の向き、ヘッダ/フッタ）を行うことができます。これにより、レポート内で用紙サイズや向きを変更する要件にも、ある程度容易に対応できます。

以下の例では、最初の2枚のページと3ページ目以降でセクションを分割しています。最初のセクションはA4縦、2つ目のセクションはA3横の設定で、それぞれ異なるヘッダ定義です。

Figure 1: two sections

セクションの操作について、詳細はマイクロソフト社のサポートページを参照してください。
http://office.microsoft.com/ja-jp/word-help/CH006082987.aspx


上記のサンプルのテンプレートはここからダウンロードできます。

---

[Sumarry]
BI Publisher supports MS-Word page setting functions - header and footer, and sections.
You can specify the page setup (size, alignment, margine, header and footer, and so on) on each sections individually.  This feature will fill your customer's requirement much easier.
Figure 1 shows the result.  The first page and the second page are in section 1.  They are in A4 vertical page layout.  The third and the fourth page are in section 2.  This section is A3 horizontal.  Its header is differ from the section 1.


Please refer the Microsoft support site for more information.
http://office.microsoft.com/en-us/word-help/understanding-page-section-formatting-book-excerpt-HA001187601.aspx


You can get the rtf template from here.

ページによるヘッダ･フッタの切り替え (Switching the header / footer contents)

ヘッダとフッタをページに応じて切り替える、という要件は古くも新しい話題です。
US-OTNでも何度も話題に上がっていますが、そのほとんどにおいて最初のページと最後のページのヘッダおよびフッタの扱いが問題となっています。

BI Publisher ではヘッダおよびフッタ領域の区切りとして以下のタグを提供しています。
<?start:body?><?end body?>
<?start@last-page:body?><?end body?>
<?start@last-page-first:body?><?end body?>

しかし、これらだけでは、たとえば以下のような要件を満たすことはできません。

• 最初のページ、中間のページ、および最後のページでヘッダ･フッタを切り替える
• 内容が1ページに収まる場合には、最初のページのヘッダと最後のページのフッタを出力する

【具体例】
上記の要件の具体例を以下に示します。

先頭のページには文字列 First page header、および First page footer が出力されます。

Figure 1: page 1 of 3 (First page)

2番目の（中間の）ページには、文字列 Middle page header、および Middle page footer が出力されます。

Figure 2: page 2 of 3 (Middle page)

最後のページには文字列 Last page header、および Last page footer が表示されます。

Figure 3: page 3 of 3 (Last page)

また、このレポートが1ページに収まる場合の出力は以下の通りです。ヘッダには文字列 First page header を表示しつつ、フッタには Last page footer が出力されます。

Figure 4: Single page (The first page is the last page)

【xdofo:inline-total】
上記のような要件を満たすには、xdofo:inline-total オブジェクトを使用します。本来、このオブジェクトはページ間で数値の累計を受け渡す為のものですが、ヘッダおよびフッタの切り替えに使用することもできます。

xdofo:inline-total に定義されている表示条件(display-condition)は以下の通りです。

• first
• last
• exceptfirst
• exceptlast
• everytime (デフォルト)

マニュアルは以下のURLにて参照できます。
http://download.oracle.com/docs/cd/E14571_01/bi.1111/e13881/T421739T481157.htm


テンプレートをこちらに用意しました。

構文を以下に説明します。

以下の設定は、最初のページのみに現れるヘッダを定義しています。
<xdofo:inline-total display-condition="first" name="vDummy">
First page header
</xdofo:inline-total>


以下の設定は、中間のページのヘッダを定義しています。 exceptfirstとexceptlastをネストすることで、中間のみの出力を実現します。
<xdofo:inline-total display-condition="exceptfirst" name="vDummy">
<xdofo:inline-total display-condition="exceptlast" name="vDummy">
Middle page header
</xdofo:inline-total>
</xdofo:inline-total>


以下の設定は、最後のページのヘッダを定義しています。exceptfirstをネストして定義することで、レポートが1ページのみの場合に非表示になります。
<xdofo:inline-total display-condition="last" name="vDummy">
<xdofo:inline-total display-condition="exceptfirst" name="vDummy">
last page header
</xdofo:inline-total>
</xdofo:inline-total>

以下の設定は、最初のページのフッタを定義しています。exceptlastをネストして定義することで、レポートが1ページのみの場合に非表示になります。

<xdofo:inline-total display-condition="first" name="vDummy">

<xdofo:inline-total display-condition="exceptlast" name="vDummy">
First page footer
</xdofo:inline-total>
</xdofo:inline-total>

以下の設定は、最後のページのフッタを定義しています。レポートが1ページのみの場合、最初のページが最後のページにもなるため、表示されます。

<xdofo:inline-total display-condition="last" name="vDummy">
Last page footer
</xdofo:inline-total>


【制限事項】
xdofo:inline-totalはPDFのフォーマッティング時に実行されるため、PDF以外の出力では使用できません。また、テンプレートの呼び出しなどはフォーマッティング以前に完了される必要があるため、xdofo:inline-total内に記載することはできません。
フォーマッティング時に実行される fo:page-number 等のオブジェクトは使用できます。つまり、以下の記載は有効です。
<xdofo:inline-total display-condition="last" name="vDummy">

<fo:page-number()>

</xdofo:inline-total>

---

[Summary]
The example above shows how to switch the header and footer based on the page condition. In many cases, The first page becomes the last page (i.e. the report is one page only) raise a problem.


BI Publisher provides header/footer solutions such as <?start:body?>, but its function is not strong enough to fill the customer's requirement.


[Requirements]
Figure 1 through to Figure 4 shows the typical requirement.
If report has several pages, it shows different header / footer on the first, middle and the last page (Figure 1 to 3).
If report is only one page, it shows the first page header and the last page footer (Figure 4).


[xdofo:inline-total object]
To fill the requirement above, use xdofo:inline-total object. You can use it with the nested construct.
The sample rtf template is available here.


For the details, please refer the manual below:

http://download.oracle.com/docs/cd/E14571_01/bi.1111/e13881/T421739T481157.htm

[Restriction]
Since xdofo:inline-total is extracted in PDF formatting phase, other format - RTF, Excel etc - is not supported.
Things that need to be organized before the PDF formatting phase, such as calling template, cannot be included in xdofo:inline-total object.

テンプレート･ビルダーのアンインストール (Uninstall BI Publisher Template Builder)

BI Publisherのテンプレート･ビルダーのアンインストール（および再インストール）方法が以下のURLに紹介されています。
http://blogs.oracle.com/xmlpublisher/2009/04/template_builder_woes_1.html

日本語の解説がないので、以下に転記します。
1. コントロールパネルの「プログラムの追加と削除」から Oracle BI Publisher desktop をアンインストール
2. エクスプローラで C:\WINDOWS\assembly を開く
3. 上記のディレクトリに "TB" で始まるファイルがある場合、それらをすべて削除する
4. MS-Wordのスタートアップディレクトリを開き、ファイルが存在しないことを確認する
※標準構成では、C:\Documents and Settings\\application Data\Microsoft\Word\STARTUP

5. MS-Wordを開き、BI Publisher のツールバーが消えていることを確認する
ツールバーが消えていない場合、Normal.dot を再作成する

Normal.dotの再作成についてはマイクロソフトのサポートを参照して下さい。
http://support.microsoft.com/kb/881319/ja

再インストールに際しては、インストール端末のAdministrator権限のあるユーザでインストールすること、および以下の.Net Frameworkがインストールされていることを事前に確認してください。
- Shared Add-in Extensibility Update for Microsoft .NET Framework 2.0 (KB908002)
- Shared Add-in Support Update for Microsoft .NET Framework 2.0 (KB908002)

---

[Summary]
The following blog explains how to uninstall BI Publisher Template Builder (English).
http://blogs.oracle.com/xmlpublisher/2009/04/template_builder_woes_1.html

You may need to rebuild Normal.dot.  If you need to do that, following Microsoft support would help you:
http://support.microsoft.com/kb/822005

ページ番号 (Page number)

ページ番号の表示は以下のコードで表示します。
<?fo:page-number?>

これに、総ページ数を組み合わせて「1/10」の様に表示するには、 fo:page-number-citation を使用します。
<?fo:page-number?> / <?fo:page-number-citation:page-total?>

実行結果は以下の通りです。

Figure 1

fo:page-number-citation に関する詳細は以下のURLを参照して下さい。
http://www.w3schools.com/xslfo/obj_page-number-citation.asp

---

[Summary]
To show the current page number and the total number of the pages, use fo:page-number-citation object.

<?fo:page-number?> / <?fo:page-number-citation:page-total?>

The result is shown in Figure 1.

PDFセキュリティ (PDF security options)

BI PublisherのPDF出力オプションは「ランタイムオプション」で設定することができます。

Figure 1: Runtime property tab

【動的なオプション設定】
バースティングの際にファイル毎に個別の（異なる）パスワードを設定したい、という要件はほぼ確実に想定されます。このような場合には、上記の画面ではなく、テンプレートにて設定を行います。

以下のURLに方法が紹介されています。
http://blogs.oracle.com/xmlpublisher/2010/02/securing_burst_output_document.html


MS-Wordにて、ファイルのプロパティ画面を開きます。「ユーザ定義」タブを選択し、文書のプロパティにPDF出力オプションをあらわす文字列を埋め込みます。
以下の例では、PDFファイルのパスワードにempnoの値を設定します。

xdo-pdf-security:  true

xdo-pdf-open-password: {/ROWSET/ROW/EMPNO}

Figure 2: MS-Word property dialog

【オプションの一覧】
PDF出力オプションを以下に一覧します。

• xdo-pdf-security
• xdo-pdf-open-password
• xdo-pdf-permissions-password
• xdo-pdf-encryption-level
• xdo-pdf-no-changing-the-document
• xdo-pdf-no-printing
• xdo-pdf-no-accff
• xdo-pdf-no-cceda
• xdo-pdf-enable-accessibility
• xdo-pdf-enable-copying
• xdo-pdf-changes-allowed
• xdo-pdf-printing-allowed

これらのPDF出力オプションは以下のマニュアルに一覧されています。 http://download.oracle.com/docs/cd/E10383_01/doc/bip.1013/b40017/T421739T421745.htm#4419522

---

[Summary]
You can set PDF file options in Runtime Options tab (Figure1).


Runtime (dynamic) security setting
The setting above is static (fixed).
To achieve the requirement such as "set different password on each bursted PDF files", you need to set these security properties on the RTF template file.
To set file open password, define xdo-pdf-security and xdo-pdf-open-password on the file properties dialog (Figure 2).  In the example, the value of EMPNO is set for the password.
For details, please refer the following URL: (English)
http://blogs.oracle.com/xmlpublisher/2010/02/securing_burst_output_document.html


PDF Security options
The manual below helps you to find the property name.  Note that you need to add prefix "xdo-".

http://download.oracle.com/docs/cd/E10383_01/doc/bip.1013/b40017/T421739T421745.htm#4419522

小計と合計 (Subtotal and Grand total)

以下の出力結果の様に、グループ毎の小計と、総合計を表示します。

設定は以下の通りです。

以下の文で変数 vTotal を宣言し、初期値ゼロを設定します。
<?xdoxslt:set_variable($_XDOCTX,'vTotal',0)?>

以下の文で変数 vTotal に SAL の小計を合算します。この文がグループ毎に実行されることで、累計（総合計）が求められます。
<?xdoxslt:set_variable($_XDOCTX,'vTotal',xdoxslt:get_variable($_XDOCTX,'vTotal')+sum(current-group()/SAL))?>

総合計を表示します。
<?xdoxslt:get_variable($_XDOCTX,'vTotal')?>

【2011-11-15追記】
SQLで小計と合計を求める方法について、「SQLで小計と合計を取得する」を作成しました。併せて参照下さい。

---

[ Summary ]
To get subtotal and grand total, you need to define a variable. The example above shows the usage of set_variable and get_variable.


Declare the variable "vTotal":

<?xdoxslt:set_variable($_XDOCTX,'vTotal',0)?>

Sum up the subtotal into the variable "vTotal".  This code is executed in each group:

<?xdoxslt:set_variable($_XDOCTX,'vTotal',xdoxslt:get_variable($_XDOCTX,'vTotal')+sum(current-group()/SAL))?>

Show the grand total:

<?xdoxslt:get_variable($_XDOCTX,'vTotal')?>

[November, 15, 2011: append]

If you want SQL group by tips, please refer to SQL: Subtotal and Grand Total.

バースティング性能 その6(Performance of the bursting function part 6)

BI Publisher 11gでの性能検証は、結論から申しますと失敗しました。1万ファイルへのバースティングに30分近く要する状況です。
VMの構成、およびJRockitの設定の見直しを行っているものの、芳しくありません。

この問題については今後、成功･失敗を問わず、事象に動きがあった段階でこのブログ上で公開したいと思います。

---

[Summary]
Performance test of BI Publisher 11g had not got good result so far - it takes around 30 minutes to burst the data into 10,000 files.
I suspend further investigation on this issue for a while.

バースティング性能 その5(Performance of the bursting function part 5)

1ファイル1ページの出力を検証します。
残念ながら、BI Publisher 11g での検証は、VM上での検証が不調に終わったため、都合により、BI Publisher 10gでの検証結果を記載します。

【検証環境】

検証環境のBIサーバ構成を以下の通り変更します。

ゲストマシン2（BIEE）：
CPU: 4コア
Memory: 4GB
OS: Windows2003 Server, 32bit
BIEE: Oracle BIEE 10g

BI Publisher10gでは、マルチスレッド処理の設定を手動で行う必要があります。今回はコア数と同じ4スレッドでの実行を設定します。

Figure 1: Runtime property setting

【結果】
出力結果は以下の通りです。出力に3分以上かかる結果となってしまいました。

	所要時間（秒）	秒間出力ページ数
1回目	199.7	50.0
2回目	180.5	55.4
3回目	201.9	49.5
平均	194.0	51.7

平均で秒間約51ページの出力性能となりました。

【OS統計】
OS統計からは、ディスクおよびメモリに問題は見られません。
CPU使用率を確認すると、個々のコアの使用率が低く、かつ、断続的に落ち込んでいる状況が確認できます。

CPU:
バッチ処理としては、CPUリソースの能力を引き出せていません。全体で6割程度の使用率です。

Figure 2: CPU usage

メモリ:
メモリには余裕がある状態です。

Figure 3: Memory

ディスク:
ディスクアクセスにも問題はありません。

Figure 4: Disk time

【JVMのチューニング】
OS統計からは明確なボトルネック情報は得られませんが、CPUの動きからはGCが疑われます。
同時間帯のGCの様子を確認します。

Figure 5: Garbage Collection status (default setting)

Full GC （黒線）が多発しています。物理メモリにはまだ余裕がありますので、GCの間隔を広げるため、ヒープの絶対量を増やします。

最大サイズ(Xmx)を1GBに指定し、また、バッチ単体用途処理ですので、初期サイズ(Xms)も1GBに合わせます。併せて、パラレルGC (XX:+UseParallelGC)を設定します。参考まで、以下に追加･変更する設定を示します。
-Xmx1024M -Xms1024M -XX:+UseParallelGC

【再実行結果】

出力結果は以下の通りです。平均で約1分20秒、秒間約120ページの出力性能となりました。

	所要時間（秒）	秒間出力ページ数
1回目	82.3	121.5
2回目	82.3	121.5
3回目	84.0	118.9
平均	82.9	120.7

GCの頻度が低減し、スループット(下図のThroughput)も改善(79.32% → 95.93%)しています。これは、実行時間中にGCのためにJVMが停止した時間が大幅に減少したことを表しています。
今回はこれ以上のJVMの調査・チューニングは行いません。

Figure 6: Garbage Collection (Heap=1GB)

【OS統計】
CPU使用率が回復していることが確認できます。

CPU:

おおむね100%に近い使用率となっています。バッチ処理として、リソースの性能を引き出すことができています。

Figure 7: CPU usage

メモリ:
JVMにメモリを割り当てた分、空き容量は減少していますが問題はありません。

Figure 8: Memory

ディスク:
ディスクは余裕のある状態です。

Figure 9: Disk Time

1ファイルに1万ページをまとめて出力した場合のファイルサイズは19MBでしたが、1ページ1ファイル（本来のバースティング）の出力では、出力されるファイルの総サイズが458MB（1ファイルあたり46KB）に増加します。
PDFファイルを個別に出力する際のオーバーヘッドを勘案すると、ある程度妥当な性能と言えます。
これまで見てきたように、BI Publisher のバースティング機能はCPU性能に依存しますので、機器構成の検討の際にはインフラ担当者と密に連携し、性能検証を十分に実施することをお勧めします。

---

[Summary]
Now it's one page in each file.
Since BI Publisher 11g on my VM did not get good result, this time, I use BI Publisher 10g.  I may try 11g again in near future.


With BI Publisher 10g, you need to specify some parameters to implement multi thread bursting.  Figure 1 shows the setting.  Please refer the manual:
http://download.oracle.com/docs/cd/E10415_01/doc/bi.1013/e12187/T518230T522345.htm




[Result]
The result are as follows...  Not good.  It took three minutes over.

	Elapsed Time(sec)	pages / sec
1st	199.7	50.0
2nd	180.5	55.4
3rd	201.9	49.5
Average	194.0	51.7

[OS statistics]
OS statistics shows no bottleneck on memory nor disk (Figure 3 and 4).  You may see the CPU usage stays low (Figure 2).




[JVM Tuning]
BI Publisher runs on JVM, you should check the Garbage Collection behavior.  Figure 5 tells there had been too many Full GC.
The memory can afford more JVM heap.  Below is new setting:

-Xmx1024M -Xms1024M -XX:+UseParallelGC

[Result (with JVM heap size 1GB)]

It gets better.  The average is 120 pages per second.

	Elapsed Time(sec)	pages / sec
1st	82.3	121.5
2nd	82.3	121.5
3rd	84.0	118.9
Average	82.9	120.7

Figure 6 shows that the Full GC has been vanished.  You can see the Throughput in GC Viewer increased from 79.32% to 95.93%.  It means the pause time in JVM had been reduced a lot.

[OS statistics]

CPU usage gets higher.  It's around 98% (Figure 7).  This means BI Publisher uses the CPU resource effectively.

The memory and the disk stay calm (Figure 8 and 9).

The PDF file size is 46KB each, total 458MB (46KB * 10,000 files = 458MB).  In Part 1, the file size was 18.8MB.  The file size increased more than 20 times.

With consideration of the overheads (overhead when BI Publisher produces 10,000 individual PDF files), I accept this result.

The bursting function of BI Publisher is CPU-bound.  You should better to communicate with the infrastructure team to discuss the server spec.  The performance test should be done with them before they determine the spec, if possible.