WebQry Red Book

ibm.com/redbooks

Front cover

Getting Started with DB2 Web Query for i

Hernando BedoyaJackie Jansen

Gene CobbRobert Andrews

Linda SwanTyler Even

Follow the best practice guides to simplify report development

Take your reporting to the next level of Business Intelligence

Learn DB2 Web Query by using the easy-to-follow tutorials

http://www.redbooks.ibm.com/


International Technical Support Organization


February 2010

SG24-7214-01

© Copyright International Business Machines Corporation 2010. All rights reserved.Note to U.S. Government Users Restricted Rights -- Use, duplication or disclosure restricted by GSA ADP ScheduleContract with IBM Corp.

Second Edition (February 2010)

This edition applies to IBM i 6.1 (product number 5761-SS1).

Note: Before using this information and the product it supports, read the information in “Notices” on page ix.

Contents

Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ixTrademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .x

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiThe team who wrote this IBM Redbooks publication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiiBecome a published author . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xivComments welcome. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiv

Summary of changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xvFebruary 2010, Second Edition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xv

Part 1. Background, installation, and setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Chapter 1. Product architecture and overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.1 Query/400: a product history. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.2 Introduction to DB2 Web Query for i . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51.3 Synonyms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51.4 DB2 Web Query features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

1.4.1 Base features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61.4.2 Optional features available from IBM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71.4.3 Companion products available from IBM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

1.5 Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101.5.1 Web browser clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121.5.2 Web server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121.5.3 Application server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121.5.4 Reporting Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131.5.5 Data adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

1.6 DB2 Web Query Developer Workbench . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141.7 DB2 Web Query product positioning. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141.8 Request for changes on Web Query. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Chapter 2. Installation and server operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172.1 Installation and setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

2.1.1 Installing DB2 Web Query. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182.1.2 Authorizing and verifying users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192.1.3 License keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192.1.4 Dynamic Language Switch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202.1.5 Sample database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

2.2 Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202.2.1 PC requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202.2.2 System i requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212.2.3 Developer Workbench requirements. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

2.3 Web Query commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212.4 DB2 Web Query server jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Chapter 3. DB2 Web Query fundamentals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253.1 Types of DB2 Web Query users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263.2 Licensing DB2 Web Query users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

3.2.1 Comparing the licensing options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

© Copyright IBM Corp. 2010. All rights reserved. iii

3.3 Registering named users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293.3.1 Adding a new user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303.3.2 Removing a DB2 Web Query registered user. . . . . . . . . . . . . . . . . . . . . . . . . . . . 303.3.3 Displaying registered users. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

3.4 Logging in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303.5 Administrator tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

3.5.1 DB2 Web Query domains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333.5.2 Creating subfolders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353.5.3 Assigning authority to users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

3.6 Developer tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443.6.1 Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463.6.2 Setting up a cross-system join . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 743.6.3 Segmenting and securing Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

3.7 Basic user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

Part 2. Tutorials for DB2 Web Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

Chapter 4. Getting started with the tutorials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91Getting started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

Chapter 5. Report Assistant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 995.1 Tutorial overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1005.2 Report creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

5.2.1 Creating a summary report (RA1_Revenue). . . . . . . . . . . . . . . . . . . . . . . . . . . . 1015.2.2 Defining a report layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1015.2.3 Sum and detail reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1045.2.4 Date formatting (RA2_XTab). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1125.2.5 Selection criteria . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1135.2.6 Cross-tab report (RA2_XTab) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1155.2.7 Creating a sample detail report (RA3_GP) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1165.2.8 Conditional styling (traffic lighting) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1215.2.9 Using variables in report headings and footings . . . . . . . . . . . . . . . . . . . . . . . . . 1245.2.10 Generating subtotals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1265.2.11 Sorting by an aggregate field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1285.2.12 Adding ranking columns (RA4_Advanced) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

5.3 Output options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1305.3.1 On demand paging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1315.3.2 PDF output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1325.3.3 Excel output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1335.3.4 DB2 database file output. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

5.4 Additional report types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1365.4.1 Parameterized reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1375.4.2 Drill-down reports: Parent report (RA5_Child) . . . . . . . . . . . . . . . . . . . . . . . . . . 1415.4.3 Report properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144

5.5 Joining tables (reference only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1445.6 Creating a report over a stored procedure synonym. . . . . . . . . . . . . . . . . . . . . . . . . . 1475.7 Report Assistant summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152

Chapter 6. Graph Assistant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1536.1 Tutorial overview: bar chart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1546.2 Creating a simple bar chart with drill-down capabilities (GA1_Bar) . . . . . . . . . . . . . . 156

6.2.1 Adding multiple bars to one chart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1586.2.2 Adding a drill down to a chart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160

6.3 Creating a dual axis bar and line chart (GA2_Parm) . . . . . . . . . . . . . . . . . . . . . . . . . 162

iv Getting Started with DB2 Web Query for i

6.3.1 Adding a second Y axis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1656.4 Creating a revenue trend over time chart (GA3_Line) . . . . . . . . . . . . . . . . . . . . . . . . 1706.5 Creating a line graph. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171

6.5.1 Adding a date range filter to a line graph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1786.5.2 Adding a user-specified date range parameter . . . . . . . . . . . . . . . . . . . . . . . . . . 182

6.6 Working with pie charts (GA4_Pie) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1856.7 Creating a product type pie chart for each year . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1856.8 Conditional styling or traffic lighting a graph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191

Chapter 7. Power Painter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1997.1 Tutorial overview (PP1_PDF) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2007.2 Launching Power Painter and tailoring the main window . . . . . . . . . . . . . . . . . . . . . . 2007.3 Building a graph with Power Painter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2047.4 Building a report with Power Painter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2127.5 Adding an image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2227.6 Building a gauge chart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224

Part 3. Tutorials for DB2 Web Query optional features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231

Chapter 8. Active Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2338.1 Overview and highlights of Active Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2348.2 Creating a report with Active Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2358.3 Using an Active Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2398.4 Summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251

Chapter 9. Developer Workbench . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2539.1 Configuring Developer Workbench . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2549.2 Setting Developer Workbench default options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258

Chapter 10. Online analytical processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26110.1 OLAP terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26210.2 Defining OLAP metadata using Developer Workbench . . . . . . . . . . . . . . . . . . . . . . 26210.3 Enabling an OLAP report (OL1_Revenue) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27010.4 Working with an OLAP-enabled report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272

10.4.1 Slicing, dicing, and drilling down for more details . . . . . . . . . . . . . . . . . . . . . . . 27310.4.2 Manipulating the data using the OLAP Control Panel. . . . . . . . . . . . . . . . . . . . 28510.4.3 Grouping data into percentiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293

Chapter 11. HTML Composer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29511.1 Compound parameterized report (HTML1_KPI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296

11.1.1 Adding parameters to existing reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29611.1.2 Designing the layout for the HTML report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302

11.2 Highly parameterized report (HTML2_Parm) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31111.2.1 Creating the report in HTML Composer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31511.2.2 Additional parameter tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334

Chapter 12. Additional features of Developer Workbench . . . . . . . . . . . . . . . . . . . . . 35112.1 Synonym Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352

12.1.1 Date Decomposition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35612.1.2 Additional date manipulation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35812.1.3 Creating filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36012.1.4 Joining tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36412.1.5 Business View. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37112.1.6 Impact Analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37312.1.7 Data profiling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376

Contents v

12.2 SQL Wizard. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37912.3 Summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384

Chapter 13. DB2 Web Query Spreadsheet Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38713.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38813.2 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38813.3 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389

13.3.1 Report Assistant mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38913.3.2 Structured Ad-hoc Form mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390

13.4 Dashboards in Excel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39113.5 Data range properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39213.6 Spreadsheet Client Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393

Chapter 14. Adapter for Microsoft SQL Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39514.1 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39614.2 Establishing a connection to your MS SQL Server . . . . . . . . . . . . . . . . . . . . . . . . . . 39614.3 Creating Metadata. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39914.4 Additional SQL Server Adapter information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402

Part 4. Companion products . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403

Chapter 15. Report Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40515.1 Tutorial overview and preparation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40715.2 Installing and Configuring Report Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40715.3 Schedule an existing report. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41115.4 Scheduling Frequency options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41615.5 Creating a Report Broker distribution list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41815.6 Busting a report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42015.7 Viewing the Distribution log. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42315.8 Report Broker and highly parametrized reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42415.9 Report Broker Administrator functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42515.10 Report Broker and Active Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42815.11 Report Broker and runtime user enablement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42915.12 Event-driven distribution request via RUNBRSCHED. . . . . . . . . . . . . . . . . . . . . . . 42915.13 Report Broker summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429

Chapter 16. Software Development Kit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43116.1 Overview of the Software Development Kit (SDK) . . . . . . . . . . . . . . . . . . . . . . . . . . 43216.2 Uses of the Web Query SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43216.3 Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43316.4 Web services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433

16.4.1 Core APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43316.4.2 Report Broker APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43416.4.3 Sample code path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43416.4.4 Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435

Part 5. Miscellaneous and additional topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439

Chapter 17. Using DB2 Web Query to run existing Query/400 reports . . . . . . . . . . . 44117.1 Query/400: a reliable reporting tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44217.2 DB2 Web Query versus Query/400: function similarities . . . . . . . . . . . . . . . . . . . . . 44217.3 DB2 Web Query versus Query/400: function differences . . . . . . . . . . . . . . . . . . . . . 443

17.3.1 Parameter passing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44317.3.2 Using output files for the next query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443

17.4 Creating metadata from Query/400 objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444

vi Getting Started with DB2 Web Query for i

17.5 Using DB2 Web Query to edit a QRYDFN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448

Chapter 18. Performance considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44918.1 Performance basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45018.2 DB2 CLI adapter performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450

18.2.1 Report request process flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45018.2.2 Adapter processing and optimization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45218.2.3 Remote database access considerations (including cross-system joining) . . . 462

18.3 Query/400 adapter performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46418.4 DB2 for i optimization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465

18.4.1 Database design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46518.4.2 Query Engine used . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46618.4.3 Indexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47518.4.4 Available hardware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47618.4.5 Concurrent users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 479

18.5 Performance case study . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48018.5.1 Identifying a long-running report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48018.5.2 Performing analysis and looking for optimization disablers . . . . . . . . . . . . . . . 48118.5.3 Determining report-tuning options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48218.5.4 Creating an SQL view and synonym. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48318.5.5 Creating a new report based on the SQL view . . . . . . . . . . . . . . . . . . . . . . . . . 48418.5.6 Performing additional database analysis and tuning. . . . . . . . . . . . . . . . . . . . . 486

18.6 Performance benchmark. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48818.6.1 Objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48818.6.2 Scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48818.6.3 Database and system configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48918.6.4 Metrics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48918.6.5 Conclusions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 492

Chapter 19. Frequently asked questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49519.1 General announcement or product information questions . . . . . . . . . . . . . . . . . . . . 49619.2 Installation and setup questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50019.3 Security-related questions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50119.4 Named-user question . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50219.5 Metadata questions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50219.6 Query/400 migration questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50619.7 Report development questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50719.8 Excel spreadsheet integration questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51619.9 Add-on product questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51819.10 Save and restore questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52219.11 Education questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 524

Part 6. Appendixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 525

Appendix A. Metadata in the integrated file system . . . . . . . . . . . . . . . . . . . . . . . . . . 527

Appendix B. Date and time functionality . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 529Date and time system variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 530Date format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 530Date format display options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 531Controlling the date separator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 532Using date fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 533Date fields in arithmetic expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 533Converting date fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 533

Contents vii

Changing the usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 534Using DB2 Web Query functions to convert to dates . . . . . . . . . . . . . . . . . . . . . . . . . . 537Using date conversion table to convert to dates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 542Using SQL Views and functions to convert to dates . . . . . . . . . . . . . . . . . . . . . . . . . . . 564Comparing the date conversion techniques . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 567Converting date fields in Oracle’s JD Edwards World application . . . . . . . . . . . . . . . . 568Converting other common legacy date formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 571

DB2 Web Query date built-in functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 572DATEADD: adding or subtracting a date unit to or from a date . . . . . . . . . . . . . . . . . . 572DATEDIFF: calculating the difference between two dates . . . . . . . . . . . . . . . . . . . . . . 572DATEMOV: moving the date to a significant point . . . . . . . . . . . . . . . . . . . . . . . . . . . . 573

Example: Dynamic Date Range report. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 574

Appendix C. Processing differences between the define and compute fields . . . . . 579

Appendix D. Change Management considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . 581Developer Workbench . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 582Without Developer Workbench . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 582

Appendix E. Additional material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 585Locating the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 585Using the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 585

System requirements for downloading the Web material . . . . . . . . . . . . . . . . . . . . . . . 585How to use the Web material . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 586

Related publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 587IBM Redbooks publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 587Online resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 587How to get IBM Redbooks publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 587Help from IBM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 588

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 589

viii Getting Started with DB2 Web Query for i

Notices

This information was developed for products and services offered in the U.S.A.

IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to: IBM Director of Licensing, IBM Corporation, North Castle Drive, Armonk, NY 10504-1785 U.S.A.

The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.

This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice.

Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk.

IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you.

Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products.

This information contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental.

COPYRIGHT LICENSE:

This information contains sample application programs in source language, which illustrate programming techniques on various operating platforms. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the application programming interface for the operating platform for which the sample programs are written. These examples have not been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these programs.

© Copyright IBM Corp. 2010. All rights reserved. ix

Trademarks

IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of International Business Machines Corporation in the United States, other countries, or both. These and other IBM trademarked terms are marked on their first occurrence in this information with the appropriate symbol (® or ™), indicating US registered or common law trademarks owned by IBM at the time this information was published. Such trademarks may also be registered or common law trademarks in other countries. A current list of IBM trademarks is available on the Web at http://www.ibm.com/legal/copytrade.shtml

The following terms are trademarks of the International Business Machines Corporation in the United States, other countries, or both:

AS/400®DB2®developerWorks®Domino®i5/OS®IBM®

iSeries®Lotus®OmniFind®Rational®Redbooks®Redpaper™

Redpapers™Redbooks (logo) ®System i5®System i®WebSphere®

The following terms are trademarks of other companies:

Adobe, PostScript, the Adobe logo, and the PostScript logo are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States, and/or other countries.

Acrobat, Adobe Reader, Adobe, PostScript, and Portable Document Format (PDF) are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States, other countries, or both.

Oracle, JD Edwards, PeopleSoft, Siebel, and TopLink are registered trademarks of Oracle Corporation and/or its affiliates.

Java, and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.

Microsoft, Windows, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both.

Pentium, Intel logo, Intel Inside logo, and Intel Centrino logo are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries.

UNIX is a registered trademark of The Open Group in the United States and other countries.

Other company, product, or service names may be trademarks or service marks of others.

x Getting Started with DB2 Web Query for i

http://www.ibm.com/legal/copytrade.shtml

Preface

The DB2® Web Query for i product is a Web-based query and report writing product that offers enhanced capabilities over the IBM® Query for iSeries® product (also commonly known as Query/400). IBM DB2 Web Query for i includes Query for iSeries technology to assist customers in their transition to DB2 Web Query. It offers a more modernized, Java™-based solution for a more robust, extensible, and productive reporting solution. DB2 Web Query provides three main components: Report Assistant, Graph Assistant, and Power Painter with the base product. Using these tools, customers can modernize existing Query for iSeries reports while providing a foundation for building more complex business intelligence applications, such as online analytical processing (OLAP), data mining, dash boarding, or data warehouse implementations.

DB2 Web Query provides capabilities to query or build reports against data that is stored in DB2 call-level interface (CLI) databases through the latest browser-based user interface technologies. It enables you to build new reports with ease through the Power Painter or Report Assistant and Graph Assistant components. It simplifies the management of reports by allowing you to leverage parameterized reporting. It delivers data to users in many different formats, including spreadsheets, PDF, HTML, or through browser support of the Java-based thin client interface.

DB2 Web Query offers features to import Query/400 definitions and enhance their look and functionality with Power Painter or Graph Assistant. It enables you to add OLAP-like slicing and dicing to the reports or to view reports in disconnected mode for users on the go. It provides an interface to all data in IBM i5/OS® through either DB2 or Open Query File native adapters that automatically identify the files to be accessed and import the metadata into DB2 Web Query.

This IBM Redbooks® publication provides a broad understanding of the new DB2 Web Query product. It entails a group of self-explanatory tutorials to help you get up to speed quickly. Overall, this book is designed for IT users. You can use Part 2, “Tutorials for DB2 Web Query” on page 89, and Part 3, “Tutorials for DB2 Web Query optional features” on page 231, as stand-alone tutorials for anyone who is developing their own queries. Much of Chapter 8, “Active Reports” on page 233, is appropriate for those who work disconnected from the System i® environment. In addition, you can use much of Chapter 10, “Online analytical processing” on page 261, if you will simply be running OLAP-enabled reports.

© Copyright IBM Corp. 2010. All rights reserved. xi

The team who wrote this IBM Redbooks publication

This book was produced by a team of specialists from around the world working at the International Technical Support Organization (ITSO), Poughkeepsie Center.

Hernando Bedoya is a Senior IT Specialist at STG Lab Services and Training in Rochester, Minnesota. He writes extensively and teaches IBM classes worldwide in all areas of DB2 for i. Before joining STG Lab Services he worked in the ITSO for nine years writing multiple IBM Redbooks publications. He also worked for IBM Colombia as an IBM AS/400® IT Specialist doing presales support for the Andean countries. He has 25 years of experience in the computing field and has taught database classes in Colombian universities. He holds a master’s degree in computer science from EAFIT, Colombia. His areas of expertise are database technology, performance, and data warehousing. Hernando can be contacted at [email protected].

Jackie Jansen is the IBM i Solutions Manager for Information Builders specializing in DB2 Web Query. Jackie is the author of a variety of published columns including “Business Intelligence with Jackie” and “Jackie's Forum”. Jackie is a frequent speaker at technical conferences and user group meetings. Contact her at [email protected].

Gene Cobb is a DB2 for i Technology Specialist in the IBM Systems Software DB2 for i Development team. He joined IBM in 1988 and spent over 10 years as an application consultant in the IBM STG Lab Services group, formerly the Client Technology Center (CTC) in Rochester, Minnesota. His current responsibilities include the promotion, education, enablement, and technical support of IBM DB2 Web Query, the strategic query and reporting solution for the IBM i platform. He speaks and writes regularly about DB2 for i and DB2 Web Query topics and is a co-author of the IBM Redbooks publication Getting Started with DB2 Web Query for IBM i. He can be reached at [email protected].

Robert Andrews is an Advisory Software Engineer working for the STG Lab Services team in the DB2 for i Center of Excellence. He was the technical head for support for the DB2 Web Query product and currently provides custom consulting services helping clients make the most of DB2 Web Query and DB2 for i. Since joining IBM in 2001, Robert has co-authored many IBM Redbooks publications and his work has been published in trade publications with a focus on SQL, journaling, and communications. Robert can be reached at [email protected].

xii Getting Started with DB2 Web Query for i

Linda Swan is a Software Developer on the DB2 for i Query Optimization component. In addition, she has spent the past year working with DB2 Web Query for IBM i. Her current responsibilities include SQE query engine optimization technique and performance on IBM i. She can be reached at [email protected].

Tyler Even is a DB2 for i5/OS Technology Specialist in STG Lab Services System i group. He currently assists customers with application/database design and development using DB2 Web Query for IBM i, DB2 for IBM i, Java/VB, WebSphere®, and Lotus® Domino®. His current responsibilities include providing consulting services to IBM i customers with a special emphasis in DB2 Web Query for IBM i and Business Intelligence practices for IBM i. He can be reached at [email protected].

Thanks to the authors of the first edition, Getting Started with DB2 Web Query for i, published in November 2007:

Renee MasonJackie JansenGene Cobb

Thanks to the following people for their contributions to this project:

Thomas GrayJames HansenJoanna Pohl-MiszczykJenifer ServaisITSO, Poughkeepsie Center

Robert AndrewsMichael CainFernando EchevesteTyler EvenDoug MackJarek MiszczykScott MooreBrian MurasChuck PenceSandy RyanRick SaltnessDan ToftEric WillIBM Rochester

Wilfried BlankertzIBM Germany

Preface xiii

Julie MawIBM UK

Simona PacchiariniFrancesca ZocchedduIBM Italy

Larry EissRobert FricanoGary GoldbergPat PowersTerry SchwarzInformation Builders Inc.

Eric J. SongyEJS IT Consulting

Rosemarie PembletonUnique Industries

Become a published author

Join us for a two- to six-week residency program! Help write an IBM Redbooks publication dealing with specific products or solutions, while getting hands-on experience with leading-edge technologies. You will have the opportunity to team with IBM technical professionals, Business Partners, and Clients.

Your efforts will help increase product acceptance and customer satisfaction. As a bonus, you will develop a network of contacts in IBM development labs, and increase your productivity and marketability.

Find out more about the residency program, browse the residency index, and apply online at:

ibm.com/redbooks/residencies.html

Comments welcome

Your comments are important to us!

We want our Redbooks publications to be as helpful as possible. Send us your comments about this book or other Redbooks publications in one of the following ways:

� Use the online Contact us review Redbooks publications form found at:

ibm.com/redbooks

� Send your comments in an e-mail to:

[email protected]

� Mail your comments to:

IBM Corporation, International Technical Support OrganizationDept. HYTD Mail Station P0992455 South RoadPoughkeepsie, NY 12601-5400

xiv Getting Started with DB2 Web Query for i

http://www.redbooks.ibm.com/residencies.html

http://www.redbooks.ibm.com/residencies.html



http://www.redbooks.ibm.com/contacts.html

Summary of changes

This section describes the technical changes made in this edition of the book and in previous editions. This edition may also include minor corrections and editorial changes that are not identified.

Summary of Changesfor SG24-7214-01for Getting Started with DB2 Web Query for ias created or updated on February 2, 2010.

February 2010, Second Edition

This revision reflects the addition, deletion, or modification of new and changed information described below.

New information� Spread Sheet Client� Report Broker� Adapter for Microsoft® SQL Server� Software Development Kit

Changed information� Updated information to latest release of products� More examples have been added

© Copyright IBM Corp. 2010. All rights reserved. xv

xvi Getting Started with DB2 Web Query for i

Part 1 Background, installation, and setup

In this part, we introduce DB2 Web Query and provide guidance on how to install it. We also introduce and provide background information about IBM DB2 Web Query for System i, along with installation and setup instructions for the product.

This part includes the following chapters:

� Chapter 1, “Product architecture and overview” on page 3� Chapter 2, “Installation and server operations” on page 17� Chapter 3, “DB2 Web Query fundamentals” on page 25

Part 1

© Copyright IBM Corp. 2010. All rights reserved. 1

2 Getting Started with DB2 Web Query for i

Chapter 1. Product architecture and overview

Today’s information overload requires companies to analyze data quickly and easily in formats that suit the needs of different types of users. Executives want quick access to track key performance indicators. Financial analysts want to analyze corporate performance to evaluate profitability or meet compliance guidelines. Business managers require up-to-the-minute sales and inventory information to ensure that customer demand and sales quotas can be met. The information must be delivered quickly and easily, with robust security in place, and distributed to a multitude of different client technologies, including browsers and spreadsheets, or integrated into line-of-business (LOB) applications.

In this chapter, we introduce IBM DB2 Web Query for i (DB2 Web Query). This comprehensive Java-based business intelligence tool provides graphical, Web-based query and report-writing functions.

We include the following key topics in this chapter:

� A history of the Query/400 product including its current limitations� An overview of DB2 Web Query including how it addresses the limitations of Query/400� DB2 Web Query architecture� DB2 Web Query product positioning

1


1.1 Query/400: a product history

When the AS/400 was first released in June 1988, one of the optional licensed programs was the Query/400 product, 5722-QU1. This product was used by midrange programmers, administrators, and users to retrieve, format, and analyze information from AS/400 database files to produce reports. The tool was widely popular within the AS/400 community due to its compact design, intuitive interface, and robust functionality. Users created custom reports by specifying the files, record selection criteria, fields to sort and group by, and column totals from a limited number of simple panels. The reports could be written directly to a panel, to a spooled file for printing, or to another database file for further processing. Then the definition could be saved to a permanent AS/400 system object (object type *QRYDFN) so that the report could be shared with other users and run again later. With a proper knowledge of the database, reports could be generated in minutes.

The licensed program has since been renamed IBM Query for System i and is still available, supported, and widely used on the System i platform today. However useful Query/400 has been to users in the past, it has several major shortcomings:

� Lack of a graphical interface

Recently, significant emphasis was given to modernize System i applications. This refers to providing a more modern (graphical) interface for tools, applications, and any generated output. Many reporting tools available today have a Web browser or rich client-based interface. They also provide the ability to generate the reports in a variety of graphical formats such as PDF, HTML, XML, and Microsoft Excel spreadsheets. Query/400 does not support any of these interfaces.

� Lack of support for non-DB2 for i5/OS databases

Query/400 can only access information that is stored in DB2 for i5/OS. If you require your Query/400 reports to include information from other databases, such as Oracle or SQL Server, then you must import these tables into DB2 for i5/OS. This method is simply not practical if you have large amounts of data that is dynamic in nature.

� Limited ability to view the data in a different way or further dissect the data and drill down

Once run, the Query/400 output is static in nature and cannot be easily manipulated for further dissection and analysis. If you want to look at the data in a different way, such as to re-sort the list by a different column, you must create and run additional reports. Furthermore, the ability to select a particular element in the report and drill down for more information and analysis simply does not exist. Again you would have to run another report to obtain this information. All this results in analysis that is disruptive, lacks flow and fluidity, and is time consuming in nature. It also places a strain on an IT department that is continually writing various versions of reports to satisfy user requirements.

� Not a pure SQL interface

Query/400 is a proprietary interface and does not use the industry standard Structured Query Language (SQL) when accessing database objects. This limitation places restrictions on the functionality of the reports that can be created. New SQL functions and features that are introduced with each release cannot be directly or easily incorporated into Query/400 reports.

� Not strategic

IBM has clearly stated that SQL is the strategic database interface for both creating and accessing database objects. Since Query/400 is not an SQL interface, IBM will not invest in this technology in the future, and therefore the product will not address any of the previously listed deficiencies.


� Does not use the new SQL Query Engine (SQE)

SQE was introduced in V5R2 of i5/OS and offers algorithms and features that give it distinct advantages over its predecessor, the Classic Query Engine (CQE). SQE is the strategic database engine. Thus, it will receive all future enhancements. Although CQE will still be supported and maintained, IBM will not incorporate any new features into this engine. Only pure SQL requests are processed by the new engine. Because Query/400 is not an SQL interface, its query requests must be handled by the older CQE technology.

For more information about SQE including its advantages over CQE, see the Preparing for and Tuning the SQL Query Engine on DB2 for i5/OS, SG24-6598.

Over the years, thousands or perhaps millions of custom reports have been created using IBM Query for System i (also known as Query/400). As a result, businesses have a significant amount of investment contained throughout their systems in the query objects. Because so much has been invested in these objects, System i businesses require a way to leverage or repurpose them using a more modern reporting tool.

1.2 Introduction to DB2 Web Query for i

In April 2007, IBM and Information Builders Incorporated announced a product alliance. The new product, called IBM DB2 Web Query for i (DB2 Web Query), is the IBM strategic replacement product for Query/400. Like Query/400, it provides reporting capabilities against DB2 for i5/OS data. It also offers features that address the Query/400 limitations; it includes a graphical interface, modernized report formats, SQL access methods, and more. It can also run existing Query/400 reports, thus protecting the company’s valuable investment in those system objects.

The DB2 Web Query product is available from IBM under licensed program 5733-QU2. Customers who have a license for Query/400, 5722-QU1, and are current on their software maintenance, are automatically entitled to the base license for 5733-QU2. Customers will be provided with a license for a limited number of named users based on software tier, unlike Query/400, which was licensed for unlimited users.

As the Web Query family progresses, new features are being released. Some of these features came out in release R110 while others were first introduced in release R111. Furthermore, other features have been made available via PTFs to R111. In this book we cover several of these new features. However, all the core technologies are there in R110 and much of this book applies. In order to make sure that you have Web Query at a level at which you can get all of the features mentioned in this book, make sure that you have R111 of Web Query with at least Group PTF Level 4.

1.3 Synonyms

DB2 Web Query employs a data description language (DDL) that describes the necessary data elements for many types of data sources, including relational structures. Using this language, DB2 Web Query can describe i5/OS tables (physical files) or views (logical files) that have been established within the relational database system on the System i platform.

Query/400 and DB2 Web Query: In an attempt to reduce the naming ambiguity, throughout this book the product Query for System i will be referred to as Query/400 and the new product IBM DB2 Web Query for i will be referred to as DB2 Web Query.

Chapter 1. Product architecture and overview 5

This view of the data is a layer of abstraction that is used by DB2 Web Query for reporting and is known as synonyms or metadata. You can learn more about metadata in “Creating metadata” on page 48.

1.4 DB2 Web Query features

Licensed program 5733-QU2 has a base product and additional product components. We discuss the features that are supported by each of these options in the following sections.

1.4.1 Base features

In the following list, we highlight some of the main features of DB2 Web Query that are available with the base product of 5733-QU2:

� Browser-based interface

A Web browser is the interface for both DB2 Web Query developers and those users who will run the reports. This interface provides a graphical environment without the requirement of installing additional desktop software or plug-ins on user PCs.

� Query/400 report modernization

DB2 Web Query provides built-in adapters to import existing *QRYDFN objects without requiring any changes to those objects. After the appropriate metadata is created from the import process, the queries can be invoked from a browser interface and results displayed to the browser. This provides a modernized interface for running both existing queries and the report output.

� Report Assistant: Web-based query and reporting of data stored in DB2 for i5/OS

Included in DB2 Web Query is a component known as Report Assistant. This HTML-based graphical tool allows you to create new queries or modify existing ones, including imported Query/400 queries. You can select a data source, specify any sorting or grouping information, and display the report in your browser or another desktop application. When you use Report Assistant, DB2 Web Query creates a styled report that you can deploy on the Web without the necessity of learning the complexities of any reporting language.

� Delivery of output content in various modernized formats for Web browsers and wireless devices

By default, DB2 Web Query generates HTML and displays the query results to the browser. However, you can optionally specify other output formats. The more commonly used formats available are:

– Excel (97 and 2000)– PDF– XML– PostScript®

In addition, you can direct your DB2 Web Query report output to the traditional spooled file and database file formats.

� Graph Assistant: easy report graph generation

Graph Assistant is an HTML-based tool that guides you step-by-step through the creation of a graph. The Graph Assistant enables you to create and style your graphs.

Metadata and synonyms: The terms metadata and synonyms are used interchangeably throughout this book. They both refer to the DB2 Web Query data abstraction layer.


� Power Painter: What You See Is What You Get (WYSIWYG) report building

Power Painter is a Web layout and report creation tool that is built by using Asynchronous JavaScript and XML (AJAX) technology. This tool enables you to create output and page layout formats. It combines reporting, graphs, and page layout design in a single tool. The framework makes Power Painter a thin-client tool that looks, responds, and performs like a Microsoft Windows®-based facility.

� Data adapters

Data adapters manage the communication between DB2 Web Query and the DB2 for i5/OS database through the use of SQL statements or other data-access methods. Three adapters are provided with the base product:

– DB2 CLI– DB2 Heritage files– Query/400

For more information about each of these adapters refer to 1.5.5, “Data adapters” on page 13.

� Runs natively on the System i platform

Each server side component of the DB2 Web Query solution runs natively on the System i platform. This integrated environment equates to a more simplified environment. There are fewer servers and operating systems to set up, administer, secure, backup, and maintain.

� Ability to use matrix reporting, ranking, color coding, drill-down, and font customization to enhance the visualization of DB2 data

� Federated DB2 for i5/OS data access

Customers with multiple System i machines or i5/OS partitions will value the federated query capabilities of DB2 Web Query. This feature provides the ability to develop a single report against multiple DB2 for i5/OS databases.

For more information about the base component of 5733-QU2 see 2.1, “Installation and setup” on page 18.

1.4.2 Optional features available from IBM

In addition to the base product, optional features (also known as add-ons) are available to enhance the product’s functionality. Add-ons are available from IBM for an additional charge. The following features are included in the list of add-ons:

� Enablement of existing reports to use Online Analytical Processing (OLAP) or multi-dimensional functionality

The DB2 Web Query OLAP module allows slicing and dicing of data in an almost unlimited number of ways. This satisfies a broad range of analytical needs, enhances reports with extensive data-analysis functionality, and gives users the ability to dynamically interact with the data. OLAP enablement of a report allows users to drill down to finer levels of detail. Users can interact with their data, pivot rows and columns, visualize their numeric fields, and much more.

� Developer Workbench: rich client for building customized business intelligence applications

DB2 Web Query Developer Workbench is an add-on component that provides a rich client development environment.


While you do not need Developer Workbench to create DB2 Web Query reports, there are compelling reasons to consider using it as your report development tool. The following list includes reasons to consider such an upgrade:

– Dimension tool

• Defines hierarchies to be stored in the metadata• Is a prerequisite for OLAP module

– Interface to easily manipulate metadata and customize synonyms

• Includes meaningful field names• Includes multilingual titles

– SQL Wizard that allows the developer to type or copy and paste SQL statements directly into the tool

– HTML Composer tool

The powerful HTM Layout Painter tool allows you to combine reports, graphs, and other elements together in a single HTML document or layout. It provides a WYSIWYG design environment to help you create professional-looking layouts that require more advanced components such as custom HTML, HTML template files, and cascading style sheets (CSS).

– Advanced programmer tools including:

• Data profiling• Impact analysis• Ability to change field types (including integer or alpha to recognized date fields)• Automatic date decomposition

� Active Reports: offline reporting capability

Many mobile workers require access to important information that is stored in their analytic reports while disconnected from the Internet. With DB2 Web Query Active Reports, such users can take the power of business intelligence with them wherever they go. By combining data and interactive controls into a single, self-contained HTML file, Active Reports delivers analytic capabilities in a completely portable and disconnected environment, with absolutely no software required. For more information about Active Reports refer to Chapter 8, “Active Reports” on page 233, and the following Web address:

http://www.informationbuilders.com/products/webfocus/portable_analytics.html

� Additional named user licenses

If you need more named users than the base option provides or you need more than you are currently licensed for, you can purchase additional licenses. For more details, contact your IBM representative.

� Run Time User Enablement

For environments that have a large number of report consumers, compared to report authors, the standard named user licensing model may put Web Query out of reach. To help with this, we have developed a second licensing model. This model allows for essentially an unlimited number of report consumers.

For complete details on this offering review the White Paper at:

http://www-03.ibm.com/systems/resources/systems_i_software_db2_pdf_DB2_Web_Query_Run_Time_User_Enablement.pdf

� Spreadsheet Client

While the base product has the ability to generate Microsoft Excel spreadsheets, it still requires the users to go into the Web Query product to generate the output. With this additional feature, users simply access the power of Web Query from within Excel. There


http://www.informationbuilders.com/products/webfocus/portable_analytics.html

http://www-03.ibm.com/systems/resources/systems_i_software_db2_pdf_DB2_Web_Query_Run_Time_User_Enablement.pdf

is no need to go to the Web browser. While in Excel, two modes of operation are possible. If you are a report author, you can access Report Assistant within Excel to allow for the creation of reports that are put into your spreadsheet.

If you are simply a report consumer, you can use the Structured Ad-hoc Forms (SAF) method. This provides the user with an HTML page, like an HTML Launch Page, to pass parameters into the report. The output is then placed inside the spreadsheet.

Within a single spreadsheet, you can have multiple reports saved. By saving the report definition, this allows the reports to be refreshed and sent to other users. This, along with the powerful template capabilities of Excel 2007, allow for the creation of dashboards in Excel. With the reports created, they can be set to even automatically update the data on a set schedule.

� Adapter for Microsoft SQL Server

While most of your data should be stored on the IBM i, we do realize that some applications require data to be stored in a Microsoft SQL Server 2000 or 2005. Just because the data is outside of the System i does not mean that it is out of reach of Web Query. With this additional feature, DB2 Web Query can integrate data stored on Microsoft SQL Server. Reports can be based solely on SQL Server data or mixed in and joined to data on your System i. Why learn two different reporting tools when Web Query can use that remote data source in an environment that you will be very familiar with by the end of this book?

1.4.3 Companion products available from IBM

In addition to the base product and its option features, IBM also offers two companion products to DB2 Web Query (5733-QU2):

� Report Broker (5733-QU3) allows for automatic report and graph distribution. This allows reports and graphs to be sent to e-mail or printers, or even to be stored on the server. In addition to distribution on a set schedule, you can tie Report Broker into your program logic. This way if inventory runs low, instead of a generic warning, you can get an inventory-wide report to show you the overall status of your company.

Report Broker uses an Intelligent Bursting technology to break a single report into pieces. Why design several different reports just for various regions or units. With Intelligent Bursting, we can take a single report, break it into pieces based on burst values, and send the data only to those that require it. For example, take a single Regional Sales report and send the complete item to the management team and only each regions data to the regional sales managers!

� Web Query Software Development Kit (5733-QU4) provides a set of Web services that allow you to completely integrate the power of Web Query into your own applications. Use the SDK to pull Web Query into existing Web-based or PC applications. Use it in your own application or many popular open source tools, such as SugarCRM.


Use Table 1-1 as a quick reference for determining which features are part of which offering.

Table 1-1 Feature offering matrix

1.5 Architecture

Although DB2 Web Query runs natively on the System i platform, it comprises multiple application tiers that service different components. The overall architecture contains each of the following components:

� HTTP clients

� Web tier

– Application server

– Web server

� Reporting Server

� Data adapters

Feature Base offering

IBM add-on offering

Base named user licenses X

Web browser interface X

Synonym creation X

Report Assistant X

Graph Assistant X

Power Painter X

Modernized output (HTML, XLS, PDF, and so on)

X

Query/400 adapter X

DB2 Heritage File adapter (multi-member or multi-format files)

X

DB2 CLI adapter (System i tables, physical files, views)

X

DB2 for i5/OS cross-system join X

OLAP X

Developer Workbench X

Active Reports X

Additional named user licenses X

Report Broker X

Web Query Spreadsheet Client X

Run Time User Enablement X

Adapter for Microsoft SQL Server X


� Relational Database Management System (RDBMS) data

DB2 for i5/OS is the integrated database for the System i platform. Other source databases can be used with the installation of the appropriate add-on adapters that are discussed earlier in this chapter.

Figure 1-1 shows the overall architecture of the DB2 Web Query system.

Figure 1-1 DB2 Web Query base architecture

To better understand the architecture, it is helpful to understand the end-to-end process and how a report request flows through the architecture. The following actions describe the life cycle of a typical DB2 Web Query request:

1. A user requests a report for execution from a Web browser.

2. The Web server receives the request, processes the parameters, and routes it to the Reporting Server via the DB2 Web Query servlet.

3. The Reporting Server processes the request and passes it to the appropriate data adapter.

4. The data adapter generates the appropriate database request and submits the request to the DB2 for i5/OS database engine.

5. The Reporting Server receives the result set from the database, formats the report, and returns the formatted report to the Web server via the DB2 Web Query servlet.

6. The Web server delivers the report to the user’s Web browser for display.

Windows Server

IBM System i

DeveloperWorkbench Client

Browser Client

i5/OS Integrated Web Application Server

Reporting Server

Application Client

Applet

DB2 for i5/OS

Data adapters

DB2 CLI

DB Heritage

FilesQuery/400

IBM HTTP serverPowered by Apache

Synonyms

Servlet container

JSP Servlet

IFS

Application directories

(domains and reports repository)

QSQSRVR jobs

Prepackaged WSDL files

Application developed using Web service language:

C++, C#, VB.NET, JAVA, RPG, COBOL

Web based applications containing DB2 Web Query content

Microsoft Excelas Client

Excel Add-in

HTTP

MicrosoftSQL

Server

MicrosoftSQL

Server

Report BrokerDistribution Server

Report BrokerRepository

TCP

TCP

HTTP

SOAP / XML

HTTP


1.5.1 Web browser clients

Both DB2 Web Query developers and users use a Web browser as the interface to the product. The browser clients communicate via HTTP to the application server. The following Web browsers are supported:

� Internet Explorer (IE) Version 6.0 or later� Mozilla Firefox Version 1.5 or later

1.5.2 Web server

Web servers generally serve as the static content repository and handle HTML, GIF, CGI, and other traditional Web content and processing. The IBM HTTP Server is used to fulfill this role for the DB2 Web Query product.

The Web server content for DB2 Web Query is grouped into contexts (aliases). These are grouped together in subdirectories and stored in the i5/OS integrated file system under the qibm/proddata/webquery/ibi/webfocus76 directory. Under this directory is webquery_html, the context subdirectory that contains the following items:

� Common templates and forms� Common images, scripts, and style sheets� Published forms and launch pages

1.5.3 Application server

An application server is a component-based product that resides in the middle-tier of a server-centric architecture. It handles requests from Web clients that require Java and non-traditional processing and provides middleware services such as security and state maintenance. DB2 Web Query runs on the i5/OS Integrated Web Application Server and uses the servlet container component to process these client requests. Servlet containers are also referred to as servlet engines.

The DB2 Web Query application server has the following attributes:

� Is a J2EE-compliant Web application

� Runs on a servlet container, a Java-based container that serves servlets, JavaServer Pages (JSPs), and connectors

� Does not require a full J2EE application server

� Supports servlets

� Standardizes deployment schemes using archives or packages

� In some cases, groups multiple applications into Web Application Bundle (WAB) files

Applications are grouped into the WAB file named webfocus76.wab. This WAB file is served under the context root of /ibi_apps and contains the following components:

– DB2 Web Query servlet

• DB2 Web Query API• Managed Reporting API

Communicates with the MR Repository (basedir)

– DB2 Web Query home page controller and JSPs– DB2 Web Query administration console– DB2 Web Query and Managed Reporting drivers– Communication Drivers to DB2 Web Query server


– Custom DB2 Web Query exit (plug-in)– Custom servlet filter (plug-in)

1.5.4 Reporting Server

The DB2 Web Query Reporting Server is a C-based application that resides on the System i platform and is responsible for managing data access, processing the business logic, and generating the fully styled output. It comprises the following components:

� Reporting Engine of DB2 Web Query product� Data adapters repository� Metadata or synonym repository

1.5.5 Data adapters

An adapter is a program that enables DB2 Web Query to access a data source. Data adapters are responsible for generating the appropriate request to submit to the database engine. DB2 Web Query comes with three different adapters. The adapter that you choose to create your metadata or synonym is transparent to the users who will create reports. The format of the request depends on the adapter that is used:

� The DB2 CLI adapter generates appropriate SQL statements to submit to the DB2 for i5/OS database engine.

We recommend this adapter for use by DB2 Web Query. Select this adapter if you want to write a report on a single member physical file. The report can include an SQL table or a data description specifications (DDS)-created physical file. This adapter is also used for object types of alias, stored procedures, and materialized query tables (MQTs). The DB2 CLI adapter generates SQL that takes full advantage of the latest DB2 enhancements that are found in the SQL Query Engine (SQE).

� The DB2 Heritage File adapter generates the appropriate OPNQRYF command to handle reports that are based on data in a file that has multiple members or multiple record formats.

This command does not take advantage of the new enhancements to the DB2 optimizer and uses the Classic Query Engine (CQE) under the covers.

� The Query/400 adapter retrieves the associated Query/400 query.

Choose this adapter when you want to create metadata on an already existing Query/400 query. The QRYDFN object must exist on the System i platform. This adapter sends the RUNQRY command to the server, which also uses the older CQE.

Table 1-2 summarizes the adapters and how they correspond to the data types.

Table 1-2 Data adapters

In addition to the three adapters that are included in the base Web Query product, we offer the optional Adapter for Microsoft SQL Server. This feature is available as a chargeable

Adapter Data type Command sent to System i5® machine

DB2 CLI Single member physical file; alias, stored procedure, or MQT

CLI API

DB2 Heritage File

Multiple member file, multi-record format files

OPNQRYF

Query/400 QRYDFN object RUNQRY


add-on to the base 5733-QU2 product. With the Microsoft SQL Server adapter, you can connect to Microsoft SQL 2000 or 2005 servers. Metadata is created the same way as in DB2. Once created, you can create reports solely against the SQL Server data or even join tables between an SQL Server and DB2 on i. Learn one set of tools and use them for all of your reporting needs.

1.6 DB2 Web Query Developer Workbench

Developer Workbench serves as the thick client component of DB2 Web Query that is used primarily for advanced development purposes. It is the standard integrated development environment (IDE) for DB2 Web Query technology. Similar to the browser client, the Developer Workbench client communicates in HTTP to the DB2 Web Query application server. Developer Workbench is an optional feature of DB2 Web Query.

1.7 DB2 Web Query product positioning

The base version of the DB2 Web Query product is intended to serve as the strategic replacement to Query/400. If you are using Query/400 today as your primary reporting tool, or your requirements are for a robust query and reporting tool on the System i platform, the base product is all that you need. While the new Web-based product is ideal for the mid-market, it offers the foundation to support large enterprise requirements as well. Consequently, if you have requirements for more advanced business intelligence capabilities, the upgrade path (available through the various add-on components) allows DB2 Web Query to be well positioned to support such large enterprise needs as well. This product fills user reporting requirements from parameterized and ad hoc reporting to analytical (multidimensional) slicing and dicing. It does not require a data warehouse or cubing technology, but if that is the desired business intelligence infrastructure, it integrates with that design with ease.

Because DB2 Web Query is comprehensive and can access all data in a company, it is the logical choice as the standard for business intelligence and reporting for many companies.You can use it for management within your organization to provide the following types of reports to keep you updated on the general health of your business:

� Dashboards� Scorecards� Key performance indicators (KPI)� Drill downs� Operational reports

In addition, the Report Broker product gives you the ability to automatically deliver reports to your users. This add-on component can intelligently burst the pages of a single report to the appropriate people. Delivery can be based on a schedule or technology event (such as a new transaction) the rise of fall of a stock price to a certain level, or even a change in the weather. Delivery destinations include a database archive (called a Report Library) to e-mail (one of the more common destinations), mobile devices, and a printer.

1.8 Request for changes on Web Query

The IBM DB2 Web Query team is always looking for ways to improve the product. If you have a suggestion for a new feature or would like a change to an existing feature, let us know. You can voice your opinion and ideas to us via the Web. You can use the standard Request for


Design change form. This form can be used to requests changes to all IBM products around IBM i. For Web Query, be sure to select the DB2 Web Query option from the problem area drop-down menu. The address to get to the Web form is:

https://www-912.ibm.com/r_dir/ReqDesChange.nsf/Request_for_Design_Change?OpenForm




Chapter 2. Installation and server operations

In this chapter, we explain the installation of DB2 Web Query, 5733-QU2, using the RSTLICPGM command. We outline the PC and System i prerequisites for installing DB2 Web Query. We also describe which i5/OS system jobs will run and their functions in DB2 Web Query. In addition, we discuss other system objects that are created upon installation of DB2 Web Query.

2

Note: For the most current and complete information about the installation instructions, see the IBM DB2 Web Query for i Install Instructions on the Web at:

http://www-03.ibm.com/systems/i/software/db2/pdf/DB2_Web_Query_Install.pdf


http://www-03.ibm.com/systems/i/software/db2/pdf/DB2_Web_Query_Install.pdf

2.1 Installation and setup

The licensed program product number for DB2 Web Query for i is 5733-QU2, which replaces 5722-QU1 (Query/400). DB2 Web Query includes the existing Query/400 product as well as the new offering. You can continue to create and run Query/400 reports and slowly migrate to DB2 Web Query if you choose. The two products can successfully operate concurrently against the same tables and libraries.

Query/400, product number 5722-QU1, as an independent product, will be withdrawn from marketing. The functionality will reside under 5733-QU2 with DB2 Web Query.

In order to continue using Query/400, you must obtain a license key for 5722QU1 via the IBM License Assistance Center.

2.1.1 Installing DB2 Web Query

To install DB2 Web Query, you must follow the up-to-date instructions on the web site listed above. Once on the Web Query home page, click the Getting Started tab. Here you will find links to the install instructions, upgrade instructions, and Info APARS.

While the exact steps are documented on the web, the basic flow of the process consists of:

1. Install prerequisite programs, if missing.2. Install prerequisite PTFs and PTF Groups, if missing.3. Install the DB2 Web Query product.4. Install the PTF Group for DB2 Web Query.5. Install any add-ons purchased and their PTFs.6. Configure a language if not running in English.

It is important that you follow all the steps as documented in the Installation Instructions and Info APARs. As noted, a new Group PTF for Web Query will be released about every three months. Refer to the Info APARs about updated Group PTFs and try to stay as current as possible. If you run into a problem and call support, you will be asked whether you are at the most current Group PTF for Web Query.

i5/OS system objectsUpon installing 5733-QU2, the following integrated file system directories are created:

� /QIBM/PRODDATA/WEBQUERY/IBI� /QIBM/USERDATA/WEBQUERY/IBI

Important: Before you start the installation, you must obtain the most current information about the prerequisites and required program temporary fixes (PTFs). You can find this information in Informational APAR, which is available on the Web at:

http://www.ibm.com/systems/i/db2/webquery



Table 2-1 lists the system objects that are created.

Table 2-1 System objects

These are DB2 Web Query-related user profiles:

� QWEBQRYADM: This profile has functionality on the server side and has authority to start and stop the Reporting Server. The profile is automatically created.

� MRADMIN: This group profile has the authority to create domains in DB2 Web Query. It also has the rights to create reports in all domains and folders on the system.

� MDUNTITLED: This group profile gives users the authority to create reports in the default common domain.

2.1.2 Authorizing and verifying users

The users must be licensed to use DB2 Web Query. For each user that will use the product, you must allocate a license. There are multiple types of licenses available. However, every user must be pre-authorized. In order to add or remove licenses from user profiles, use the WRKWEBQRY Administration tool. For details on the various licenses and the use of the Administration tool see 3.2, “Licensing DB2 Web Query users” on page 27.

You can also use the Administration tool to view who is currently licensed. In addition to the Admin tool, you can view the currently licensed users by running:

WRKLICINF PRDID(5733QU2)

Then take option 8 next to the feature 5050.

2.1.3 License keys

After you install DB2 Web Query, you are allowed a grace period in which to try the product. During this grace period, you have access to all the features that are provided in the base product as well as all of the IBM add-on components. However, after the grace period expires, license keys are required to continue using both the base product and the add-on components.

To obtain your DB2 Web Query license keys, you must work through your normal product ordering channels (for example, a System i business partner). The system serial number is required to generate your specific license keys.

Object name Object type

QWEBQRY76 *LIB

QSYS/QWEBQRYADM *USRPRF

QSYS/MRADMIN *USRPRF

QSYS/MDUNTITLED *USRPRF

QSYS/QWEBQRY *AUTL

QWEBQRY76/QWEBQRYJOB *JOBD

QUSRSYS/QWEBQRYADM MSGQ

Chapter 2. Installation and server operations 19

Each license key is used to activate either the base product feature (5050) or one of the add-on features. To enter your license keys and activate the specific features, use the ADDLICKEY command.

2.1.4 Dynamic Language Switch

If you are running a system that may need to be viewed in multiple languages, the Dynamic Language Switching option is for you. This is included in the base product. It allows you to set a list of languages that a user can select from at login time. This feature will, by default, update the interface of the program to match the language selected. If the user has the Developer Workbench tool and has set multiple field names in each language, then it will show the appropriate header to match the language. However, the data itself will not be translated. Therefore, the level of translation depends on the data source and the configuration of the metadata.

To use this feature, follow the instructions in the installation document on the Getting Started tab of the DB2 Web Query home page at:


2.1.5 Sample database

Throughout this book, we use a sample database called the Century database. This database is available as a save file for download from the link provided in Appendix E, “Additional material” on page 585. This allows you to follow along figure by figure to see exactly what you get in the book. You can use your own data if you like, but we make this sample database available to you. Download the save file from the site below and upload it to your server. Do a restore library of QWQCENT and you are set to follow along.

ftp://www.redbooks.ibm.com/redbooks/SG247214

2.2 Requirements

In this section, we cover the PC and System i minimum requirements to install and run DB2 Web Query.

2.2.1 PC requirements

No client is required to be installed on your PC to enable DB2 Web Query. You only need a browser. The browser requirements are:

� Internet Explorer 6.0 or later� Firefox 1.5 (certified) Version 2.0 (supported)

If you are unsure about the version of Internet Explorer that you are using, open the browser and select Help → About Internet Explorer. Note the version number.

In regard to PC memory requirements, in general, queries usually run best on PCs that have 1 GB of RAM or more.

Note: You do not have to wait for the grace period to expire before you enter your license keys. You can do this at any time.




2.2.2 System i requirements

Your System i environment have V5R4 of i5/OS or later.

2.2.3 Developer Workbench requirements

Although the Developer Workbench client is not required for DB2 Web Query report development and execution, you might still find that it provides additional development features that make it worthwhile. If you choose to install it on your PC, use the hardware and software requirements listed in this section.

Hardware requirementsVerify that your Windows machine meets the Developer Workbench hardware requirements:

� Pentium® 3 or later at 600 MHz or later� VGA or later resolution graphics card; display of 1027x768 recommended� 512 MB of RAM� 500 MB free hard disk space

Software requirementsVerify that your Windows machine meets the Developer Workbench software requirements:

� Windows 2000, XP, or 2003 Server and Professional Editions

Windows 2000 must have Service Pack 2 or later.

� Internet Explorer 6 and later

Internet Explorer components are required for Developer Workbench. If possible, upgrade to the most recent version of Internet Explorer.

� Adobe® Acrobat Reader 6.0 and later

Acrobat Reader 6 and 7 are certified to view PDF reports generated by Developer Workbench.

Provided third-party componentThe third-party component Java 2 SDK 1.5.0_09 is provided for use with Developer Workbench. A Java SDK is required for WebFOCUS features such as servlet connectivity, graph generation, and online analytical processing (OLAP). If it is not present on your machine, you have the option to install it with Developer Workbench.

If Java SDK 1.4.1 or later is not installed on your machine, you must allow Developer Workbench to install the SDK.

2.3 Web Query commands

The base component of the licensed program provides multiple i5/OS commands to help with DB2 Web Query administrative tasks. By default, the commands to work with Web Query are shipped as *PUBLIC *EXCLUDE. However, any user that is authorized to use the commands via *ALLOBJ special authority or explicit authority is able to start or stop Web Query. When starting Web Query, it performs a prerequisite check. If required products or PTFs are

Note: You must be an administrator to the Windows machine to run the Developer Workbench installation.


missing, Web Query will not start. The job log will provide complete details on what was missing to allow you to correct this issue.

� STRWEBQRY

Use the STRTWEBQRY command to start all the jobs that are required to run Web Query.

� ENDWEBQRY

Use the ENDWEBQRY command to end the Reporting Server.

� TRCWEBQRY

The TRCWEBQRY command turns on, turns off, and saves server traces.

In addition to using the CL commands to start and stop the server, you can use the Web Query Administration tool.

2.4 DB2 Web Query server jobs

Typically, the interface that DB2 Web Query uses to access the DB2 for i database is the SQL call-level interface (CLI). CLI is a callable SQL programming interface that is available in DB2 on the IBM i operating system. CLI consists of application programming interfaces (APIs) that are used to connect to the server and start dynamic SQL statements. The CLI is a subset of Open Database Connectivity (ODBC). The system job that processes CLI is QSQSRVR. For more information about CLI, refer to System i Database DB2 UDB SQL call level interface (ODBC) on the Web at:

http://publib.boulder.ibm.com/infocenter/iseries/v5r4/topic/cli/rzadp.pdf

The following jobs run on your server when the Reporting Server is running. For all jobs, the start time of the job is the start time of the Reporting Server.

� EDAPTH: one job that helps with the workspace process and runs under the user profile QWEBQRYADM.

� EDAPLOG: one job that contains startup information and runs under the user profile QWEBQRYADM.

� EDAPGWY: three listener jobs, one each for HTTP, TCP, and Java. These jobs receive incoming requests and hand off work to the TSCOM3 jobs. All run under the user profile QWEBQRYADM.

� TSCOM3: By default, four of these jobs are running. These jobs accept the request from the EDAPGWY job and translate the DB2 Web Query request into SQL. One TSCOM3 job does not correspond to one user. One TSCOM3 job can service several users. For this reason, the design of these jobs contributes to the scalability of the product. They are referred to as agents. and all run under the user profile QWEBQRYADM.

� JSCOM3C: one job that services Java processes and runs under the user profile QWEBQRYADM.

� HLISNK: one job that is an internal server process and runs under the user profile QWEBQRYADM.

� WQLWI7: This job is for integrated application server jobs. Four of these jobs should be running whenever DB2 Web Query is active (three run under the user profile QTMHHTTP, the other under profile QWEBQRYADM).

� QSQSRVR: This IBM i native prestart job handles SQL requests that are made over CLI. This job does the actual database work of optimization, execution, and returning the result. By default these jobs run under the user profile QUSER, but when DB2 Web Query



report (based on a DB2 CLI synonym) is run, a CLI connect event occurs with one of these jobs. At this point, the user profile running the job is swapped to the user profile that initiated the DB2 Web Query report request.

With the exception of the WQLWI7 jobs, these jobs will run in the QSYS work subsystem. However, it is possible to customize your system such that the QSQSRVR jobs run in a different subsystem. The WQLWI7 jobs will run in the QHTTPSVR subsystem.

In addition, the following jobs are started if you have the DB2 Web Query Report Broker product installed and running:

� STRBROKER: one job that runs under QWEBQRYADM and invokes QSHELL to run a script to start the Distribution Server.

� QP0ZSPWP: two jobs that run under user profile QWEBQRYADM. One job is the JVM and the other is the console window that the Distribution Server starts up.

Another way to look at the jobs is via their ports. When running, DB2 Web Query will be active on ports 11331 to 11339. When first started, ports 11336 and 11338 may not start until the first user arrives at the Web Query login page. Port 11339 is used for DB2 Web Query Report Broker. Therefore, if you do not have that product installed, this port will not be active. At the time of publication, port 11337 is not used.

You can look at active ports by using the NETSTAT command and taking option 3. Once the display is up, use F14 to display port numbers. As you scroll down, you will see that the local port column is ordered descending. Scroll down until you reach a local port of 11331 to see these connections.



Chapter 3. DB2 Web Query fundamentals

In this chapter, we introduce the basic steps needed to get started using DB2 Web Query. We discuss the three types of DB2 Web Query users, the two different ways that a user can be licensed to use the product, and the specific tasks performed by each user type.

3


3.1 Types of DB2 Web Query users

There are three types of DB2 Web Query users:

� An administrator� A developer � A basic user

The tasks that each of these users are responsible for are discussed in the following sections:

� 3.5, “Administrator tasks” on page 33� 3.6, “Developer tasks” on page 44� 3.7, “Basic user” on page 87

Each installed DB2 Web Query instance must designate at least one IBM i user as an administrator. It is the administrator who creates report domains and subfolders used by those who develop reports. Different domains are created to segregate your reports by topic or by target audience, for example, Sales, Human Resources, Marketing and Research, or Executive Performance Indicator reports. It is through a domain that access to reports is secured.

An administrator can perform the tasks of a developer or a basic user but does not need to. You may choose to have your DB2 Web Query administrator be someone whose sole purpose is to set up the report domains and control authorized access to develop or use reports within those domains. An administrator has access to all domains and the reports within those domains.

A report developer is someone who can create, alter, and run reports within one or more specifically authorized domains. A developer can also create subfolders for partitioning reports within a domain. The report developer could be a database administrator (DBA) or someone who works closely with the DBA to gain access to the data that is needed to create the necessary reports to meet the needs of a target audience. The roles of the DBA and the report developer are covered under developer tasks.

Finally, a basic user of reports is someone who is only allowed to run reports again, only in specifically authorized domains. A basic user can, based on how the report is defined, influence the content of the report by selecting or providing various input values to a report but cannot actually alter the definition of the report.

Although a DB2 Web Query user may be an administrator, a report developer or a basic user as defined by the product, the operating system's object level security rules are still enforced when it comes to actually accessing the data related to a report. As a basic user, you may be authorized to run a report within a specific domain but if your login profile is denied access to the underlying table, view, stored procedure or Query/400 object, the report will still not run


3.2 Licensing DB2 Web Query users

In addition to the three types of Web Query users, there are two different ways that a user profile can be licensed to use the product:

� Registered/named users

User profiles are explicitly licensed to use the product. These are called registered or named users and each individual user profile consumes a license.

� Run time users

Group profiles are explicitly licensed to use the product. These group profiles are associated with a specific DB2 Web Query domain. Consequently, the number of licenses needed is dependent on the number of domains that are required in your reporting environment. For more information about domains refer to 3.5.1, “DB2 Web Query domains” on page 33. User profiles that are members of these group profiles can then gain access to the product under the license umbrella of the group profile. These user profiles are called run time users.

Regardless of which licensing option you decide to implement, all DB2 Web Query administrators and developers must be registered as named users of the product. It is only a basic user who can access reports by logging in to DB2 Web Query and sharing a runtime user license that is allocated and registered to a group profile tied specifically to the DB2 Web Query domain.

3.2.1 Comparing the licensing options

As described previously, runtime users share a license through an associated group profile that is tied to a report domain. It is the group profile that becomes the named or registered user of the product.

Note: In order to register users as run time users, you must purchase and install 5733QU2 Option 4, the Run Time User Enablement option.

Chapter 3. DB2 Web Query fundamentals 27

Depending on the number of basic users who you anticipate will require access to reports, you can determine whether the Run Time User Enablement option is right for your organization. If the Run Time User Enablement option is chosen, the administrator must to determine the number of explicit licenses of the product to acquire. This is based on the number of report developers (each developer needs a license) and the number of report domains that allow a shared license for run time users. Since access to a report is secured by the domain, each report topic could be its own domain, thus allowing more control over what a basic user is exposed to. For example, in Figure 3-1 this would mean acquiring four additional user licenses for runtime users, one for each domain.

Figure 3-1 Example of DB2 Web Query environment with four domains

Four Domains


Alternatively, you could choose to put all reports under a single domain, as shown in Figure 3-2. The groups of reports could be organized into subfolders. Such an environment would require only one additional license for runtime users. While this type of implementation would effectively provide an unlimited run time (basic) user environment, it would not be as secure because all users would have access to all reports in the single domain, regardless of the subfolder in which they are placed. Keep in mind that you if have in place object-level security the unauthorized users can see the list of reports but they cannot actually execute them.

Figure 3-2 Example of DB2 Web Query environment with one domain

For more information about the Run Time User Enablement option, considerations for how many licenses are needed, and whether this licensing option is a good fit for your environment, follow the articles link on the DB2 Web Query Getting Started page and look for DB2 Web Query Run Time User Enablement.

If the majority of your users are basic users, another licensing option to consider is DB2 Web Query Report Broker, the scheduling and automated distribution product of the DB2 Web Query product suite. With Report Broker, reports and graphs can be scheduled to run in a batch mode and distributed to the target recipients via e-mail or a printer. This type of push implementation means that there is an entire report user community that can have access to reports without consuming user licenses. Because their reports are distributed to them via e-mail, the members of this user community would not require direct access to DB2 Web Query, and therefore would not require and consume a user license. For more information see Chapter 15, “Report Broker” on page 405.

3.3 Registering named users

Because DB2 Web Query requires the registration of users or group profiles (depending on the licensing option implemented), two different methods are provided to help carry out these

One Domain

Note: The maximum number of group profiles that a user profile can be a member of is 16. This is an IBM i operating system restriction and it means that, at most, a basic user could only access reports within 16 distinct domains.


tasks. You can use the Work with Web Query (WRKWEBQRY) utility (discussed further in “Work with Web Query (WRKWEBQRY) administration utility” on page 38) or you can register DB2 Web Query user profiles using the Add Web Query Licensed User (ADDWQLUSR) CL command.

In this section we discuss DB2 Web Query user registration topics using the CL commands.

3.3.1 Adding a new user

To register a DB2 Web Query user, issue the following command:

ADDWQLUSR <userprofile>

Taking this action consumes a user license.

Alternatively, you can register new users from the WRKWEBQRY utility discussed in “Work with Web Query (WRKWEBQRY) administration utility” on page 38.

3.3.2 Removing a DB2 Web Query registered user

To remove a registered DB2 Web Query user, issue the following command:

RMVWQLUSR <userprofile>

Taking this action frees up a user license.

Alternatively, you can remove users from the WRKWEBQRY utility discussed in “Work with Web Query (WRKWEBQRY) administration utility” on page 38.

3.3.3 Displaying registered users

To display the list of user profiles that are currently registered to DB2 Web Query, you can use the WRKWEBQRY utility discussed in “Work with Web Query (WRKWEBQRY) administration utility” on page 38, or you can enter the following command:

WRKLICINF PRDID(5733QU2)

Then select option 8, Work with licensed users, for feature 5050.

This list contains all the user profiles or group profiles (if using Run Time User Enablement) that currently have a DB2 Web Query user license.

3.4 Logging in

Regardless of the type of DB2 Web Query user that you are, the process of logging in is the same. One of the many attributes of DB2 Web Query is that you do not have to install anything on your PC to use it. You only must have a Web browser to create and run reports. As mentioned in 2.2.1, “PC requirements” on page 20, DB2 Web Query supports Internet Explorer and Firefox.


To log into DB2 Web Query, take the following steps.

1. Enter the following internal URL:

http://mysystem.abc.acme.com:11331/webquery

The port number in the URL is always 11331. This is the pre-configured port for DB2 Web Query.

2. A Web page opens like the example shown in Figure 3-3. Sign onto DB2 Web Query with the same user profile and password that you use to access the IBM i machine.

Figure 3-3 DB2 Web Query signon page

Note: In this example, the system name is MYSYSTEM.ABC.ACME.COM:


If your DB2 Web Query instance was configured with Dynamic Language selection, your login will provide you with a Select Language pull-down menu, as illustrated in Figure 3. This allows you to select the language of choice. See 2.1.4, “Dynamic Language Switch” on page 20, for how to configure Dynamic Language selection.

Figure 3-4 DB2 Web Query signon page with Dynamic Language Selection

Upon log in, you see only the domains and menu options that you are authorized to, as shown in Figure 3-5. For an explanation of domains, refer to 3.5.1, “DB2 Web Query domains” on page 33. If you do not see a domain that you think you should be authorized to, contact your DB2 Web Query administrator.

Figure 3-5 DB2 Web Query home page

Tip: Add your DB2 Web Query URL to your browser Favorites menu.


3.5 Administrator tasks

The main tasks for administrators are to create domains, create subfolders within those domains, and assign user authority.

If user profile OZZIE is to be the administrator, use the following CL command to assign it to the group profile MRADMIN:

CHGUSRPRF USRPRF(OZZIE) GRPPRF(MRADMIN)

If the user profile OZZIE already has a group profile, then use the following command so that you do not overwrite the current group profile:

CHGUSRPRF USRPRF(OZZIE) SUPGRPPRF(MRADMIN)

3.5.1 DB2 Web Query domains

In the context of DB2 Web Query, the term domain refers to a graphical way to classify, separate, and secure your reports. For example, an administrator can create domains for sales, human resources, marketing, and so on.

The first time that you open your browser to DB2 Web Query, you see only the default Common Domain folder. Inside the Common Domain folder, you see two other folders, as shown in Figure 3-6:

� The Reports folder is where permanent report objects are displayed. Users go into this folder to find the report that they want to run. Developers who are authorized to this domain can create new reports in this folder.

� The Other Files folder contains files such as style sheets and JPG files that you might want to import into your report.

Figure 3-6 Common Domain folder

Naming your domainIt is good practice to initially name your domains with exactly eight characters. These eight characters are also known as the Href. We explain more about the eight-character rule in the following section.

Attention: To perform the administrator tasks, the administrator must have a user profile and the group profile or supplemental profile for that user profile must be MRADMIN. This administrator is the only one who is authorized to create new domains. The administrator is authorized to create and run reports in all domains.


To view an Href for a domain, as shown in Figure 3-7, right-click the domain and select Properties. If you create a domain that has less than eight characters, the domain name is padded to complete the eight characters. The padding characters are autogenerated. You must know what the Href is in order to assign user authority, which is explained in 3.5.3, “Assigning authority to users” on page 36.

Figure 3-7 Properties of a domain

Reason for creating domains with exactly eight charactersDB2 Web Query uses the Href, which is based on the domain name, to control user access to the domain. DB2 Web Query checks to which IBM i groups the user belongs. If the user belongs to a group named MDhrefname, the user can be a developer in the domain with the associated Href. For a user to be a developer in the Common Domain (Figure 3-7), they must belong to the group MDUNTITLED.

The other special prefix is that DB2 Web Query checks for MU. Having a group profile of MUUNTITLED means that the profile is a valid user in the Common Domain (Href untitled) and is allowed to run reports there but not create them. In fact, the Common Domain is the system default and is the one domain in which you do not require an MUhref to run reports. If you are registered as a licensed user of DB2 Web Query, then you are entitled to run reports in the Common Domain by default.

If you want a domain name to be greater than eight characters, first create it with a meaningful name of exactly eight characters. Then rename your domain to a desired name that is greater than eight characters. The original eight characters remain as your Href name. For example, if you want your domain to be Month End Reports, you can first create your domain as monthend. Then you can rename it to Month End Reports and your Href remains as the eight characters of monthend. Table 3-1 shows the Developer and Basic User group profiles for our example.

Table 3-1 Developer and basic user group profiles

Creating a domainTo create a domain:

1. Log on to the DB2 Web Query home page as administrator, which is a user profile that belongs to the MRADMIN group.

2. Right-click Domains and select New Domain.

Domain name Href name Developer group profile Basic user group profile

Month End Report monthend MDMONTHEND MUMONTHEND


3. In the New Domain window that opens, like the one in Figure 3-8, type your domain name and click Save.

Figure 3-8 New Domain window

4. If your domain name was shorter than eight characters, right-click your domain and select Properties in order to view what was autogenerated.

Renaming a domainAfter creating your domain with a short name to facilitate a meaningful Href, you can rename your domain by selecting the Properties menu option to give it a more descriptive name. Take the following steps to rename a domain:

1. Right-click the existing domain and select Properties.

2. In the Domain Properties window (Figure 3-9) that opens, in the Name field, type a preferred name over the name in the white box. After you edit the name, click OK.

Figure 3-9 Domain Properties window

3.5.2 Creating subfolders

After you create your domains, you must create folders inside of those domains. These subfolders further classify the types of reports within their domains. When the domain is expanded, a developer or user can recognize which subfolder contains the desired report.

Tip: Avoid using blanks or special characters in domain names, folder names, or field names within DB2 Web Query.


Keep in mind that you cannot create reports directly in the Reports folder. You must use a subfolder to create and store reports.

To create a subfolder:

1. Right-click Reports and select New Folder.

2. In the New Folder window (Figure 3-10) that opens, type the desired name for the new folder and click Save.

Figure 3-10 New Folder window

Now developers can create reports in the folder.

3.5.3 Assigning authority to users

As mentioned earlier in this section, one of the key tasks of a DB2 Web Query administrator is to authorize report developers and basic users to specific report domains.

Table 3-2 shows the three user types and the authorities that they have. Using MONTHEND as an example domain, MDMONTHEND denotes the developer group profile for that domain and MUMONTHEND denotes the basic user group profile for that domain.

Table 3-2 Authority of the different users

Note: Both administrators and developers (within the domain) are authorized to create new subfolders. A basic user is not.

Administrator Developer Basic user

Group profile name MRADMIN MDMONTHEND MUMONTHEND

Authority

Create domain Yes

Create subfolder Yes Yes

Create report Yes Yes

Change report Yes Yes

Run report Yes Yes Yes


A DB2 Web Query administrator has two approaches to authorize developers or basic users to DB2 Web Query:

� A manual approach � The use of the WRKWEBQRY administration utility

Manual steps for authorizing users to a domainThe following are the manual steps that an administrator would take after creating a new domain to authorize both a developer and a basic user to the domain.

Let us say that the administrator just created a new domain call monthend where the hrefname for that domain is also monthend. ARCH is a developer and SHANEG is a basic user who runs read-only reports. The administrator would do the following steps:

1. Log in to DB2 Web Query and create a new domain from the DB2 Web Query home page.

2. From the IBM i command line, create two new profiles that reflect developer and user access to the domain:

– CRTUSRPRF USRPRF(MDMONTHEND) TEXT('Group profile for Developers of domain MONTHEND')

– CRTUSRPRF USRPRF(MUMONTHEND) TEXT('Group profile for Basic Users of domain MONTHEND')

3. Change the user profile of both ARCH and SHANEG, adding the domain's developer group profile to ARCH and the domain's user group profile to SHANEG. If ARCH or SHANEG already has a GRPPRF, use the supplemental group profile option, SUPGRPPRF.

– CHGUSRPRF USRPRF(ARCH) GRPPRF(MDMONTHEND)– CHGUSRPRF USRPRF(SHANEG) GRPPRF(MUMONTHEND)

4. Register ARCH as a licensed user (only necessary if this is the first time that ARCH has been authorized as a developer. You can use WRKLICINF 5733QU2, option 8 on 5050 to check).

ADDWQLUSR USRPRF(ARCH)

5. If you are using Run Time User Enablement to authorize SHANEG and as you know that you just created the domain, authorize MUMONTHEND as the shared license user for all basic users running reports in the MONTHEND domain.

– ADDWQLUSR USRPRF(MUMONTHEND)

OR

If you are not using run time user access then SHANEG must be explicitly licensed to use the domain.

– ADDWQLUSR USRPRF(SHANEG)

If a user does not belong to any group profiles for a domain, the user will only be authorized to run reports in the Common Domain. No other domains are visible to the user.

Note: If you use the CHGUSRPRF command to change the group profile or supplemental profile parameter while a user is currently signed on to DB2 Web Query, the user must log off and back on to see the new domain.


Work with Web Query (WRKWEBQRY) administration utilityWRKWEBQRY is an administrative tool designed to assist a DB2 Web Query administrator with the following tasks:

� Determine whether DB2 Web Query is active.� View summary of current license statuses.� Start or end DB2 Web Query server jobs.� Force the end of DB2 Web Query server jobs.� Work with a list of all the users authorized to DB2 Web Query.� Work with a list of domains and add or remove user authorization to a domain.

To accomplish the same task as the manual steps in the previous section, you can use the WRKWEBQRY utility.

As with the previous example, assume that the administrator wants to create a domain called monthend and authorize ARCH as a developer and SHANEG as a basic user. Take the following steps to complete the process using WRKWEBQRY:

1. Log into DB2 Web Query as an administrator and create a new domain named monthend.

2. Sign on to a 5250 session with a user profile that has sufficient authority (as described in the Note box above).

3. Issue the WRKWEBQRY command.

The main menu is presented. This pane displays the current status of DB2 Web Query and how many explicit licensed users of DB2 Web Query there are. It also provides options to start and end the DB2 Web Query capability and the ability to work with users authorized to use the product.

Note: The WRKWEBQRY command is installed with PUBLIC *EXCLUDE, so you need *SECOFR user class or *ALLOBJ special authority to issue the command or you must be granted explicit authority to the command. If your profile is granted access to the command it automatically adopts enough authority to complete Web Query administrative tasks such as authority to create the group profile necessary under the covers necessary to secure domains for developers or users and enough authority to alter existing user profiles to specify those domain-specific profiles as a group profile.


4. To work with the list of DB2 Web Query domains, select option 8, Work with domains.

Figure 3-11 Work with DB2 Web Query main menu

The Work with DB2 Web Query Domains screen is presented. This screen displays each domain's short Hrefname and the descriptive name, and a column to indicate whether the domain is currently enabled.

5. To display a panel with all the current users authorized to work with the MONTHEND domain, locate the MONTHEND domain and specify option 5 to Work with users.

Figure 3-12 Work with DB2 Web Query Domains panel

8/03/09 14:48:10 Work with DB2 Web Query LP12UT21 ______________________________________________________________________________ DB2 Web Query Status: Active Type options, press Enter. 1=End DB2 Web Query 4=Force Server end 5=Work with users 8=Work with Domains *NOMAX Maximum number of licenses for system 5 Total licenses in use for system 5 Licenses in use on this partition

8 ______________________________________________________________________________ F3=Exit F5=Refresh F12=Cancel

8/03/09 14:51:22 Work with DB2 Web Query Domains LP12UT21______________________________________________________________________________ Type options, press Enter 1=Enable Domain 4=Remove Domain from system 5=Work with users Opt Enabled Domain Description YES ADVLAB99 Advanced Lab Template YES COBBGRPP cobbg domain YES COMMON20 Common 2009 YES DB2WBQRY Sales and Marketing Demo YES FLGHT400 Flight400 Reports 5 YES MONTHEND Month End Reports YES NEUGCAM2 NEUGC YES OTHLABXX OthLabXX YES PAYROLLR Payroll Reports YES PERFORMA Performance testing YES SAFDOMAI Structure Ad-Hoc Forms Domain YES SECLABXX SecLabXX YES SPREADSH Spreadsheet Client More... ______________________________________________________________________________ F3=Exit F5=Refresh F12=Cancel


The Work with DB2 Web Query Domain Users screen is presented, as shown in Figure 3-13.

Figure 3-13 Work with DB2 Web Query Domain Users panel

6. Press F6 to add a user.

7. Enter all the information necessary to give user profile ARCH developer (DEV) access to the domain.

Figure 3-14 Add User Authorization pane

Note: Because we just created the MONTHEND domain, this list is limited to users set up with the MRADMIN group profile. In the example, this is user profile WQADMIN.

8/03/09 14:54:44 Work with DB2 Web Query Domain Users LP12UT21 ______________________________________________________________________________ Domain Name: MONTHEND Description: Month End Reports Type options, press Enter. 1=Add authority 4=Remove Authority Opt User Name Authorization WQADMIN ADMIN Bottom ______________________________________________________________________________ F3=Exit F5=Refresh F6=Add user F11=Sort by authorization F12=Cancel

8/03/09 14:59:13 Add User Authorization LP12UT21 ______________________________________________________________________________ User Name: ARCH Type: DEV Valid types: ADMIN Administrator MRADMIN DEV Domain developer MD ( MONTHEND ) USER Domain user MU ( MONTHEND ) SCHED Report scheduler MRSCHEDULE Domain Name: MONTHEND ______________________________________________________________________________ F1=Help F3=Exit F12=Cancel .


8. Press Enter to authorize ARCH as a developer to the MONTHEND domain.

As a result of this request, ARCH will be registered as a licensed user and the profile MDMONTHEND will automatically be added as a group profile. In addition, if this is the first time that a developer has been added to this domain, the utility will automatically create the underlying MDMONTHEND profile.

The other valid types of authorizations possible are:

– ADMIN will automatically register the user profile as a named user and specify MRADMIN as a group profile (thereby making the named user a DB2 Web Query administrator.

– USER gives the named profile the ability run (read-only) reports in the specified domain. If the Runtime User Enablement option is installed the user can share the license of the group profile for the domain. If it is not installed, the user is explicitly registered and consumes a license.

– SCHED is only applicable if Report Broker is installed. Because ARCH is a developer, he can also be given schedule authority for reports in any domain that he is authorized to as a developer. Schedule authority allows ARCH to create Report Broker schedule entries for the automatic distribution of reports.

You are returned to the Work with DB2 Web Query Domain Users screen.

9. Press F6 again to add a new user and enter similar information to give user profile SHANEG basic USER access to the domain.

The Add User Authorization screen is presented, as shown in Figure 3-15.

Figure 3-15 Add User Authorization panel

10.Press Enter to authorize SHANEG as a user to the MONTHEND domain.

Because Run Time User enablement is installed on this box, the administrator has the choice of either registering SHANEG explicitly as a licensed user or of registering the MUMONTHEND group profile as a runtime user license. By default, Runtime enablement is set to Y. If the value for this setting is Y, MUMONTHEND will be created and registered, allowing other basic users to share the registration of MUMONTHEND. If Runtime

8/03/09 15:01:38 Add User Authorization LP12UT21 ______________________________________________________________________________ User Name: SHANEG Type: USER Valid types: ADMIN Administrator MRADMIN DEV Domain developer MD ( MONTHEND ) USER Domain user MU ( MONTHEND ) SCHED Report scheduler MRSCHEDULE Runtime enablement: Y Enter Y or N Domain Name: MONTHEND ______________________________________________________________________________ F1=Help F3=Exit F12=Cancel


enablement was not installed, or if N was specified for the Runtime Enablement setting on this screen, SHANEG would be registered as a named user.

11.Press F12 to return to the Work with DB2 Web Query Domains screen.

12.Select option 5, Work with users, for the domain MONTHEND.

You will now see that we have three users authorized to the domain. One is an administrator, one is a developer, and the other is a run time user. This is shown in Figure 3-16.

Figure 3-16 Work with DB2 Web Query Domain Users panel

Note: The presented list was sorted by user name. Press F11 to toggle the view to sort by authorization as well.

Note: Although WRKWEBQRY does not allow you to create domains, it does give you the ability to register users, both named and runtime, to access the domain. It also manages the underlying changes to user and group profiles.

8/03/09 14:54:44 Work with DB2 Web Query Domain Users LP12UT21 ______________________________________________________________________________ Domain Name: MONTHEND Description: Month End Reports Type options, press Enter. 1=Add authority 4=Remove Authority Opt User Name Authorization ARCH DEV SHANEG USER WQADMIN ADMIN Bottom ______________________________________________________________________________ F3=Exit F5=Refresh F6=Add user F11=Sort by authorization F12=Cancel


Table 3-3 summarizes how the different user types gain access to report domains.

Table 3-3 User type access

User type Group profile requirement License requirement

Administrator MRADMIN User profile is explicitly registered using ADDWQLUSR or WRKWEBQERY.

Developer � MDhrefname group profile specified for each domain in which the developer is authorized to develop reports.

� MUhrefname for other domains that the developer can only run reports in

User profile is explicitly registered via ADDWQLUSR or WRKWEBQRY.

User MUhrefname for each domain that the user is authorized to run reports in

� Run time user: MUhrefname is created and registered as the shared licensed user.OR

� Not run time user:Base user profile is explicitly registered via ADDWQLUSR or WRKWEBQRY.

Note: The DB2 Web Query user license is not automatically removed when a user profile is deleted from the system. This means that you must explicitly remove the user’s registration before the license is freed up and can be used by another user profile. An advantage of Run Time User Enablement is if that if a user profile is deleted, you do not need to worry about removing the DB2 Web Query license (because the license belongs to the group profile and not the user profile that was deleted from the system).


To view all users authorized to access DB2 Web Query domains and the type of licenses that they consume, select option 5, Work with users, on the main WRKWEBQRY menu. Figure 3-17 illustrates the currently authorized users.

Figure 3-17 Work with DB2 Web Query Users

WQADMIN is an administrator and therefore a NAMED license user. ARCH is a developer and also a named license user. MUMONTHEND is a RUNTIME user that shares a license with all basic users with MUMONTHEND as a group profile. SHANEG is designated a USER, no explicit license. He gains access through the group profile. If you did a WRKLICINF PRDID(5733QU2), option 8 on the base option, all of the user profiles except SHANEG would be reflected in the list.

3.6 Developer tasks

In this section, we describe the developer tasks for creating a DB2 Web Query report. We explain the steps that prepare you to write a report, such as which adapter to use and creating metadata.

A developer does not need to know either Query/400 or SQL to use DB2 Web Query. The report writing process in DB2 Web Query is different from either of the former tools. Although DB2 Web Query is mentioned as a replacement for Query/400, it is not a GUI representation of it. The knobs and buttons are different, and it has its own look and feel. This is a completely new tool for the IBM i platform.

8/03/09 15:14:07 Work with DB2 Web Query Users LP12UT21 ______________________________________________________________________________ Type options, press Enter 4=Remove user from Web Query 5=Work with authority Opt User Type Description ARCH NAMED Mike Archer SHANEG USER Shane Garton WQADMIN NAMED Web Query administrator Bottom ______________________________________________________________________________ F3=Exit F5=Refresh F6=Add user F12=Cancel


All examples in the tutorials are based on the sample QWQCENT database and can be downloaded from the IBM Redbooks publication Web site. This database contains four tables. Figure 3-18 shows a database map of the QWQCENT schema that was created using System i Navigator. The icons between the tables represent a foreign key constraint.

Figure 3-18 Database map of the QWQCENT (CENTURY) schema

Tip: The data in the QWQCENT library contains sample data for the years 2006 and 2007. If you would like to update this data so that the year is something more recent, issue an SQL command similar to this one:

UPDATE QWQCENTDEM/ORDERS SET ORDERDATE = ADD_MONTHS(ORDERDATE, 24)

This statement adds two years (24 months) to the values of the ORDERDATE column for all rows in the ORDERS table. Making this change means that for some reports your results will be different from those in the tutorial examples of this book.

CENTURY versus QWQCENT: The sample database was called CENTURY on the pre-general-announcement (GA) version of the product. It is called QWQCENT in the GA version of the product. For this reason, we might refer to the CENTURY database in some places for what is now the QWQCENT database.


For those who are not familiar with SQL and its terminology, Figure 3-19 maps the equivalent terms between SQL and IBM i.

Figure 3-19 SQL and i5/OS terminology

3.6.1 Metadata

Before you can create a single report or graph in DB2 Web Query, you must create metadata (also known as synonyms) over the data source. The metadata requirement of the DB2 Web Query product may be foreign to you. Many IBM i customers are simply not accustomed to working with a product that requires metadata and consequently view it as an unnecessary burden—an extra layer of complexity that they have to create and maintain. Typical questions include the following:

� What exactly is metadata?� Why do I need it?� Can't I just query my files directly?� What happens if the structure of my underlying files changes?

This section explains what metadata is and why you should consider it as an advantageous feature—something that can reduce the complexity of your query and reporting environment and make life easier for your report developers.

What is metadataMetadata is simply data about data. Whenever you issue the DSPFD or DSPFFD commands, what is generated and displayed on your screen is in fact metadata—information such as record lengths, record formats, field names, data types, field attributes, and field lengths. DB2 for i also maintains system catalogs, which are files that store information about each of the objects in your database. They are effectively a materialized metadata repository that is kept up to date and can be queried to collect a wide variety of information about your database.

i5/OSSQL

log

column

row

index

view

table

schema/collection

journal

field

record

keyed logical file

logical file

physical file

library


In much the same way, DB2 Web Query metadata is a materialized repository that contains information about your database files. Before you can create a report or graph in DB2 Web Query you must first create metadata (also referred to as synonyms) over the data sources. You can create a synonym over the following database objects:

� Tables/physical files� SQL views� DDS logical files� Stored procedures� Materialized query tables

In general, whenever you create a synonym over a database object, two stream files are created in a folder in the Integrated File System (IFS):

� Access file

This file has an extension of .ACX and contains the file-level information such as the type of object and the library in which it resides. A very simple example of an access file would look something like Figure 3-20.

Figure 3-20 DB2 Web Query access file example

The access file consists of multiple keyword-value pairs that are separated by commas. Attributes included are the name of the synonym segment (FL400_FRCITY), the underlying table that is referenced (FRCITY in library FLGHT400C), the system to connect to in order to find the data source object (*LOCAL), and the number of key fields (1).

� Master file

This file has an extension of .MAS and contains the column (field) level information such as column name, data type, and length. Figure 3-21 is an example of the contents a master file.

Figure 3-21 DB2 Web Query master file example

Similar to the access file, the master file uses a keyword-value pairing technique to define the column attributes. These include the name of the field, the ALIAS (the underlying field name in the file), the data type and length (for both how it is used in reports and actually defined in the file), and the title to be used in report column headings.

Typically, these two stream files are located in the following folder in the system's Integrated File System (IFS):

/qibm/UserData/webquery/ibi/apps/baseapp

The exception to this is if you have requirements to secure or segment your metadata. In those cases, a custom folder (referred to as an application folder) can be created and

SEGNAME=FL400_FRCITY, TABLENAME=FLGHT400C/FRCITY, CONNECTION=*LOCAL, KEYS=1, $

FILENAME=FL400_FRCITY, SUFFIX=DB2, REMARKS='City table for building Flights (From City)', $ SEGMENT=FL400_FRCITY, SEGTYPE=S0, $ FIELDNAME=FRCINT, ALIAS=FRCINT, USAGE=A3, ACTUAL=A3, TITLE=' CITY,INITIALS', $ FIELDNAME=FRCNAM, ALIAS=FRCNAM, USAGE=A16, ACTUAL=A16, TITLE='CITY NAME', $ FIELDNAME=FRCALN, ALIAS=FRCALN, USAGE=A3, ACTUAL=A3, TITLE=' CITY,AIRLINE', $ FIELDNAME=FRCNBR, ALIAS=FRCNBR, USAGE=P4, ACTUAL=P2, TITLE=' FROM, CITY,NUMBER', $


associated with a specific DB2 Web Query domain (more on this in “Creating an application folder for segmented metadata” on page 82).

The really nice thing about metadata is that it can be an abstraction layer. You can build business logic into the metadata so that all reports and graphs that reference those synonyms have access to all of that logic. This greatly simplifies the environment for the report developers.

Benefits of metadataThe primary objective of the metadata layer is simple: Improve the productivity of the DB2 Web Query report developers by providing an abstraction layer and burying the database complexity. Report developers can be more productive if you keep the data model simple. A simple and intuitive data model also means that you can extend the report developer community because it does not require an intimate knowledge of the database. By empowering more and more of your users, you can reduce their dependence on IT and the number of backlogged reporting requests.

But before this can happen, some work needs to be done to build up this abstraction layer. For this, you must have the DB2 Web Query Developer Workbench tool. This Windows PC-based tool contains several powerful components, one of which is the Synonym Editor. The Synonym Editor contains graphical tools and interfaces that allow you to:

� Define database joins.� Build virtual columns to centralize business logic.� Standardize column formats.� Convert and standardize date fields.� Create filters.� Create business views.� Define OLAP dimensions.

Creating metadataDB2 Web Query metadata can be generated in multiple ways. Each technique is discussed below.

� Create your own.

Metadata creation wizards are available from both the Web browser via the Web Query launch page and in the DB2 Web Query Developer Workbench tool (more on this tool later). To create metadata, you must either be a Web Query administrator (member of group profile MRADMIN) or a developer in the domain. In most cases, this is how the metadata is created.

� Through the use of third-party tools.

Some examples of this include:

– The Databorough x-WebQuery product (www.databorough.com) generates the metadata based on the data model that it derives from both database definitions and business logic buried in application programs. It can also use this extracted information to generate the necessary dimensions for instant OLAP capabilities.

– Information Builders's iWay Data Migrator (www.ibi.com) and Coglin Mill's RODIN DB2 Web Query Edition (www.thinkrodin.com) products generate the metadata in conjunction with building a data mart or data warehouse.

� Provided by ERP or services provider.

ISVs have the ability to include DB2 Web Query content as part of their solutions package. If you purchase such a distribution, the metadata will be included in the package. Similarly, a services provider may have the expertise and tools to build the metadata for you.


For more information about what is created on the system see Appendix A, “Metadata in the integrated file system” on page 527.

In most cases you are going to create your own metadata using the provided metadata creation wizards. To do this, take the following steps:

1. Open a Web browser and enter the URL of the DB2 Web Query home page.

2. On the DB2 Web Query home page, expand the domain in which you want to work. Expand Reports. Right-click the specific report folder and select Metadata (Figure 3-22).

Figure 3-22 Selecting the Metadata option

3. In the Configuring Data Adapters pane (Figure 3-23), select the adapter that matches the data on which you will create metadata. In this example we use DB2 CLI, which is for a single member file. Click the adapter type and select Create Synonym, as shown in Figure 3-23. If you have a connection to a remote database, select the database to which you want to connect from this panel. Notice that we click the *LOCAL connection.

To learn more about data adapters refer to 1.5.5, “Data adapters” on page 13.

Figure 3-23 Creating a synonym


4. In the Select Synonym Candidates for DB2 CLI pane (Figure 3-24), enter your collection name. Select the type of data that you want to query. In our example, we select Tables because want to create metadata on a table in QWQCENT. In the Library field, type qwqcent. Click Next.

Figure 3-24 Selecting the schema or library

5. The Create Synonym for DB2 CLI pane (Figure 3-25) is displayed and shows all the different tables that reside on the QWQCENT (Century) schema. In this panel, select the table names for which you want to create reports.

Figure 3-25 Selecting tables from a schema or library

You might want to include a prefix or suffix. In our example, cen_ is our prefix because the table resides in library QWQCENT. We leave the suffix blank, but the developer has the choice to use it. Leave baseapp in the Application field. Click Create synonym.


The metadata takes a few seconds to create, depending on how many items you selected. After the processing is done, in the Status column, you see the message Created successfully, as shown in Figure 3-26.

Figure 3-26 Created successfully message

The process of creating metadata is now complete. You are ready to begin the tutorials in Chapter 5, “Report Assistant” on page 99.

Miscellaneous considerations about creating metadataThe DB2 CLI adapter can create metadata on five different i5/OS object types:

� Tables� Views� Aliases� Stored procedures� MQTs

Tables, views, aliases and MQTs are treated identically by DB2 Web Query. All of them can be used to filter, join, sort, define, compute, and access all the functionality of Report Assistant. After you create the metadata, you will be unable to tell which object type you are using in your report.

Prefix and suffix (optional, yet recommended): The prefix and suffix are optional letters that you can add to your synonym name to provide extra meaning for you. Using a prefix or suffix is not required. It is up to the developer to decide whether it is necessary to use the prefix and the naming convention that is preferred. We recommend that you use the library name or an abbreviated version of the library name for the prefix. This way, when you create your reports, you can search on all metadata that starts with the library name.

Keep in mind that all metadata is displayed in one box called Database Descriptions. The box is small and does not list the metadata according to library.


Stored procedure synonymsA stored procedure is a program or procedure in a service program that can be called by an application using the SQL CALL statement. Stored procedures can be written in the SQL procedural language, or you can use existing programs or service program procedures (written in RPG, COBOL, JAVA, and so on) and register them to the database as stored procedures.

When it comes to DB2 Web Query data sources to base their reports on, many developers only use database objects like tables and views. But a very powerful, yet under-utilized feature of DB2 Web Query is its ability to use a stored procedure as a data source, provided that the stored procedure returns a result set. DB2 Web Query has the ability to capture that result set and use it as the source data for a report.

When a DB2 Web Query synonym is created over a stored procedure, the result set is used as the format for synonym. This means that all fields in the result set can be used as columns in the report. In addition, the input parameters of the stored procedures can be used as input parameters for the report. Consequently, you can pass parameter values from a report to the stored procedure, let the procedure use those values to perform the business logic, and return the results to the report.

This is a powerful technique because it gives the report developer programmatic control over what is returned to DB2 Web Query. Consider the following ways that a stored procedure could be used with the tool:

� Reuse and repurpose the business logic in your existing programs.You can take an existing RPG program (or one written in any language supported by the IBM i), make small modifications to return a result set, and register it to the database as a stored procedure. This means that many existing reports generated by RPG programs could be converted to work with DB2 Web Query. Comment out the header lines and change the details line to write to a result set, temporary file, or array, rather than a print file record. By combining DB2 Web Query with existing report programs, you can salvage proven business logic and provide a modernized output format for those old reports.

� Use native record level access (RLA), instead of SQL, if you prefer that method of data access.

� Provide the ability to call to other programs, commands, and system APIs as well as pull data from other system objects such messages queues, data queues, or data areas.

� Provide a way to dynamically change the library list by passing an input parameter to the stored procedure (and changing the library list based on that parameter value), then execute the appropriate process to return the result set.

� Adopt authority of the user profile that owns the underlying program or service program. This gives you the ability to restrict access to the database objects and only allow users to access the objects through the programs (stored procedures) with adopted authority.

� Provide auditing capability. The stored procedure can include logic to insert a row in an audit log table to record any report request. With so much attention given to security and auditing these days (that is, Sarbanes-Oxley), this can be very important consideration, especially for users who have access to sensitive information.

� Provide the ability to programmatically change attributes of the querying job. Examples of what can be specified in a stored procedure to change the environment are:

– SET CURRENT DEGREE to enable Symmetric Multi Processing (SMP) and boost query performance of a long-running report if the requestor is an executive or other high-profile user.

– SET OPTION SRTSEQ to change the collating sequence of the report.


To illustrate how a stored procedure could be used, let’s assume that you need to create a report that returns rows from a sensitive table (the HR table) and you must add an auditing feature to this report. That is, each time the report is run, information such as the time stamp, name of the report, and requesting user profile must be logged to an audit table.

To create a stored procedure that returns data from specific columns in the payroll table and satisfies the auditing requirement take the following steps:

1. From an SQL interface such as System i Navigator Run SQL Scripts, create the audit table:

CREATE TABLE rptaudlog (rpttimst TIMESTAMP, rptname CHAR(25),rptusrprf CHAR(10))

2. From same SQL interface, create the stored procedure:

CREATE PROCEDURE hr_table_audit (inplantcode CHAR(3))DYNAMIC RESULT SETS 1 LANGUAGE SQL NOT DETERMINISTIC MODIFIES SQL DATA P1 : BEGIN

DECLARE c1 CURSOR WITH RETURN TO CLIENT FOR SELECT lastname, firstname, status, payscale, salary FROM hrWHERE plantcode = inplantcode; INSERT INTO rptaudlog VALUES(CURRENT TIMESTAMP, 'HR Salary Report', SESSION_USER); OPEN c1 ;

END P1 ;

Several items must be pointed out for this store procedure:

� The cursor is declared with the “WITH RETURN TO CLIENT” clause specified. It is a good idea to specify this clause to ensure that the result set is returned to the client application. “WITH RETURN TO CALLER” is the default, which would cause problems in the event that you had a nested stored procedure (a stored procedure called by another stored procedure) that was actually returning the result set.

� The INSERT statement is specified to log the request. This satisfies the auditing requirement.

� The cursor is opened (and left open). This returns a result set to the client application (which is DB2 Web Query).


The process for creating a stored procedure synonym is similar to that of creating a synonym over a table. Take the following steps:

1. From the Select Synonym Candidates for DB2 cli (*LOCAL) Step 1 screen, select Stored procedures from the Restrict object type to drop-down list, specify the library, and click Next, as shown in Figure 3-27.

Figure 3-27 Creating stored procedure synonym: step 1

The Select Synonym Candidates for DB2 cli (*LOCAL) Step 2 or 3 screen is displayed.

2. From the list of stored procedures displayed, select HR_TABLE_AUDIT, as shown in Figure 3-28.


If the stored procedure has input parameters, you will be prompted to enter a valid value for the input parameter.

3. As demonstrated in Figure 3-29 on page 55, specify a valid input parameter value by taking these steps:

a. Select/check the INPLANTCODE parameter.b. Specify ORL as the value for the input parameter. (This is a valid Plant Code value.)c. Click Create Synonym.



As shown in Figure 3-30, a confirmation window is displayed to confirm that the stored procedure synonym was successfully created.

Figure 3-30 Stored procedure synonym created

For an example of how to create a report over this synonym, see 5.6, “Creating a report over a stored procedure synonym” on page 147.

Considerations with multimember filesAs noted in Table 1-2 on page 13, the DB2 CLI adapter sends SQL statements to i5/OS, where the DB2 Heritage File adapter sends the OPNQRYF CL commands. As indicated earlier, DB2 for i5/OS optimizes SQL and OPNQRYF differently. SQL can go down the

Note: When the synonym is created, the stored procedure is called by DB2 Web Query so that it can receive the result set. This is because it must store the format of the result set in the synonym. Consequently, you must pass it a valid value for the input parameter at this step.

Multiple result sets: DB2 Web Query supports the return of multiple result sets from the stored procedure. In this case, it assigns a distinct segment name to the fields of each separate result set.


codepath of the newer SQE, while OPNQRYF must still go down the CQE path. In general, SQE tends to be faster than CQE.

A limitation of SQL is that it can only read data from the first member in a file. Perhaps you have run into this limitation when writing SQL queries on multimember files before. One option is to consider using an SQL alias, which enables your query to use the DB2 CLI adapter and makes the query eligible for SQE. The alias is a permanent i5/OS object that points to a specific member in a file. It is easy to create, and after it exists, SQL treats the alias the same as it would a table. Simply substitute the alias name in any query where you would put a table name.

An example of a CREATE ALIAS command in SQL is:

CREATE ALIAS QGPL/MYALIAS FOR QGPL/MULTI_MBR_FILE (MBR_NUM_2)

You can run this command in the Run SQL Scripts window of iSeries Navigator or in STRSQL from the command line. STRSQL has a prompt for CREATE ALIAS that is intuitive.

You can create metadata on an alias as easily as you can on a regular table. Refer to “Creating metadata” on page 48, which explains how to create DB2 Web Query metadata.

The DB2 Heritage File adapter also has the limitation of only being able to join on key fields. If you try to join on non-key fields using the multimember file adapter, you receive an error message (Figure 3-31). This message might provide extra incentive to create an alias and use the DB2 CLI adapter.

Figure 3-31 Error message regarding joining on non-key fields

Refreshing metadata (when IBM i database object structure changes) A common concern for many customers is what happens when the metadata gets out of synch with the underlying data source. For example, if the database administrator alters a table and either adds a new column or removes an existing one, do existing reports still run successfully? The answer to this is that it depends. The synonym may need to be refreshed to reflect this change. If none of your reports reference a column deleted from the underlying file, a synonym refresh is not required. The same applies if you do not want to include the new column in any existing or new reports. However, if the changes do impact your reports, you must synchronize the synonym with the altered file. For this, there is an option from the right-click menu, DB2 Web Query Developer Workbench, to refresh the synonym. This is shown in Figure 3-32 on page 57.


Figure 3-32 Refresh Synonym

When this action is taken, the synonym is parsed and its contents are compared with the structure of the actual underlying data source. New columns are added to the synonym and deleted columns are removed. Any custom changes (joins, virtual columns, filters, OLAP dimensions, and so on) that were made to the synonym are preserved.

What happens to the metadata if the IBM i database object is deletedIf you delete the underlying database or the QRYDFN object, the DB2 Web Query report cannot run based on the metadata alone. If you attempt to run the report in DB2 Web Query, you receive an error message. You have the option to recreate the table or QRYDFN exactly as it was before. Therefore, you do not need to recreate the metadata. Or if you create a new, yet slightly different object, you must create new metadata on that object.

Referential integrityIn this section we explain the benefits to DB2 Web Query of having referential integrity defined in the database. We begin by briefly explaining referential integrity.

A feature of a relational database is that it must support the definition and enforcement of referential integrity. If you do not fully grasp the meaning of referential integrity, you are not alone.

A database can consist of one large fact table and several smaller dimension tables. The dimension tables each contain a primary key that is referenced by a foreign key in the fact table. For our example, the primary key on the inventory table is PROD_NUM, and the corresponding foreign key on the order table is PROD_NUM. An entry in the fact table is not

Attention: The Refresh Synonym will not update the synonym for all database object changes. For example, if column attributes such as data type or length are altered in the database object, those changes are not applied to the synonym. For those types of changes, the synonym must either be manually edited or recreated.


allowed unless there is a matching key in the dimension tables. That is, you are not allowed to place an order for a product that is not confirmed to be in your inventory. The referential constraint does not permit an entry into the orders table unless the entry has a value for PROD-NUM in the inventory table. This prohibits unmatched, or orphan, entries in the Orders table.

Benefit of using referential integrity in DB2 Web QueryWhen DB2 Web Query creates metadata, it recognizes files that are related through referential integrity and brings them all in together in one piece of metadata. When you write your report, you select a single synonym or table name that includes several files that are all related to each other. You do not need to manually define all the table joins. In order to have this convenience, you must have defined constraints on your tables.

If you do not currently have referential integrity in your database, we strongly recommend that you consider implementing it. Not only does referential integrity aid in more effective report writing in DB2 Web Query, but it also moves your business logic closer to the database level to reduce the programming effort. You do not need to understand SQL to add constraints to your database. You can do this easily by using iSeries Navigator. Referential integrity constraints can be added to files that are created with DDS and CRTPF, or they can be added to tables that are created with the CREATE TABLE statement.

The following brief example demonstrates how to set up referential integrity on our sample QWQCENT database. The orders table is the fact table. The inventory, plant, and stores tables are the dimensional tables. For our example, we set up referential integrity between the orders table and the inventory table. An item must exist in the inventory table before it can have a child in the orders table.

First we must create a primary key in INVENTORY, then we can create the foreign key in ORDERS. The relationship between the two is called a referential constraint. The referential constraint starts at the child table and ensures that no child entry is inserted into the table unless an entry exists in the parent table.

Creating a primary key on INVENTORY field PROD_NUMOpen iSeries Navigator and follow these steps:

1. Expand the database container.

2. If the Century (QWQCENT) database is not currently displayed, right-click Schemas and then Select Database to display.

Tip: You can also think of the small dimension tables as parent tables, and the large fact table as a child table. Do not let the part about the child table being larger confuse you. Think of it as a parent that has many children. The constraint does not let the child be born unless the parent already exists.

Tip: If you want to add constraints by using the command line, use the ADDPFCST command. If you want to add constraints by using SQL, use the CREATE TABLE or ALTER TABLE statement.


3. In the Select Schemas to Display window (Figure 3-33), in the Enter schema names field, type Century and click Add. Then click OK.

Figure 3-33 Select Schemas to Display window


4. In the left navigation bar of iSeries Navigator, expand the CENTURY database and click Tables. In the right pane, right-click the INVENTORY table and select Definition, as shown in Figure 3-34.

Figure 3-34 Selecting the Definition option

5. In the next window, from the tabbed selections, click the Key Constraints tab and then click Add.


6. In the New Key Constraint window (Figure 3-35), complete these steps:

d. Under Constraint type, select the Primary Key radio button.

e. Under Available columns, select the ProductNumber field and click the Add arrow button. Now the ProductNumber field is displayed under Selected columns. Click OK.

Figure 3-35 Key Constraints window

7. In the window that contains the various tabs (Figure 3-36), click OK.

Figure 3-36 Key Constraints tab showing the ProductNumber field


You are now finished creating the primary constraint on the Inventory table. Next, we go to the orders table and create a referential constraint. Remember that the orders table checks the inventory table to ensure that any new record also has a matching key value in Inventory.

1. Expand the Century schema and click Tables. Right-click the Orders table and select Definition.

2. In the next window, click the Foreign Key Constraints tab. Click Add.

3. In the New Foreign Key Constraint window (Figure 3-37) complete these steps:

a. For table name, select Inventory.

b. Under Available Columns, select ProductNumber and click Add. We know that this is the primary key on the inventory table because it is indicated under Key columns near the top of the window on the right. Click OK.

Figure 3-37 New Foreign Key Constraint window

You are now finished creating the referential constraint between the inventory and orders tables. You can now repeat this process with the two other dimension tables, stores and plant. The key fields on those tables are, respectively, Store_Code and Plant_Code. The orders table has the corresponding foreign key for each table as it did for the inventory table.

After you are done creating the other two referential constraints, your database is now ready for metadata creation.


Creating metadata on tables with referential integrityThe process to import a cluster of related tables into one piece of metadata is similar to creating a single piece of metadata. Review “Creating metadata” on page 48. In the Create Synonym pane (Figure 3-38), notice the With foreign keys check box at the top of the page. This is the difference in the process. You must select With foreign keys so that the related tables are included in the same piece of metadata.

Then the only table that you must select is the fact table, which in our case is the ORDERS table. The dimension tables are automatically included. Then click Create synonym. You can check all the related tables if you would like to, but the final metadata creation is the same.

Figure 3-38 Creating metadata with referential integrity


Next the Status pane (Figure 3-39) is displayed, on which you see the status message Created successfully. Notice that there is only one piece of metadata. You can close this panel.

Figure 3-39 Created successfully message

When you first start to write the report based on the file cluster, you are presented with the metadata window. The related files are all under one name. The description says Cluster xxx for table yourFactTable, as in Figure 3-40. The word Cluster in your metadata indicates that referential integrity has been used to create that metadata. All the related dimension tables with referential constraints defined appear in Report Assistant.

Figure 3-40 Cluster: metadata with referential integrity


When you create a report, the list of columns can be presented alphabetically or by segment. In our case, segment means table. See Figure 3-41.

Figure 3-41 Field selection sorted by table

Creating metata over tables without referential integrityWhile there are many advantages to implementing referential integrity, many existing DB2 for IBM i production databases currently do not have RI set up. This means that an administrator or developer has the following three options if tables must be joined together:

� Defined in SQL views� Defined in the DB2 Web Query metadata layer� Defined in the reports and graphs

Each of the above options is discussed in the following sections.

Defining joins in SQL viewsAn SQL view is a virtual table whose definition is based on a SELECT statement. In traditional i5/OS terms, they can be thought of as non-keyed logical files. Because there are no keys associated with views, there is no access path maintenance. This means that you can create as many views as you like and not worry about performance repercussions associated with access plan maintenance.


For DB2 Web Query, SQL views are particularly useful because they can be used to join tables together. Once the view is created DB2 Web Query metadata can be created over the view (instead of the base tables). Reports using that synonym can access any of the columns from each of the join segments defined in the view. Using reports based on SQL views provides several distinct advantages to DB2 Web Query, including the following:

� Encourages database optimization (pushes logic down to DB2)

� Provides method for implementing more complex reporting requirements such as row and column-level security

� Provides additional join types, unions, intersects, excepts, Common Table Expressions, complex business logic (case statements, and so on)

� Data-centric because business logic and rules can be defined in one place (at the database level) rather than the application level

In addition, SQL views can be accessed by other interfaces such as RPG programs (with embedded SQL or native Record Level Access), ODBC, JDBC, and so on.

In Example 3-1 we ilustrate an SQL View that could be leveraged by DB2 Web Query.

Example 3-1 SQL View definition

CREATE VIEW ORDERSVIEW (ORDERNUMBER FOR COLUMN ORDER_NUM, PRODUCTNUMBER FOR COLUMN PROD_NUM,...)AS SELECT a.*, b.*, c.*, d.* FROM orders a INNER JOIN stores b ON a.storecode = b.storecode INNER JOIN inventory c ON a.prod_num = c.prod_numINNER JOIN plant d ON a.plantcode = d.plantcode

A synonym created over the example SQL view would contain all of the columns in the joined tables.

Defining joins in DB2 Web Query synonymsYou can also define the file relationships in the DB2 Web Query metadata. When this technique is employed, DB2 Web Query join syntax is stored in metadata and translated to an SQL statement with join syntax. Because the joins are defined at the synonym level, you only must do this in one place. Every report that uses this synonym will have access to the join logic already defined, thus it is not necessary to define joins in each report. This is an example of the power of the metadata abstraction layer.

Consider the following when using this technique:

� Requires DB2 Web Query Developer Workbench to edit the synonym and define the join segments.

� Can be accessed by all DB2 Web Query reports and graphs that use the synonym. It is not accessible from any other SQL interface.

� Performance could suffer if logic is not pushed down to database due to database optimization disablers. For more information about this see “Performing analysis and looking for optimization disablers” on page 481.


Before you begin this exercise, you must have a basic understanding of the different types of joins that DB2 Web Query supports:

� Multiple (SEGTYPE=S0)

Indicates that the segment has no key field and is therefore not sorted. Keys and sequences are defined in the access file. With the multiple segment type, each joined file is represented as an individual join segment. If no matching row is found based on the join criteria, no row is returned to the join. This prevents something called the multiplicative effect, but also does not allow a developer to write a report that sorts (or performs a combination of sorting and selecting) across the different segments.

� Unique (SEGTYPE=U)

For each join definition. Every child segment becomes logically part of the parent. At least one row will be retrieved, regardless of whether a matching row was found. If there is a one-to-many relationship between parent and child, all children will be returned (despite the name Unique, which indicates a one-to-one relationship). Since the child becomes an extension of the parent, the result is one virtual segment. This provides the ability to sort and select fields across the underlying segments, but could also result in a report that delivers incorrect results due to the multiplicative effect.

For this exercise, we are not concerned about the multiplicative effect. Therefore, Unique join types are defined.

1. Open DB2 Web Query Developer Workbench.

2. Expand WebFOCUS Environment → your-system-name and log in using your user profile and password.

3. Expand Data Servers → EDASERVE → Applications → baseapp.

4. Under the contents of baseapp in the right navigation pane, select cen_orders.mas and from the right-click menu select Edit in Synonym Editor (Figure 3-42).

Figure 3-42 Edit in Synonym Editor


The cen_orders master file is opened in the synonym editor.

5. Right-click the CEN_ORDERS segment and select Add → Segment From Existing Synonym, as shown in Figure 3-43.

Figure 3-43 Add join segment to synonym

The list of existing synonyms is presented.

6. From the presented list, select the cen_inventory synonym, as shown in Figure 3-44 and click the Select button.

Figure 3-44 Select synonym to add

The segment CEN_INVENTORY is added under CEN_ORDERS.


7. Select the CEN_INVENTORY segment and change the join segment type (SEGTYPE → Type) setting from Multiple (the default) to Unique, as shown in Figure 3-45.

Figure 3-45 Specify Unique join segment


Figure 3-46 Join properties

Note: Once you have changed the segment type to Unique, the icon next to the CEN_INVENTORY segment becomes a red color.


8. PRODUCTNUMBER is the field that is used to join ORDERS to INVENTORY. Select this field under both tables and click the = button (located between the tables lists), as shown in Figure 3-47. Make sure that Inner Join is selected for the join type.

Figure 3-47 Specify join columns


This brings the join formula into the Expression pane, as shown in Figure 3-48.

Figure 3-48 Join columns in expression

9. Click OK.

10.Repeat step 5 on page 68 to step 9 for the CEN_STORES segment. The join field for this join is STORECODE.

11.Repeat steps 5 on page 68 to step 9 for the CEN_PLANT segment. The join field for this join is PLANTCODE.


12.At this point you have created a cluster for the ORDERS table. The segments of this cluster should look like the example shown in Figure 3-49.

Figure 3-49 CEN_ORDERS with all join segments


13.Save your work by clicking the Save icon, as shown in Figure 3-50.

Figure 3-50 Save synonym

3.6.2 Setting up a cross-system join

The base version of DB2 Web Query provides the ability to access tables and views on remote systems. This means that you can create reports against data that resides on the following systems:

� The local system� A remote IBM i machine or logical partition (LPAR)� A combination of both the local system and a remote IBM i machine or LPAR

This feature provides the foundation for creating a report with a federated or cross-system join. A cross-system join is a join in which the underlying base tables reside on multiple IBM i machines. The restriction here is that all databases (both local and remote) must be DB2 for i5/OS.

In the following task, we explain how to create a connection to a remote DB2 on a IBM i machine. If you already defined a remote database using the WRKRDBDIRE command, you can skip the first three steps.

1. Open iSeries Navigator.

2. In iSeries Navigator, expand the desired connection name. Under the expanded connection, right-click Databases and select New → Relational Database Directory Entry, as shown in Figure 3-51.

Figure 3-51 Selecting the option to create a new Relational Database Directory entry


3. In the Add RDB Directory Entry (ADDRDBDIRE) window (Figure 3-52), specify the following options:

– Relational database

This is the logical name to assign to the relational database. It is usually the name of the remote system or partition.

– Remote location name or address

This is either the fully qualified system or the partition name or the IP address.

– Remote location type

This refers to the protocol that is being used to communicate between the two systems or partitions. In most cases, you specify *IP for this setting.

Click OK.

Figure 3-52 Add RDB Directory Entry window in iSeries Navigator

Tip: Another option is to use the CL command ADDRDBDIRE.


4. Open your Web browser to the DB2 Web Query console on port 11331, for example:

http://yoursystemname:11331/webquery

5. Enter your IBM i user ID and password.

6. Navigate down to any folder under Reports, right-click, and select the Metadata option.

7. Select Data Adapter from the menu bar.

8. In the Data Adapters window (Figure 3-53), click DB2 cli and select Add connection.

Figure 3-53 Adding a connection to data adapters

9. In the Add Connection for DB2 cli pane (Figure 3-54 on page 77), specify the following options:

– Connection Name

This is the logical name that is used to identify this particular set of connection attributes. It is usually the remote system or partition name, but it does not have to match any value that is specified during the Add RDB Directory Entry step (step 3 on page 75).

– Datasource

This is the DB2 database name that is used for this connection. The name must match the Relational Database value that is specified during the Add RDB Directory Entry step.

– Security

There are three methods by which a user can be authenticated when connecting to a DB2 database server:

• Explicit

The user ID and password are explicitly specified for each connection and passed to DB2, at connection time, for authentication.

• Password Passthru

The user ID and password received from the client application are passed to DB2, at connection time, for authentication.

• Trusted

The adapter connects to DB2 as a Windows login using the credentials of the Windows user, who impersonated by the server data access agent.

– User

For Explicit security only, this field is for the i5/OS user profile.


– Password

For Explicit security, this field is for the password that is associated with the specified i5/OS user profile.

Click the Configure button.

Figure 3-54 Add Connection for DB2 cli pane

10.Create the synonyms for the remote tables or views that you want include in your reports:

a. In the Data Adapters window (Figure 3-55), click the remote connection and select Create Synonym.

Figure 3-55 Selecting the Create Synonym option


b. In the Select Synonym Candidates for DB2 cli pane (Figure 3-56), for Restrict object type to, select Tables and Views. Then specify the name of the Library (schema) that contains the database objects that you want to include in the cross-system join. Click Next.

Figure 3-56 Select Synonym Candidates for DB2 cli pane

c. In the Create Synonym for DB2 cli pane (Figure 3-57), specify the prefix (recommended format is connectionName_libraryName_) and select the tables, views, or both that you want to include in the cross-system join. Click Create synonym.

Figure 3-57 Create Synonym for DB2 cli pane


11.Include the table in your reports by using a cross-system join:

a. In the DB2 Web Query home page, under the desired folder, select Report Assistant.

b. In the Select from available database descriptions panel, find and select the synonym for the local table; do not select remote synonym just yet.

c. In the Report Assistant window (Figure 3-58), click the Join options tab.

d. On the Join options tab, complete these steps:

i. Click New.

ii. In the Web Page Dialog that opens, find and select the synonym for the remote table and click OK. Notice that the Join options page changes.

Figure 3-58 Selecting the target database description


iii. Under Join Settings, as shown in Figure 3-59, specify the Join Type, Description, Instances, and Join fields options.

Figure 3-59 Specifying the join options

Note: For more information about joining tables, see 5.5, “Joining tables (reference only)” on page 144.


12.Click the Field Selection tab. At this point, you can finish the report by specifying the desired options such as Sort by and Sum as shown in Figure 3-60. All of the fields from the joined files are displayed in the list of fields to select from. Notice that the fields are color coded to clearly identify the files from which they originated. See Chapter 5, “Report Assistant” on page 99, for more details about report writing.

Figure 3-60 Field selection tab

3.6.3 Segmenting and securing Metadata

An enhancement that was added to the DB2 Web Query product via a PTF is the ability to segment and secure your metadata. Prior to this feature, all synonyms were created in the common application folder BASEAPP. Consequently all synonyms were displayable and selectable from all report development interfaces (across all domains). There was no way to filter the list of synonyms for specific users or groups of users. This was problematic for several reasons:

� All report developers could see sensitive synonyms. Although they could not see the data of the underlying tables, the ability to see the names and existence of sensitive synonyms was still an area of concern.

� The list of synonyms to use when creating a new report could be extensive and finding/positioning to the desired synonym wasn't always easy

� Promoting reports and their referenced synonyms through the development cycle was tedious because the reports had to be changed (at each step) to reference specific and uniquely named synonyms in BASEAPP.


These areas of concern have been addressed with the ability to create custom application folders and associate them with specific domains. The application folder (and the synonyms within it) can now be set up as an extension of the domain. Because domains are secured using IBM i group profiles, you now have the ability to segment and secure your synonyms.

Creating an application folder for segmented metadataCreating new application folders to hold your synonyms is a feature provided by Developer Workbench. This is done by logging into DB2 Web Query Developer Workbench as a user profile that is a member of the MRADMIN group profile and selecting Applications under the Data Servers folder. Once there, select New Application from the right-click menu as shown in Figure 3-61.

Figure 3-61 Create new application

Linking an application folder to a domainOnce you new application is created you simply create new synonyms in that application folder. To associate the application folder with a specific domain, take the following steps:

1. Select the domain

2. From the right-click menu select Domain Properties


3. From the he domain properties dialog, check the Application Path setting, select the desired application folder, and click the right-arrow icon (located between Available and Selected list). An example is shown in Figure 3-62.

Figure 3-62 Linking the payroll_files application to the Payroll domain


After clicking the right arrow icon, the application will move from the Available list to Selected. An example is shown in Figure 3-63.

Figure 3-63 Linked payroll_files application

You can remove applications from a domain by selecting the application under the Selected list and clicking the left arrow icon. This will move it back to the list in Available.

4. Repeat the above steps to add application webqry01 to the domain.

Note: Although only one application can be selected at a time, you can repeat the above steps and add as many as you want from the list under Available to Selected. There is no documented limit for the number of application folders that can be linked to a domain (as many as 1,500 application folders have been successfully linked during system testing). However, you may want to consider performance implication before adding this many to your domains.


5. When you have finished linking the applications to the domain, you can sort the Selected list by selecting the application and using the up and down arrow icons above the list. Use this technique to move the payroll_files application to the top of the list as shown in Figure 3-64.

Figure 3-64 Move payroll_files to the top


After clicking the up arrow icon, the Selected list is sorted as shown in Figure 3-65.

Figure 3-65 Linked and sorted applications

When DB2 Web Query searches for the synonym specified for a report in this domain, it will use the list in the order you have configured - much the same way library list searching works on the IBM i system. This means that if you have a synonym named cen_payroll in all three selected application folders (payroll_files, baseapp, and webqry01) any report that references cen_payroll will use the version in the payroll_files application, because it was first in the list.

6. Accept the settings by clicking the Apply button.

7. Click OK to close the Domain properties dialog window

Once you have associated an application folder to a domain, you have secured it. The synonym is only visible and accessible to those developers explicitly authorized to the associated domain or to user profiles that are members of MRADMIN. The report developers can only reference the synonyms in the application by creating reports from within the domain that the application is linked with.


A developer using DB2 Web Query Developer Workbench tool can only access the Application folders by going through the domain. As shown in the example in Figure 3-66, notice that when the Payroll developer logs in using Developer Workbench, there is no Data Servers option under the system/environment name.

Figure 3-66 DB2 Web Query Developer Workbench interface for developers

The Data Servers option is only available for members of MRADMIN. In order to work with application folders (and the synonyms within them), the developer must expand Domains → Applications. The only applications that appear in this list are the ones that have been linked to the domain. This way the developer can only access synonyms in the application folders linked to the domains that he or she is authorized to.

3.7 Basic user

The basic user employs DB2 Web Query to run reports, so in this section, we explain how to run a report. Before you continue, ensure that you have read 3.4, “Logging in” on page 30, and are logged on to the DB2 Web Query home page. You only see the domains to which you are authorized. If you do not see a domain that you need, contact your DB2 Web Query administrator.


To run a report, expand the domain. Then expand the Reports folder and the subfolder. The subfolders inside of this report categorize the reports within the domain. After you expand the subfolder, double-click the report that you want to run. The Processing Request panel is displayed while your results are retrieved from the server. Then the results are displayed in the right panel (see Figure 3-67).

Figure 3-67 Running a report

Keep in mind that the results of your report are returned to your PC and stored in your browser. This affects the time that it takes for your results to appear. If your report returns several thousands of records, you will notice more delay than if your report returns ten records. If you think the report returns more records than you can use, ask your developer to limit the number of records that are returned to you. We explain how to do this in 5.2.3, “Sum and detail reports” on page 104.


Part 2 Tutorials for DB2 Web Query

This part and Part 3, “Tutorials for DB2 Web Query optional features” on page 231, are structured as basic tutorials. These examples are not intended to replace reference manuals or customer education classes. The intent is to provide hands-on exercises that help you get started and demonstrate the more common reporting techniques.


� Chapter 4, “Getting started with the tutorials” on page 91� Chapter 5, “Report Assistant” on page 99� Chapter 6, “Graph Assistant” on page 153� Chapter 7, “Power Painter” on page 199

Chapter 4, “Getting started with the tutorials” on page 91, lays the groundwork for the following tutorials. In Chapter 4, “Getting started with the tutorials” on page 91, we explain the tables that we are going to use in future chapters and we are going to set up security. If this has already been done for you, you can go straight to Chapter 5, “Report Assistant” on page 99.

The tutorials all use tables in the QWQCENT library. This library can also be referenced as the Century library. Century is the fictitious electronics company that is referenced throughout these tutorials. Specifically, we use the following tables:

� ORDERS� INVENTORY� PLANT� STORES

Part 2


ORDERS is the central table. It contains foreign keys or links to the other three tables. In our examples, you will see that we only directly refer to the ORDERS table. Thanks to the knowledge and understanding that DB2 Web Query has DB2 for i5/OS, the other three tables are automatically made available whenever ORDERS is referenced.

Map of tables in QWQCENT: Century library

In DB2 for i5/OS, the following foreign keys are defined in the ORDERS table:

� ProductNumber is the key to the INVENTORY table.� StoreCode is the key to the STORES table.� PlantCode is the key to the PLANT table.


Chapter 4. Getting started with the tutorials

In this chapter, we set up the System i platform and the user profiles in preparation for the tutorials that follow. We explain many of the steps in this chapter in more detail in Chapter 3, “DB2 Web Query fundamentals” on page 25. They are included here to give you complete, step-by-step instructions and to enable the tutorials to stand alone. To better understand items, such as the security, domains, and Hrefs, refer to Chapter 3, “DB2 Web Query fundamentals” on page 25.

4


Getting started

In preparation to start using the tutorials, you must authorize your user profile to create tables in the Common Domain. Then you must create a folder to store all your work. Finally you must define all the tables that we will query to DB2 Web Query through the Create Synonym process.

1. Before you start using the tutorials, register your user profile as a valid licensed DB2 Web Query user. Enter the following command:

CALL QWEBQRY76/WQADDLIC ‘USERPROFILE’

USERPROFILE references your System i user profile name and must be specified in uppercase letters.

For more details about registering and removing users see 3.3, “Registering named users” on page 29.

2. Incorporate the user profile to a group profile called MDUNTITLED. When you install DB2 Web Query, the system creates a group profile named MDUNTITLED. To create reports in the Common domain, you must be a member of MDUNTITLED. As a member of the MDUNTITLED group, you are authorized to create new reports in the default Common domain. For more details about security and authorizations see 3.5.3, “Assigning authority to users” on page 36.

3. Open a browser.

We tested these steps using both Internet Explorer and Firefox, but you should use Internet Explorer for the tutorials presented in this book.

4. Since DB2 Web Query uses port 11331, point your browser to the following URL (Figure 4-1):

http://systemi_name:11331/webquery

Figure 4-1 URL to initiate DB2 Web Query

Note: You can also use the CL Command ADDWQLUSR for the same purpose.

MRADMIN group: Being a member of the MRADMIN group instead of MDUNTITLED also works for these tutorials. The MRADMIN group profile allows a user to create new reports in all domains and to create new domains. This additional authorization is not required for the tutorials.


5. Enter your System i user ID and password (Figure 4-2).

Figure 4-2 Initial logon window

6. In the main DB2 Web Query home page, right-click Common Domain and select Properties to see the domain properties.

7. The Domain Properties window (Figure 4-3) opens. The Common domain is where we store our reports. One of the properties is the Href or the system identifier. For the Common domain, this is always untitled. By previously including yourself in the group MDUNTITLED, you now have developer authority (MD) in the domain UNTITLED. Close this window.

Figure 4-3 Common Domain properties

8. Expand Common Domain, right-click the Reports folder, and select New Folder.

Chapter 4. Getting started with the tutorials 93

9. In the New Folder window (Figure 4-4), create a new folder called Tutorials, which is where we store all of our work. Click Save.

Figure 4-4 Creating a new folder

10.Before you can create a report on the System i machine, you must tell DB2 Web Query which tables the users can query. DB2 Web Query then creates the metadata or synonyms to describe the selected tables. For more details see “Creating metadata” on page 48.

In the left navigation area (Figure 4-5), right-click Tutorials, and select Metadata.

Figure 4-5 Creating metadata

Note: Although you select a folder to enable the submenu that contains metadata, the metadata is not restricted to that folder. After the metadata is created, it is available system wide and to all reports.


11.In the Data Adapters window (Figure 4-6), right-click *LOCAL, which is the System i where the table resides, and select Create Synonym.


12.Enter the library where the tables reside. The library that we use throughout the tutorials is the QWQCENT library.

Tip: If you have other System i machines, logical partitions (LPARs), or independent auxiliary storage pools (IASPs) in your network, you can add a connection to these systems. Then the database names will be displayed under *LOCAL. Any of these remote DB2 tables are then available for use. These additional databases must be defined in the relational database directory table on the System i machine.

Note: There are three types of System i objects that you can query with the base DB2 Web Query product:

� DB2 cli refers to the majority of your tables created with either an SQL CREATE TABLE statement or by using data description specifications (DDS) and a CRTPF command.

� DB2 Heritage files refers to older tables that have multiple record types or multiple members. Tables described with this adapter use the OPNQRYF command on the System i machine. It then directs the query to the older, and typically slower, database optimizer (Classic Query Engine (CQE)).

� Query/400 imports the existing Query/400 definitions and converts them to both table and report definitions.


13.In the Select Synonym Candidates on DB2 cli panel (Figure 4-7), complete these steps:

a. For Restrict object type to, specify Tables, Views, and Other Objects.

b. Under Further restrict search to, select the Tables option. In this example, we clear the Views check box. This leaves us with a concise list that contains only our physical files or tables.

c. For Library, type qwqcent. Click Next.

Figure 4-7 Select Synonym Candidates for DB2 cli panel

SQL views: If you created SQL views or logical files and want to query them, you must leave Views selected. If this library is an SQL collection or schema, selecting Views also displays all of the SQL catalog views in the library.


14.In the Create Synonym for DB2 cli panel (Figure 4-8), complete these steps:

a. In the list of tables, select the Default synonym name check box to select all the tables that are currently displayed.

b. For Prefix, enter Cen_. This prefix is added to the beginning of the table names, so the users see, for example, Cen_ALERTS, CEN_ORDERS, and so on. If you have a long list of table names, using a prefix is one way to keep all related tables grouped together.

c. Select With foreign keys to bring in all tables that are directly related through referential integrity and foreign key support. For more details about foreign key support, see “Referential integrity” on page 57.

d. Click Create synonym.

Figure 4-8 Creating QWQCENT metadata

You have now authorized your user profile to create tables in the Common Domain. You have created a folder in which to store all your work, called Tutorials. You have also defined all the tables that we query to DB2 Web Query through the Create Synonym process. See Figure 4-9.

Figure 4-9 Synonym creation completion



Chapter 5. Report Assistant

Report Assistant provides an intuitive, graphical interface with drag-and-drop functionality. It enables you to quickly create a report in which you can:

� Sort data.� Include record selection criteria.� Add headings, footings, subtotals, and page breaks.� Apply a style template.� And so on.

When you use Report Assistant, DB2 Web Query creates a styled report that you can deploy on the Web without learning the complexities of any reporting language. With DB2 Web Query, you can specify input parameters to allow users to easily subset or filter their reports.

Report Assistant supports output in many different file types including PDF files, Microsoft Excel, and DB2 database files. Report Assistant’s tight integration with Excel includes the real-time creation of Excel spreadsheets with full styling, drill-downs, and formula capabilities. This support allows Excel power users to analyze their corporate data in a tool with which they are already familiar.

Many of the reports created in this chapter are prerequisites for the enhanced features that are discussed later in this book. Active Reports, which is for users who are not connected to a System i machine, and online analytical processing (OLAP)-enabled reports are both based on existing reports that are created in this chapter.

In this chapter, we go into detail about basic functionality that is common among the various DB2 Web Query components. For more details about the various options that are not discussed in the tutorials, use the help text.

5

Tip: If you have Developer Workbench installed, you will find the help text to be more extensive than the help text that is available in Report and Graph Assistant.


5.1 Tutorial overview

In this tutorial, we create the two reports, which are shown in Figure 5-1. The first report is a simple summary that shows revenue by product type. The second report is a more detailed report that calculates gross profit for each product category within a specific user-requested product type. Finally, we enable a user who is viewing the initial summary report to click the product type and automatically drill down to see the more detailed gross profit report.

In 5.5, “Joining tables (reference only)” on page 144, we demonstrate how to join two tables if you did not previously define the relationship using DB2 foreign key support. This section is for your reference only and is not part of the tutorial.

Figure 5-1 Final drill-down reports

5.2 Report creation

In our first task, we show the product revenue for each product type. We use the Century database that ships with DB2 Web Query in the QWQCENT library. You can find instructions for creating the metadata that defines this database to DB2 Web Query in Chapter 4, “Getting started with the tutorials” on page 91.

In this section we explain how to create a summary and detailed report. As we explain how to create this report, we illustrate how to perform the following tasks (among others):

� Define a report layout.� Apply date formatting.� Use selection criteria.� Define traffic lighting.� Generate subtotals and report headings.

Important: In order to complete the tasks in this chapter, you must have read and completed the steps in Chapter 4, “Getting started with the tutorials” on page 91.


5.2.1 Creating a summary report (RA1_Revenue)

To begin creating a summary report:

1. In the Reports navigation area, under Domains, expand Common Domain → Reports. Right-click the Tutorials folder, which is where you will store your report, and select Report Assistant.

2. In the window that opens, you see a list of available tables for you to query. Select the CEN_ORDERS table. As shown in the example in Figure 5-2, you can tell from the word Cluster in the description that this single definition covers multiple tables without requiring external joins. Click OK.

Figure 5-2 Initial table selection using Report Assistant

After you choose the CEN_ORDERS table, you see a list of all the column or field names on the Field selection tab. Continue with the next section to learn how to use these names to define a report layout.

5.2.2 Defining a report layout

As discussed in “Referential integrity” on page 57, the displayed fields in the Available fields list come from various tables. These tables are automatically brought in by DB2 Web Query

Note: Depending on the number of tables that were defined previously to DB2 Web Query, your list might contain only one table or it might contain many tables.

Tip: When you type the first character of the table name, you jump to the tables that start with that character. We recommend that, when you define your tables (create synonyms) to DB2 Web Query, you add a prefix to the tables so that they are logically grouped, for example, by subject area, collection, or library.

Chapter 5. Report Assistant 101

when you select the Foreign key option during the creation of the orders synonym or metadata. This results in the composite list of available fields.

To define a report layout:

3. To see the table or segment names, drag the sides of the window to widen it.

4. From the list of Available fields on the left, drag PRODUCTTYPE to the Sort by pane in the center of the window.

5. Again from the list of available fields, drag LINETOTAL to the Sum/Print pane on the right side of the window. LINETOTAL is the gross revenue for each line item on an invoice.

6. Select the Add grand totals to the end of the report check box. See Figure 5-3.

Figure 5-3 Report Assistant field selection

Icons for Available fields: You can choose to view your field names alphabetically regardless of which table they originated from, or you can view the fields for each table separately. Immediately above the field list are three icons. The first from the left is a calculator icon. The second icon is the dimension or hierarchy icon, which shows the fields within each individual table. The third icon is the list icon, which shows all the fields from all the tables in one long alphabetical list.

Tip: If you are using the Firefox browser, you might not be able to drag your fields. In this case, you must highlight the column in which you want to insert in your report and then click the add field icon in the appropriate pane (for example Sort by, Sum, and so on) to where you want to move the field.


7. At the top of the window, click the Run arrow to run your first report. Figure 5-4 shows the initial summary report.

Figure 5-4 Initial summary report

8. Save the report as shown in Figure 5-5:

a. Click the Save icon at the top of the window and select Save As.b. In the Save Standard Report window, enter the name as RA1_Revenue and click OK.

Figure 5-5 Report Assistant save as menu

It was easy to answer the question that was posed about the total revenue by product type, but we know that we can make this report look better and more meaningful for the users. Next we take a closer look at creating sum and detailed reports.

Tip: If you use an alpha field instead of LINETOTAL, the default sum option shows the value of the alpha field in the last record for each sort group or product type.


5.2.3 Sum and detail reports

In this section we look at the difference between the Sum and Print options on the Field selection tab. By default, we click the Sum button, which we used to produce the initial summary report. As requested, this report was aggregated on PRODUCTTYPE. The Print option turns off the aggregation and produces a detail report.

9. Before you run a detail report, limit the number of records that you want to read. There are more than 32,000 detail records in the orders file. We do not need to retrieve all of these records simply to make a point.

a. Click the Report options tab (Figure 5-6).

b. Under Content and generation, for the Limit the number of read operations performed during report generation field, type 100 for the number of records to read.

Figure 5-6 Limiting the records to read on the Report options tab

10.Click the Field selection tab.

11.Click Print instead of Sum.


12.Click the Run arrow at the top of the window. Then you see the report shown in Figure 5-7.

Figure 5-7 Report Assistant detailed print report

13.The Print option is for a detailed report that includes one row for each selected record. The Sum option sums or aggregates field values that are based on your sort column and consolidates the records. Since we want a summary report, complete these steps:

a. On the Field selection tab, click Sum.

b. Click the Report options tab.

c. On the Report options tab, for the Limit the number of read operations performed during report generation field, clear the value of 100.

14.We now enhance the report to make it more readable:

a. Click to highlight the LINETOTAL field in the Sum/Print pane.


b. Select the Show - Field options - LINETOTAL arrow near the bottom of the window.

The Field options display allows you to work with the properties for an individual field. You can describe standard and conditional formats based on values in your report. You can set up a field so that when a user clicks it they will drill down to a lower-level report. You can specify if you want the report to display the actual data in a field or if you want to see the average, minimum, or maximum value in the field instead. If you are working with a sort field you have additional capabilities to control the sort, add ranking columns, and control the subheadings and subfooting.

i. Click the ellipsis button (...) under the Format in report as field (Figure 5-8).

Figure 5-8 Report Assistant field options


ii. Under Select options (Figure 5-9), select Commas inclusion and Floating dollar to change the LINETOTAL field to be displayed with commas and a floating dollar sign.

Figure 5-9 Report Assistant change format window


c. On the Field selection tab, complete these steps:

i. Ensure that LINETOTAL is highlighted.

ii. Select the Show - Field options arrow.

iii. Click the Title tab. See Figure 5-10. Notice that the title is Revenue. This pane is where you enter your own, more meaningful column headings for users. In our case, the LINETOTAL column was defined to DB2 as having a heading of Revenue. DB2 Web Query imports the DB2 heading attribute into the metadata attribute Title.

Figure 5-10 Report Assistant new column headings


15.Add a count of the number of orders for each product type:

a. Drag ORDERNUMBER from the Available fields list on the left to the Sum/Print pane on the right.

b. Click the Show - Field options button to open the pane if it is closed.

i. Under Calculated as, select Count.

ii. Under the Format in report as field (Figure 5-11), click the ellipses button (...). Change the field format to integer seven with commas. The value is displayed in the field as I7C.

Figure 5-11 Report Assistant field calculation options

iii. Click the Title tab.

Note: If you do not see a long list of field options including Count, verify that your report is a summary report and not a detailed report. Verify that Sum is highlighted, and not Print.


iv. Change the heading as shown in Figure 5-12, with Order on the first line and Count on the second line.

Figure 5-12 Report Assistant column heading for count field


c. Using the up and down arrows (circled on the right in Figure 5-13) in the Sum/Print pane, move CNT.ORDERNUMBER above LINETOTAL.

Figure 5-13 Report Assistant field count

16.Click the Run arrow at the top of the window to run the report. Figure 5-14 shows the results of running this report. You have now created a report that includes a count of the number of orders for each product type.

Figure 5-14 Report Assistant RA1_Revenue report

17.Save your report.


5.2.4 Date formatting (RA2_XTab)

In this next example, we select only products that were sold in the year 2007, and across the top of our report, we add the quarter in which the products were sold.

We create two new fields based on ORDERDATE. One field contains the quarter, and the other field contains the year.

1. If you closed your report, on the DB2 Web Query home page, open the Tutorials folder, right-click the RA1_Revenue report, and select Open.

2. Next to the Field selection list, click the calculator icon ( ) to define a new field.

3. In the Define field creator window (Figure 5-15), complete these steps:

a. Enter the name of the field as Quarter.

b. For Format, select Q.

c. In the date field, either select or type ORDERDATE. The name must be in uppercase letters. This extracts the quarter data from ORDERDATE. Click OK.

Figure 5-15 Report Assistant defining a date quarter

Note: The new quarter and year fields will be available only in the current report. See 12.1.1, “Date Decomposition” on page 356, which explains how to modify the metadata and make these fields available globally. This task requires you to have the optional Developer Workbench feature.


4. Repeat the process starting with step 2 on page 112 to create the year field. In the Define field creator window (Figure 5-16), for fields, type Year. For Format, select YY. In the date field, either select or type ORDERDATE.

Figure 5-16 Creating a date year field

5.2.5 Selection criteria

In this section, we continue the procedure by filtering this report and selecting only the year 2007:

5. Click the Selection criteria tab.

6. On the Selection criteria tab (Figure 5-17), from the Available fields list, drag Year to the white pane on the right.

Figure 5-17 Report Assistant Selection criteria

Note: DB2 Web Query handles dates in an intelligent manner. However, much of this information, including the various date formatting options, is not well described in the help text. For this reason, we provide details about working with dates in “Date and time system variables” on page 530.


7. From the first drop-down list, select WHERE.

8. Select EQUAL to.

9. Click Select values.

10.In the window that opens (Figure 5-18), complete these steps:

a. Click the Values radio button.

b. DB2 Web Query looks for all distinct values in this field and presents them in a list. Select 2007.

c. Click OK.

Figure 5-18 Report Assistant selection values

WHERE or WHERETOTAL: Although we select the default WHERE, DB2 Web Query allows you to choose WHERE or WHERETOTAL. WHERE does the select at read time and only passes those records to the query that meet the specified condition. WHERETOTAL does the comparison after the records are retrieved, sorted, and aggregated. The selection is done on the aggregate value of the column. For example, if you want to select only the product types whose total revenue were greater than $100 million, use WHERETOTAL. If you use WHERE, you apply the selection on every individual order read and none meet this criteria.

Note: You can compare a field to the following types:

Constant A specific number

Parameter A variable whose values are either entered by a user or passed from another report

Field Another field in your table or tables

Values Selectable from a list of actual values in the selected field


5.2.6 Cross-tab report (RA2_XTab)

In this section, we continue our report creation process by creating a cross-tab report:

11.From the Available fields pane, drag Quarter to the Sort across pane on the right side of the window (Figure 5-19).

Figure 5-19 Report Assistant Sort across

Tip: With DB2 Web Query, you can store a list of products, regions, customers, and so on, that you are specifically interested in on your local PC. This list can be stored in a text file or in Excel. If you click the wizard icon ( ) next to the Constant prompt, you can browse your local PC. The values in that file then become the filter for your query.


12.Click the Run arrow at the top of the window to run your report. You will see the results as shown in Figure 5-20.

Figure 5-20 Report Assistant sort across output

13.At the top of the window, click Save → Save As. In the Save Standard Report window, save the report with the name RA2_XTab, click OK, and close it.

5.2.7 Creating a sample detail report (RA3_GP)

In this section, we create a parameterized report where the user selects, at run time, the product type that they want to query. We are also able to drill directly to this report from the RA1_Revenue report that we initially created.

1. Right-click the Tutorials folder and choose Report Assistant.

Tip: If your report shows only two quarters, remember that you must remove the 100 record limit. See step 13 on page 105.


2. In the window that opens (Figure 5-21), select the CEN_ORDERS table and click OK.

Figure 5-21 Report Assistant file selection


3. From the Available fields pane, drag PRODUCTTYPE and PRODUCTCATEGORY to the Sort by pane (Figure 5-22).

4. Drag LINETOTAL and COSTOFGOODSSOLD to the Sum/Print pane.

5. Under Hide - Field options, for Format in report as, click the ellipsis button (...). Add commas to the formatting of LINETOTAL and COSTOFGOODSSOLD.

6. Select the Add grand totals to the end of the report check box.

Figure 5-22 Report Assistant Field selection for detail report

Defining and computing fieldsIn this section, we create new fields and explain how to create new calculated fields in our report:

7. Click the calculator icon ( ), which is next to the Available fields heading, and select New define field (Figure 5-23). We create a gross profit field by subtracting the COSTOFGOODSSOLD from LINETOTAL.

Figure 5-23 Report Assistant New define field


8. In the Define field creator window (Figure 5-24), complete the following steps:

a. Enter a new field name of Gross_Profit.

b. There are three icons on the right side: . The first two icons display the list of fields in various formats including alphabetically and hierarchically. The function icon is used to display the precoded functions that are available. Try the different buttons.

Click the list icon ( ). This icon shows the list of available field names alphabetically.

c. Create the formula LINETOTAL - COSTOFGOODSSOLD. Double-click the field LINETOTAL, click the minus button (-) on the calculator pad or on your keyboard, and then double-click COSTOFGOOD.

d. Click the Format button and define your field as being an integer, 10 long, with commas and a floating dollar sign. It is displayed in the field as I10CM.

Figure 5-24 Report Assistant creating a defined field

e. Click OK.

Note: There are two ways to create calculated fields in DB2 Web Query. When you use the define field, you add the definition to the list of fields within the table. This field is calculated every time that a record is read and selected. Next to the Sum/Print heading is the wizard wand icon. You can use this icon to create a compute field. In this case, the field is not calculated until after the data is sorted and all aggregation is complete. Compute fields are often required for percentages and variances.

Tip: Field names in the Defined field creator panel must all be in uppercase.

Tip: When creating your own reports, ensure that the field length is large enough to handle the commas, dollar sign, and maximum digits possible.


9. Drag your new Gross_Profit field to the Sum/Print pane (Figure 5-25). Verify that the Gross_Profit field is highlighted.

Figure 5-25 Report Assistant formatting gross profit

10.Click the Show - Field options arrow near the bottom of the window.

a. Select the Title tab.

b. Change the column as shown in Figure 5-26, with Gross on the first line and Profit on the second line.

Figure 5-26 Report Assistant Show: Field options

If you define your DB2 tables and specify long names, aliases, or column headings, DB2 Web Query uses them.

Tip: There are times when you might create one define field based on a second define field. DB2 Web Query processes the defines in the order in which they are entered into the system. The define field must exist before it can be used in a secondary calculation. For more details about viewing the define order of the fields, see Appendix C, “Processing differences between the define and compute fields” on page 579.


5.2.8 Conditional styling (traffic lighting)

Next we highlight the gross profits that are $25,000,000 or more:

11.In the Sum pane, highlight Gross_Profit and open the Field options pane.

12.Select the Display tab (Figure 5-27):

a. Click Conditional styling.

Figure 5-27 Report Assistant Conditional styling option

b. In the Conditional styling window (Figure 5-28), click the wizard icon.

Figure 5-28 Report Assistant Conditional styling window

Tip: The IF THEN ELSE constructs allow you to use logic when creating virtual fields. For example, if you want to create your own count of the number of items sold in 2007, you can create a virtual field and use the formula:

IF Year EQ 2007 THEN 1 ELSE 0

DB2 Web Query prefers using EQ instead of =.


c. In the Edit condition window (Figure 5-29), you can define various filters or conditions for which you want to test your data:

i. Enter the name High_Profit for this condition. ii. For Field, select your test field of Gross_Profit. iii. For Relations, select the is greater than or equal to relationship. iv. Under Please select a value, enter a value of 25000000 (25 million).v. Click OK.

Figure 5-29 Report Assistant edit condition window

You can now enter another condition. For example, you might want to create a condition called Low Profit. This allows you to monitor your report and present the high and low in different colors.

d. From the list of conditions, highlight the one in which your are interested, High_Profit, and then click the add icon on the right side of the window to attach the condition to the Gross_Profit column. That was the column that we started with when we clicked the Conditional styling button (Figure 5-30).

Figure 5-30 Report Assistant attach conditional styling

Values button: The Conditional styling dialog allows you to compare Gross_Profit to another field in your table. If you click the Values button, you see a list of distinct values in the Gross_Profit column.

Note: Now that you have created a condition, you must attach it to your column for it to take effect. You can create one condition and attach it to multiple columns. For example, in a high-profit situation, you might want every column in the report to be highlighted.


13.Define the formatting of the Gross_Profit field when it meets the High_Profit condition:

a. Click the Font button.

b. To make the profit stand out, highlight it by choosing the Bold style and green for the background color (Figure 5-31). Click OK twice to return to the main reporting window.

Figure 5-31 Report Assistant styles window


5.2.9 Using variables in report headings and footings

In this section, we explain how to enhance our report by using variables in the report headings and in page footing:

14.Click the Report headings tab.

15.Under Page heading, enter Gross Profit by Product Category. For Page footing, type Prepared on &DATE at &TOD (Figure 5-32).

Figure 5-32 Report Assistant page headings and footings

Tip: For more information about using date and time variables within DB2 Web Query, see “Date and time system variables” on page 530.

Note: DB2 Web Query ships with a default style sheet that automatically formats headings and footings. To control the report formatting yourself, you must remove the default style sheet under the Report options tab.


16.Click Run at the top of the window to run your report. Figure 5-33 shows the resulting report. Notice how easy it is to see the high-profit items that are highlighted in green.

Figure 5-33 Report Assistant high profit report

17.Save your report. Click the Save icon at the top of the window and select Save As. In the Save Standard Report window, enter RA3_GrossPft and click OK.


5.2.10 Generating subtotals

We continue our example by generating subtotals for each product type:

18.In the Sort by field, highlight PRODUCTTYPE.

19.Make sure that the Show - Field options pane (Figure 5-34) is displayed.

a. Click the Sorting tab.b. Select Subtotal numeric sum/print fields.

Figure 5-34 Report Assistant subtotals

20.Click the Run arrow at the top of the window to run your report again. Figure 5-35 shows the results of running this report.

Figure 5-35 Report Assistant subtotalled report


21.To change the default subtotal heading, make sure that PRODUCTTYPE is highlighted.

22.In the Field options pane, click the new Subtotal tab (Figure 5-36).

23.Under Current Subtotal Text, type Subtotal for. Make sure that you leave a blank at the end because DB2 Web Query appends the product type to your heading.

Figure 5-36 Report Assistant new subtotal headings

24.Click the Run arrow to run the report. Figure 5-37 shows the results of running the report.

Figure 5-37 Report Assistant report showing new subtotal headings

Tip: By default, all columns are summed to create a total line. You can override individual columns and request that, instead of summing the column, the total line shows the result of calculations such as a count of values or the average of the values. Look at the options under Sum.


5.2.11 Sorting by an aggregate field

Often when users see the results of what they requested, they want something different. Instead of a product category within a product type sequence, the user now requests that we sort by gross profit within product type:

25.The Show - Field options pane for Gross_Profit does not contain a Sort tab. Drag Gross_Profit from the Available fields pane to the Sort by pane. Then move it below PRODUCTTYPE, as shown in Figure 5-38.

26.In the Show - Field options pane, click the Sorting tab and select the Total option. If you do not perform these steps, you will work with individual gross profit records instead of the aggregate or total of gross profit by product type.

Figure 5-38 Report Assistant adding additional sort criteria

27.If you do nothing else, your report contains the Gross_Profit column twice. Select the Display tab and click the Make this field invisible option to make Gross_Profit invisible (Figure 5-39).

Figure 5-39 Report Assistant make field invisible

Tip: If you run your report without selecting the Total option, you see that the report contains detail records instead of summary records. Therefore, it is important to remember to select the Total option.


28.Click the Sorting tab and select the Descending sequence.

29.Save your report.

30.Click the Run arrow to run the report. Figure 5-40 shows the results of running the report.

Notice that the records within each product type are in descending sequence by gross profit instead of product category.

Figure 5-40 Report Assistant sorting by a sum field

5.2.12 Adding ranking columns (RA4_Advanced)

We now show the gross profit ranking within the product type:

31.In the Sort by pane, highlight Gross_Profit.

32.Click Show - Field options if it is not in view.

33.Click the Ranking tab.

34.On the Ranking tab, select the Add Ranking column. Change the column as shown in Figure 5-41, with Gross on the first line, Profit on the second line, and Rank on the third line.

Figure 5-41 Report Assistant ranking


35.Save your report. Click Save at the top of the window and select Save As. In the Save Standard Report window, enter the name it RA4_Advanced and click OK.

36.Click the Run arrow at the top of the window to run your report. Figure 5-42 shows the results of running the report.

Figure 5-42 Report Assistant with a ranking column

5.3 Output options

In this section, we experiment with a few of the other report options within DB2 Web Query. The first one is on-demand paging.

To continue with this section, the RA4_Advanced report must be open. If you must open this report, on the DB2 Web Query home page, right-click the RA4_Advanced report and select Open.

Tip: If you want to produce a Top 10 report, use the ranking capability. From the Ranking tab, limit your ranked values to 10.


5.3.1 On demand paging

Choose the Report options tab. On this tab, select the On-demand paging option. Then rerun your report. See Figure 5-43.

Figure 5-43 Report Assistant On-demand paging option

Our sample report is not the best to show the on-demand paging feature, but you can see the options that are available with on-demand paging, as shown in Figure 5-44. Assume that our report was 201 pages long instead of one page long. When on-demand paging is enabled, DB2 Web Query saves your report on the System i machine and delivers one page of report output at a time to your browser, decreasing the amount of time that you wait for your report to be transmitted. The bulk of your report remains on the System i machine until you request it or close the report. On-demand paging allows you to jump directly to a specific page or to search for a string of information in the report.

Figure 5-44 Report Assistant On-demand paging output

Jump Next page Search


5.3.2 PDF output

Up to this point, all of our output has been to a browser. DB2 Web Query provides many additional options for output. In this section we look at the PDF output option.

Click the Report options tab. For Generate report as, select PDF - Portable Document Format (Figure 5-45). Then click the Run arrow to generate the report again.

Figure 5-45 Report Assistant PDF report options

Figure 5-46 Report Assistant PDF output

Note: To create a PDF report, no additional software is required other than the no-charge Adobe Reader. Adobe Acrobat Professional Edition is also not required.

Restriction: The report shown in Figure 5-46 was generated using an imported style sheet. If your PDF report scrolls onto two pages, you run into a known problem with the default style sheet. This problem is being investigated as this book goes to print. Not all style sheets have this problem.

See “I have my own style sheets that I want to use for my reports. How do I make them available from Report Assistant?” on page 508. This FAQ includes information about how to import style sheets. The report in Figure 5-46 was created using the “problue.sty” style sheet that ships with DB2 Web Query.


5.3.3 Excel output

There are multiple choices for outputting to Excel. An excellent option is to download your report to Excel, complete with formulas. With this choice, your totals and subtotals, as well as many compute fields, are represented as Excel formulas and are not downloaded as static values. This allows these columns to continue to be accurate even after the user modifies the worksheet.

You should still be in report RA4_Advanced. To generate output in Excel:

1. Click the Report options tab.

2. Select Excel w/formula from the first drop-down list.

3. Run your report.

Excel 97 versus Excel 2007: DB2 Web Query has the ability to create reports as Excel files. These can be created in two formats, Excel binary (XLS) files, referred to as Excel 97, and the newer XML-based Excel format (XHT), referred to as Excel 2000. Excel 2000 is really the first release that supported XML. DB2 Web Query cannot output directly in the new format of Excel 2007. However, Excel 2007 can read the Excel 2000 format.

With the XML-based Excel 2000, style sheets can be applied, cells can be formatted, traffic lighting or conditional styling can be passed, calculations can be rendered as formulas, and drill-downs are supported from within the resulting spreadsheet.

Note: There are many more output choices. Changing the second drop-down list changes the output choices in the first list. If you are not using a style sheet for your output, the difference between HTML and HTML with grid is whether your reports show with grid lines between the rows and columns. This option is overridden by your style sheet.


Figure 5-47 shows the output of this report in Excel. Notice the total for Audio in cell F9. If you look at the Excel input line, you see that this is represented as a formula as opposed to an actual value of $162,704,821. This is a helpful feature for users who want to download reports and then analyze the data and possibly delete or move rows of data. Having formulas instead of values in your report allows the total fields to adjust automatically. If you want to see the constant values downloaded, simply choose Excel 97 or Excel 2000 for your output.

Figure 5-47 Report Assistant Excel output

Tip: If gross profit is calculated as a compute field instead of a define field, it is also represented in the Excel spreadsheet as a formula.


5.3.4 DB2 database file output

One final output option that we investigate is the creation of a DB2 database file on the System i machine.


2. On the Report options tab, select Show database formats in the second drop-down list (Figure 5-48). This enters in the DB2 - DB2 database table in the first pane. It also shows a section in the bottom right corner of the window where you can specify the library and file or table name that you want to create.

Figure 5-48 Report Assistant output to a DB2 database file

Tip: You must have imported the metadata or created a synonym for your output table before you can use it as input to another query.


This time when you run your report, the records are inserted in the table that you specify. After the file insert is complete, you see a new window that tells you the number of records that were inserted into the DB2 table (Figure 5-49).

Figure 5-49 Report Assistant DB2 output confirmation

3. Set your output option back to HTML, as shown in Figure 5-43 on page 131, or reload your saved report.

We continue with the last steps of our example.

5.4 Additional report types

In this section we explore other types of reports, including:

� Reports that accept an input parameter, which are called parameterized reports� Reports with drill-down capabilities

Note: See 17.3.2, “Using output files for the next query” on page 443 for recommendations about converting Query/400 definitions that currently create temporary output files in QTEMP.


5.4.1 Parameterized reports

We are asked to print our RA4_Advanced ranking report for a single product type that is requested at runtime. To do this, we add an input parameter.

1. If you are still in your RA4_Advanced report, click the Selection criteria tab (Figure 5-50).

If you are not, open the RA4_Advanced report. On the DB2 Web Query home page, right-click the RA4_Advanced report and select Open.

2. From the Available fields pane, drag the PRODUCTTYPE field onto the empty white pane on the right.

3. Click Select values to define the parameter.

Figure 5-50 Report Assistant Selection criteria

4. In the EQ Values window (Figure 5-51), select Parameter and then click the Auto Prompt icon ( ).

Figure 5-51 Report Assistant parameter definition


5. Under Selection, ensure that Dynamic is selected (Figure 5-52).

For the Description field in the Name section, enter the prompt that you want the users to see. We use the default name for this parameter of PRODUCTTYPE.

Figure 5-52 Report Assistant Parameter properties

Note: Choosing Dynamic presents users with a distinct list of the current values of the column when the query is run. The Static option allows you to define a predefined set of values.

If you allow the users to select multiple values at run time, they will be able to use the Windows standard Ctrl and Shift keys to select multiple product types. For now, leave it to default to a single input value.


6. To make the drill-down report more understandable, place the product type in the report heading:

a. Click the Report headings tab (Figure 5-53).

b. Add the words “for Type” to the heading.

c. Select the Show - Field list arrow and drag PRODUCTTYPE to the end of the heading.

Figure 5-53 Report Assistant variable report heading


7. Since we know that this parameterized report is small and, in most cases, it fits on one browser page, remove the default page numbering. Click the Report options tab and for Page numbering select Off (Figure 5-54).

Figure 5-54 Default page numbering


8. Run the report. Figure 5-55 shows the results of running this report.

Figure 5-55 Report Assistant Output parameter report

9. Save and close this report.

We now have a report that can either accept a parameter passed by another report or prompt the user for their input.

5.4.2 Drill-down reports: Parent report (RA5_Child)

In this section we take our initial RA1_Revenue report and enable it to pass an individual product type to the report that we just created.

1. On the DB2 Web Query home page, right-click the RA1_Revenue report and select Open.

2. In the Sort by pane, highlight PRODUCTTYPE.

3. Click the Show - Field options arrow.


4. On the Display tab, click Drill down (Figure 5-56).

Figure 5-56 Report Assistant Drill-down option

5. In the next window (Figure 5-57) complete these steps:

a. Click the Execute procedure radio button. DB2 Web Query populates the list with your reports.

b. Navigate through the list until you find your RA4_Advanced report and select it.

c. In the Alternate comment for hyperlink field, add a comment for users to see when they hover over the Product Type field.

d. Click Add.

Figure 5-57 Report Assistant Drill-down window


e. In the Drill-down parameter window (Figure 5-58), complete these steps:

i. In the Parameter name field, type the same name as the parameter that the drill-down report is expecting. In this case, type PRODUCTTYPE.

ii. Under Parameter value, select the Field option, then select the field that you want passed into the variable PRODUCTTYPE. Select the PRODUCTTYPE field. Click OK.

Figure 5-58 Report Assistant drill-down parameter window

6. Run your report. Figure 5-59 shows the results of running the report.

7. In the parent or top-level report, the product types are highlighted in blue, indicating that they can be selected and that you can then drill-down to a more detail report. Click Audio to drill down to see more information.

Figure 5-59 Report Assistant parent (summary) and child (drill-down) reports

8. Save your report:

a. Click the Save button at the top of the window and select Save As.b. In the Save Standard Report window, enter the name RA5_Child and click OK.

9. Close the report and close Report Assistant.


5.4.3 Report properties

To view the properties of a report, on the DB2 Web Query home page, navigate to the RA4_Advanced report, right-click, and select Properties. The results are shown in Figure 5-60.

The General tab of the Properties window shows the creation date, the domain, and most importantly the Href or file name on disk. The Detail tab show all the tables and columns that are used in your query. You also see your sorting details, filtering criteria, output format, and any joins that you might have explicitly defined.

Figure 5-60 Report Assistant report properties

You have now completed this tutorial.

5.5 Joining tables (reference only)

You might have noticed that we never needed to join any tables together even though we looked at data from multiple tables. As previously discussed, this is because the tables were defined to DB2 with foreign key constraints.

If either of the tables do not have foreign keys defined or you choose not to include the foreign keys when you created the metadata, you must create your joins manually. In this section we explain the process that you must follow.


After you select your main table to query, click the Join options tab to specify any additional tables that you want to access. You must click New to create a new join. In the window that opens, highlight the table in the list to which you want to join and click OK. See Figure 5-61.

Figure 5-61 Report Assistant join options

Next you must define the actual join criteria. You tell DB2 Web Query which field from each table you want to use for your join. See Figure 5-62.

Figure 5-62 Report Assistant join definition


You must remember to click Save & Create. If you forget to do this and navigate away from this page, your join is not created.

After you save and create the first join definition you can click New and proceed to define a second join if you would like.

When you click the Field selection tab, you see that the fields from both tables are available for use (Figure 5-63).

Figure 5-63 Report Assistant secondary table field

Notice that the columns from the secondary table are in a different color than the columns from the primary table. This is a quick visual check to help identify the different source tables. If you select the tree icon (between the calculator and the spreadsheet), you can see the fields listed in physical sequence by table.

Join types:

� Unspecified: This option was created for compatibility with prior versions. We recommend that, instead of this choice, you select the appropriate options (Inner Join, Left Outer Join, Multiple Instances, Single Instances).

� Inner Join: An inner join combines rows from both tables where there is an exact match between the join fields.

� Left Outer Join: This option retrieves records from both primary and secondary tables, including all records from the left table (primary) and any records from the right table (secondary) where the condition values match. If there are no matching values in the secondary table, the join still retrieves the records from the host table.

� Multiple Instance: A one-to-many join structure that matches one value in the host data source to multiple values in the cross-referenced field. Joining an employee ID in a company's employee data source to an employee ID in a data source that lists all the training classes offered by that company would result in a listing of all courses taken by each employee or a joining of the one instance of each ID in the host file to the multiple instances of that ID in the cross-referenced file.

� Single Instance: A one-to-one join structure that matches one value on the host data source to one value in the cross-referenced data source. Joining an employee ID in an employee data source to an employee ID in a revenue data source is an example of a unique join.


5.6 Creating a report over a stored procedure synonym

In “Stored procedure synonyms” on page 52, you learned how to create a synonym over a stored procedure. The stored procedure added a row to an audit table and returned a result set from the HR table. In this section you create a report over this synonym by taking the following steps:

1. Use Report Assistant to create a new report in your Tutorials folder.

2. From the list displayed, select the stored procedure synonym CEN_HR_TABLE_AUDIT, as shown in Figure 5-64.

Figure 5-64 Select stored procedure synonym

The Report Assistant tool is displayed. Notice that the columns under the list of available fields have two different segment names: ANSWERSET1 and INPUT (Figure 5-65). The columns in the ANSWERSET1 segment are the columns returned in the stored procedure’s result set. This means that they can be used as output fields in the report. Any columns in the INPUT segment can only be used as input parameters to the stored procedure.

Figure 5-65 Different segments from stored procedure synonym

Tip: If you switch to tree mode and hover over a field name, additional information pertaining to that field is displayed.


3. Create a new input parameter to the report by dragging the INPLANTCODE column from the list of available fields to the Screening conditions area. Click Select Value, as shown in Figure 5-66.

Figure 5-66 Create input parameter for report

4. Select Parameter and make it a prompt control (drop-down list) by clicking the Auto Prompt icon, as shown in Figure 5-67.

Figure 5-67 Set up prompt control


5. To populate the list of plant codes to be displayed in the prompt control, you can select a different data source. Because these values are stored in the ORDERS cluster, select CEN_ORDERS from the list of values for Data Source. This repopulates the list of fields displayed. Find and select PLANTCODE from this list and click OK. See Figure 5-68.

Figure 5-68 Specify data source and field to populate prompt control


6. Click OK again. Your Selection Criteria should look like the example in Figure 5-69.

Figure 5-69 Input parameter to pass to stored procedure


When run, this report prompts the user for an input parameter. The selected value will be passed as an input parameter to the stored procedure.

7. Next finish your report by doing the following (as displayed in Figure 5-70):

a. Sort by columns LASTNAME, FIRSTNAME, STATUS, and PAYSCALE.

b. Sum the SALARY column and specify formatting of comma inclusion and floating currency.

Figure 5-70 Finish stored procedure report

8. Save your report as HR Salary Report.


9. Run the report. Select a value from the Plantcode prompt control and click Run, as shown in Figure 5-71.

Figure 5-71 Run stored procedure report

10.As a final step, verify that running the report above resulted in a row being added to the audit log. From any SQL interface, run the following SQL statement:

SELECT * FROM rptaudlog ;

You should see a row that was logged as a result of running the HR Salary Report through DB2 Web Query:

2009-09-01 09:54:11.896625 HR Salary Report COBBG

5.7 Report Assistant summary

You have now completed the first tutorial and created a few different reports. In many of the remaining chapters you modify the reports that you created in this chapter. We do not repeat information that is similar between the different components in some cases, such as joining tables. In other examples, we list the steps but in far less detail. If you forget how to accomplish a function, return to this chapter for a refresher of the steps.


Chapter 6. Graph Assistant

Graph Assistant provides a wide variety of graph types and graphing functionality to allow users to choose how to present their data in the best possible format. The available graph types range from a variety of bar and line charts to histograms and area charts, stock charts, gauges for key performance indicators, and much more. You can find additional details about the graphing facility in the help text.

In this chapter we continue with the same Century database used in the previous tutorials. In this chapter we complete the following tasks:

� Create a simple bar chart that shows revenue by product type within country. We drill down from this graph to the detail report that we created previously with Report Assistant. We then modify this graph to be a dual axis bar and line chart that accepts country as an input parameter.

� Create a line chart that shows revenue trending over time. The users can specify the time range that they want to see.

� Create multiple pie charts with traffic lighting or conditional styling based on a calculated field.

6


6.1 Tutorial overview: bar chart

In this exercise we initially create a bar chart that allows the user to drill down to a previous report (Figure 6-1).

Figure 6-1 Completed bar chart with drill down


We then modify this bar chart to create a dual axis bar and line chart that accepts country as an input parameter. See Figure 6-2.

Figure 6-2 Modified chart by adding a gross profit line

Chapter 6. Graph Assistant 155

6.2 Creating a simple bar chart with drill-down capabilities (GA1_Bar)

To create a simple bar chart with drill-down capabilities:

1. Right-click the Tutorials folder and select Graph Assistant.

2. In the window that opens (Figure 6-3), select the same CEN_ORDERS table that we used in the previous tutorials. Click OK.

Figure 6-3 Starting Graph Assistant


3. In the Graph Assistant, click the Graph types tab (Figure 6-4). On this tab, complete the following steps:

a. Under Select from the following graph types, look at the various chart types that are available. For graph type, choose a Bar chart type.

b. For each chart type, there are many variations shown in the Graph Styles pane. For Graph Styles, select Clustered.

c. Look at the various templates under Apply template. Select Cylinder on grey.

Figure 6-4 Graph Assistant Graph type selection


4. Click the Field selection tab (Figure 6-5).

Figure 6-5 Graph Assistant Field selection

5. Define the fields that represent the x and y axis for the chart:

a. Drag LINETOTAL to the Sum pane. This is our Y axis.

b. Drag COUNTRY to the X axis field.

c. Drag PRODUCTTYPE into the separate graph area field. By default, this produces one chart for each separate plant.

6.2.1 Adding multiple bars to one chart

To add multiple bars to one chart:

6. On the Field selection tab, under the Graph fields section, ensure that PRODUCTTYPE is still highlighted.

7. Click the Show - Field options for PRODUCTTYPE.

8. Select Merge graphs into a single graph. Instead of having a graph for each product type, this option merges the graphs so that each type is a separate bar within each country.


9. Click the Headings tab (Figure 6-6). Graphs can have headings both at the page level and at the individual chart level. Click the Graph tab. Under Chart title, type Revenue by Product Type, and for Chart subtitle type Country Comparison.

Figure 6-6 Graph Assistant Chart titles

10.Save your graph as GA1_Bar and then run it. Figure 6-7 shows the results of running this report.

Figure 6-7 Graph Assistant Revenue by Product Type Chart


6.2.2 Adding a drill down to a chart

Now that we have our chart, we want users to have the ability to double-click any of the bars and drill down to the detailed product type report that we created earlier:

11.Return to the Field selection tab and highlight LINETOTAL.

12.Under Field options - LINETOTAL, on the Display tab (Figure 6-8), click Drill down.

Figure 6-8 Graph Assistant Drill-down button

13.In the next window that opens (Figure 6-9), complete these steps:

a. Select Execute procedure and a list of your reports is populated in the top white pane.

b. Navigate to and select the RA4_Advanced report that you created earlier. After you select your procedure, the Add button becomes available.

c. Click Add to add the parameter that you pass from this report to the RA4_Advanced report.

Figure 6-9 Drill-down selections


14.In the next window (Figure 6-10), complete these steps:

a. For Parameter value, select Field and then select the field that you want to pass as the parameter value, which is PRODUCTTYPE.

b. Under Parameter name, type PRODUCTTYPE. This name must match the name that the child report is expecting to be passed. We defaulted our parameter name to equal the input column name of PRODUCTTYPE. Click OK.

Figure 6-10 Graph Assistant parameter passing

Drill down: When you drill down from one report to another, the child report expects a parameter. In our case, this is the PRODUCTTYPE parameter that is linked in the gross profit report to the PRODUCTTYPE field. In the parent report or graph, you indicate where users can drill down. In this graph, the users can drill down on any LINECODE or bar. When they click a bar, we tell the system that we want the RA4_Advanced report to run. We also indicate that we are going to pass in the PRODUCTTYPE field that is referenced by the selected bar. We do this by passing the value as a parameter called PRODUCTTYPE. Since this is the name of the parameter that the Advanced report was expecting, it accepts the value and executes the report.


15.Save and then run this graph. Figure 6-11 shows the results of running this report.

16.Move over the bars with your mouse. Notice that the cursor changes from an arrow to a hand. The hand indicates that you can drill down in this area. When you hover over a bar, a window opens that shows all the details of the bar. First you see the product type, then the country, and lastly the revenue or line total.

Figure 6-11 Graph Assistant drill down from chart to report

6.3 Creating a dual axis bar and line chart (GA2_Parm)

In this exercise, we change COUNTRY from a set of bars to an input parameter. We also add gross profit as a line chart on top of our existing bar chart. Gross profit has its own Y axis. This way we can see the relationship between our revenue and the profit that each product generated.

1. If you closed the bar chart that you just created, navigate to the Tutorials folder, locate GA1_Bar, right-click the report name, and click Open.

2. Click the Field selection tab.

Note: In this drill-down example, we pass the product type to the child report. We could design the report to accept both country and product type. If we do this, when the user clicks the same bar, they can pass the country name as well as the product type as filters or parameters to the Gross Profit report (RA3_GrossPft).


3. Modify the existing graph slightly, as shown in Figure 6-12:

a. In the Create a separate graph for each value of this field, remove PRODUCTTYPE by highlighting the entry and clicking the red Sort Across Remove (X) button.

b. Change COUNTRY in the Field value plotted on X axis field to be PRODUCTTYPE. You can choose one of the following options:

• Delete COUNTRY by clicking the Sort Across Remove (X) button.• Drag PRODUCTTYPE on top of COUNTRY, which does an automatic replace.

Figure 6-12 Changing X axis columns

4. Add COUNTRY as a parameter:

a. Click the Selection criteria tab (Figure 6-13).

b. Drag COUNTRY from the Available field list to the pane on the right.

c. In this case, the defaults of WHERE and EQUAL TO are appropriate since we want the user to select or specify a single country.

d. Click Select values.

Figure 6-13 Creating a parameter for COUNTRY

Note: At any time during development, you can click Run to see how your chart looks up to this point. Using the Update button on the graph preview is useful during development. If you closed your graph preview box, click the Graph Type tab and select Show Graph Preview.


e. In the next window (Figure 6-14), select Parameter and click the Auto Prompt icon.

Figure 6-14 Parameter Auto Prompt

f. In the Parameter Properties window (Figure 6-15), complete these steps:

i. Change the prompt that the user sees. For Description, type Select Country:.ii. For the remainder of the window, select the default options. Click OK.

Figure 6-15 Details about COUNTRY parameter

5. Save your report as GA2_Parm.

We just created a simple bar chart that prompts the user for country, which you can try to see how it works. Remember that you can run your report or update the graph preview at any time.


6.3.1 Adding a second Y axis

Redefine the graph as one that supports a second Y axis:

6. Click the Graph types tab (Figure 6-16). Change the Graph Styles from Clustered to Dual-Axis Clustered.

Figure 6-16 Selecting a Dual-Axis Clustered graph type

7. Superimpose Gross Profit as a line on top of the existing bar chart. Since Gross Profit does not exist in the field list, create it:

a. Click the Field selection tab.

b. On the Field selection tab, click the calculator icon and select New define field (Figure 6-17).

Figure 6-17 Selecting New define field

c. In the window that opens (Figure 6-18), complete these steps:

i. For Field, type Gross_Profit.

ii. To define the field, you can type the formula manually or open the field list pane to the right-click then double-click the field names to move them over. Enter the following formula:

LINETOTAL - COSTOFGOODSSOLD

Now Gross_Profit is available for us to use.

Figure 6-18 Calculating gross profit


8. Drag Gross_Profit to the Y axis panel below LINETOTAL.

9. Click Show → Field options → Gross_Profit.

10.Click the Visualize subtab (Figure 6-19) and complete these steps:

a. For Force the values on this field to be plotted as, select Line. b. For Place this field on the specified axis, select 2nd axis.

Figure 6-19 Adding a second Y axis for a line chart

11.Ensure that there is a heading for the graph:

a. Click the Headings tab.

b. Click the Graph subtab.

c. Under Chart title, the graph title is Revenue by Product Type. We do not need a subtitle for this graph. See Figure 6-20.

Figure 6-20 Graph headings

12.Save and run your graph.


13.In the report that is displayed, for Select Country, select Germany and you will see the results shown in Figure 6-21.

Figure 6-21 Dual axis bar and line chart with prompting


Modifying graph properties and settingsOverall the graph looks like what we wanted. The one potential concern is ensuring that the users can quickly and easily read the values on the Y axis. Let us simplify this for our users:

14.Click the Properties tab.

15.On the Properties tab, select the Y axis subtab (Figure 6-22).

a. Both the revenue and profit are large numbers in the millions. From the drop-down list, select Y1 axis to format the product type y axis values.

b. For Value format, select $10M to show the Y (gross profit) axis as millions of dollars.

Figure 6-22 Formatting Y axis values


16.Save and run your report. Figure 6-23 shows the result of the chart.

Figure 6-23 Dual axis bar/line chart with prompting

17.Close Graph Assistant.

With these minor changes, our users are now less likely to misinterpret the dollar values.


6.4 Creating a revenue trend over time chart (GA3_Line)

In this exercise, first we create a simple line chart that spans two years (includes all our data). Then we modify this chart to allow the user to specify the time range in which he is interested (Figure 6-24).

Figure 6-24 Trending report with a variable date range


6.5 Creating a line graph

To create a line graph:

1. Right-click your Tutorials folder and select Graph Assistant (Figure 6-25).

2. In the window that opens (inset in Figure 6-25), select the table Cen_Orders and click OK.

Figure 6-25 Creating a new graph


3. In the next window, click the Graph types tab.

4. On the Graph types tab (Figure 6-26), under Select from the following graph types, select Line. Then under Select from the following Graph Styles, select Absolute.

Figure 6-26 Selecting a graph type for a line chart

5. To show product revenue trending by month, you must plot one point for every month for each product. To do this, convert the date field from year, month, and day to a field with just the year and month.

a. Click the Field selection tab.

b. Click the calculator icon and select New define field (Figure 6-27).

Figure 6-27 Defining a new field


c. In the Define field creator window (Figure 6-28), complete these steps:

i. For Field, type MthYr.

ii. In the pane below Field, where you define the formula for the new field, type ORDERDATE, which is the name of the date on which MthYr is based.

iii. In the Format field, type TMYY.

T means that the month or day immediately following will be represented as uppercase text. A single Y means that you want to display a two-digit year, but YY means that you want to display a four-digit year.

An example of a MthYr value is Jan, 2007. If we want to place the year first, we specify a format of YYTM. DB2 Web Query is powerful when it comes to working with date and time fields. See “Date and time system variables” on page 530 for many of the different ways that you can work with date and time fields. Click OK.

Figure 6-28 Creating a date field of month and year


d. On the Field selection tab (Figure 6-29), complete these steps:

i. Drag MthYr to the Field value plotted on X axis (our main X axis) pane. Drag LINETOTAL to the Sum/Print pane under Field value plotted on Y axis. Under Create a separate graph for each value of this field, specify PRODUCTTYPE.

ii. Click Show - Field options - PRODUCTTYPE. Select the Merge graphs into a single graph option.

Figure 6-29 Creating a line graph with multiple lines

Tip: You must place LINETOTAL in the Sum/Print pane before you can drag PRODUCTTYPE to the Create a separate graph for each value of this field pane.


6. Since an entry on an axis of “Jan, 2007” is obviously a date, remove the heading or label for MthYr from the graph (Figure 6-30):

a. Under Field value plotted on X axis, highlight MthYr.

b. Click Show - Field options - MthYr and under X axis field label, delete the label MthYr.

Figure 6-30 Removing the X axis field label

7. Save your report as GA3_Trend.


8. Run your report. Figure 6-31 shows the results of running this report.

Figure 6-31 Two-year product revenue trend lines

9. Change the X axis to rotate the text and make it look better:

a. Click the Properties tab and then click the X axis subtab.

b. Click Style labels.


c. In the X Axis Properties window (Figure 6-32), complete these steps:

i. Under Set Style for, select Data.

ii. Some of the options initially are unavailable because a default style sheet is in effect. Select the Because automatic arrangement is turned on, certain style options are disabled. Check here to override defaults check box.

iii. For Text rotation, select 45-degree bottom to top. Click OK.

Figure 6-32 45-degree x axis labels


10.Save and run your report. Figure 6-33 shows the result of running this report.

Figure 6-33 Report with 45-degree X axis labels

6.5.1 Adding a date range filter to a line graph

Up to this point, we plotted one point for every month/year combination in our data. This is not practical because the history grows in size. Next we select a specific range to display. We display one year’s worth of data starting with orders that were generated on July 1, 2006, and ending with orders received on June 30, 2007. After we look at the options for hardcoding a range we look at how the user can specify an ad hoc range.


To filter the dates:

11.Click the Selection criteria tab (Figure 6-34).

12.Drag MthYr to the Screening conditions pane on the left.

13.In the Screening conditions pane, complete these steps:

a. To select the records as we read them, use the WHERE default as opposed to WHERETOTAL.

b. As stated previously, our range is all orders inclusively from July 2006 to June 2007. For our first WHERE clause, for MthYr, select GREATER THAN or EQUAL to and then click Select values to enter the date.

c. In the GE Values window, select Constant and type 072006.

Figure 6-34 Selection criteria for date


14.Drag MthYr to the Screening conditions pane (Figure 6-35).

15.Notice that, by default, the two conditions that you define will be ANDed together.

16.In the Screening conditions pane, complete these steps:

a. Select LESS THAN or EQUAL to and click Select values.

b. In the LE Values window, select Constant and type 062007.

You have now defined a range where 072006 <= MthYr <= 062007.

Figure 6-35 Selecting date ranges

17.Save and run your report. Figure 6-36 shows the results of running this report. Notice that our report now starts with July and ends with June.

Figure 6-36 Specific date range


Here are a couple of options that achieve the same results:

– Option 1

i. Remove the selection criteria that we specified. In the Screening conditions pane (Figure 6-37), select both conditions. Then click the red X under the text Screening conditions to remove them.

Figure 6-37 Removing screening conditions

ii. Using the same steps as we did with MthYr, this time drag ORDERDATE to the Screening conditions pane and specify the full date (Figure 6-38).

Figure 6-38 Using ORDERDATE column

iii. Run your report. It should look exactly the same as our previous report.


– Option 2

i. Remove the previous screening conditions.

ii. Drag ORDERDATE to the Screening conditions pane.

iii. Select FROM - TO and click Select values.

iv. In the FROM-TO values window (Figure 6-39), for the From criteria, type 20060701, and for the To criteria, type 20070630.

Figure 6-39 Date From-To option

v. Run your report. Again the same report is generated.

6.5.2 Adding a user-specified date range parameter

In this next example, we allow the user to specify their date range instead of forcing one on them:

18.Remove your existing Screening conditions.

19.Drag ORDERDATE to the Screening conditions panel.


20.In the Screening conditions pane (Figure 6-40), complete these steps:

a. Select GREATER THAN or EQUAL to and click Select values.

b. In the GE Values window (Figure 6-40), instead of specifying a constant, select Parameter. Enter a parameter name for your user such as FROM_DATE. Click OK.

Figure 6-40 Creating a date parameter

21.Again drag ORDERDATE to the Screening conditions pane.

22.In the Screening conditions pane (Figure 6-41), complete these steps:

a. Select LESS THAN or EQUAL to. Click Select values.b. In the LE Values window, select Parameter and name the parameter TO_DATE.

Figure 6-41 Defining parameters for a date range


23.Save and run your report. Figure 6-42 shows the results of running this report.

Figure 6-42 Trend graph with variable date range

24.Try various date combinations.

In this exercise, we saw multiple ways to hard code a date range and how to have the user specify a variable date range.


6.6 Working with pie charts (GA4_Pie)

In this exercise, we create a single chart that contains multiple pie charts, one for each year. We then add conditional styling or traffic lighting to our pie charts based on comparisons with calculated values. See Figure 6-43.

Figure 6-43 Yearly pie charts with conditional styling or traffic lighting

6.7 Creating a product type pie chart for each year

To create a product type pie chart for each year:

1. Navigate to your Tutorials folder, right-click, and select Graph Assistant.

2. In the window that opens, choose the Cen_Orders table and click OK.

Audio (25%)

Camcorders (28%)Revenue

Cameras (12%)

Office (2%)

Video (33%)

2006 2007

Video (34%)

Office (2%)

Cameras (12%)Revenue

Camcorders (29%)

Audio (24%)

Red pie slices indicate an average markup of less than 35% Red pie slices indicate an average markup of less than 35%


3. On the Graph types tab (Figure 6-44), under Select from the following graph types, select Pie. For Select from the following Graph Styles, select Basic.

Figure 6-44 Selecting a graph type

In this example, we create a pie chart for each year in our data. We do not currently have a field that contains just the year.

4. Click the Field selection tab.

5. Click the calculator icon and select New define field.


6. In the Define field creator window (Figure 6-45), for Field, type Year and for Format, type YY. Remember that this creates a four-digit year (for example, 2007). In the pane under Field, specify that the field is to be based on ORDERDATE. Click OK.

Figure 6-45 Creating a year field

Tip: If you are tired of splitting ORDERDATE into its various components for each report, make sure that you continue to progress to the tutorial in 12.1.1, “Date Decomposition” on page 356. This tutorial shows how to automatically break down a date and make the components available to all reports.


7. Click the Field selection tab to define the fields used in the pie chart. See Figure 6-46.

8. Drag PRODUCTTYPE to the Field value plotted on X axis pane. This means that we will have a pie slice for each product type.

9. Drag LINETOTAL to the Field value(s) plotted on Y axis box. This means that the product type pie slices will be proportionately sized based on the LINETOTAL summed values.

10.Drag Year to the Create a separate graph for each value of this field pane. By default, this creates a separate graph for each value in Year.

11.Click Show - Field options - Year.

a. Select the Display graph in number of columns option.

b. Type a value of 2 next to the Display graph in number of columns option to indicate that you want two graphs across the page. If you had six different years, these settings would create six pie charts in a 2x3 layout. If you specified six across, you would have six small pie charts across the page in a single row.

Figure 6-46 Pie chart field definitions

12.Run or preview your chart. The graph is essentially complete.


13.Often a graph is easier to read without a legend. Instead we want the labels directly on or next to the pie slices for easy readability. Click the Properties tab and the Pie subtab (Figure 6-47).

a. In the Graph preview window, select the Automatic update option. Whether you permanently work in Automatic update mode is strictly a performance question.

b. While viewing the Graph preview window, select Show pie labels.

c. Try selecting the different option combinations from both columns to see the results. In the end, select the Labels only and Slice label and % value options.

d. In the Graph preview window, clear the Automatic update option.

Figure 6-47 Automatic update for Graph preview

14.As you can see in the Graph preview, you still see the legend, which duplicates the information on the slice labels. To remove the legend from your pie chart, click the Properties tab and the Settings subtab.

Tip: If you closed or lost your Graph preview window, click the Graph types tab and select Show graph preview.


15.On the Settings tab (Figure 6-48), clear the Show legend option.

Figure 6-48 Legend removal

16.Tell DB2 Web Query the size to make each of our pie charts:

a. Click the Properties tab and the Options subtab.

b. On the Options tab, select Custom size. For Horizontal, type 400 pixels, and for Vertical, type 300 pixels.

Figure 6-49 Specifying custom graph sizes


17.Save your chart as GA4_Pie and run the report. Figure 6-50 shows the results of running this report.

Figure 6-50 GA4_Pie chart

As we expect, notice how similar the graphs look compared to the Graph preview window in Figure 6-47 on page 189.

6.8 Conditional styling or traffic lighting a graph

The last area that we want to address in our graphing tutorial involves having segments of the graph highlighted based on a condition in our data. It is straightforward to highlight LINETOTAL when LINETOTAL is greater or less than a predefined number. In this case we want to highlight the pie segments based on the profit margin of that segment. Specifically, if the markup that the product is sold for is lower on average than corporate standards, we want to highlight this.

We must calculate the average markup after we aggregate our data. Summing an average calculated at record input time gives us inaccurate results. As previously discussed with DB2 Web Query, you can specify whether you want a new field calculated as records are read or after the input records are processed and aggregated. This processing sequence is described in more detail in Appendix C, “Processing differences between the define and compute fields” on page 579.

Audio (25%)

Camcorders (28%)Revenue

Cameras (12%)

Office (2%)

Video (33%)

2006 2007

Video (34%)

Office (2%)

Cameras (12%)Revenue

Audio (24%)

Camcorders (29%)


1. If you are still in your GA4_Pie report, click the Field Selection tab (Figure 6-51).

If this report is not open, open the GA4_Pie report. On the DB2 Web Query home page, right-click the GA4_Pie report and select Open.

2. To create a compute field, select the Wizard icon next to the Print button.

Figure 6-51 Initiating the compute field wizard

Note: DB2 Web Query calls a new field calculated at input time a define field. A field that is calculated after all aggregation is done is called a compute field. See Figure C-1 on page 579 for more details.


3. In the Compute field creator window (Figure 6-52), for Field, type MARKUP. Specify the formula in the pane below Field. Type the following text in the pane:

((LINETOTAL - COSTOFGOODSSOLD) / COSTOFGOODSSOLD) * 100

You can either type the field names or select them by double-clicking the names on the left. The DB2 field names must be in uppercase.

Click OK.

Figure 6-52 Creating a compute field

While MARKUP is a field that we must reference in our conditional styling, we do not want to display a graph of MARKUP data.

4. Under Field value(s) plotted on Y axis, highlight MARKUP.

5. Click Show - Field options (Figure 6-53). On the Display tab, select the Make this field invisible option. This makes MARKUP available to the report but does not display it on the graph.

Figure 6-53 Making a field invisible


6. Define the pie slices that you want to highlight (Figure 6-54):

a. Highlight LINETOTAL under Field value(s) plotted on Y axis.

b. Click Show - Field options.

c. Click Conditional styling.

Figure 6-54 Conditional styling

d. Click the Add wizard icon (Figure 6-55).

Figure 6-55 Conditional Styling Add wizard


e. We want to highlight the pie segments or slices that have a lower markup than our company standard of 35% (Figure 6-56).

i. Give this condition the name of Low_Markup.ii. For Field, select MARKUP. iii. For Relations, select is less than or equal to. iv. For Please select a value, type the value of 35. Click OK.

Figure 6-56 Creating a conditional styling condition

f. Attach the condition definition to LINETOTAL and define what happens when this condition is satisfied.

i. Highlight Low_Markup and click the Add Condition icon. See Figure 6-57.

Figure 6-57 Attaching a condition definition


ii. Click the grey color indicator box (circled in Figure 6-58).

iii. In the Color window (Figure 6-58), select the color that you want the pie slice when the slice meets the Low_Markup condition. In this example, choose Red.

Figure 6-58 Conditional styling highlighting


7. When modifying a report by applying filters or using traffic lighting, we recommend that you indicate this information on the report itself. You typically do this via a subheading or a page footing or footnote.

a. Select the Headings tab and click the Graph subtab (Figure 6-59).

b. Under Chart footnote, type Red pie slices indicate an average markup of less than 35%.

Figure 6-59 Explanatory chart footnote

8. Save your report and run it. Figure 6-60 shows the results of running this report.

Figure 6-60 GA4_Pie low markup charts

Audio (25%)

Camcorders (28%)RevenueCameras (12%)

Office (2%)

Video (33%)

2006 2007

Video (34%)

Office (2%)

Cameras (12%) Revenue

Audio (24%)

Camcorders (29%)

Red pie slices indicate an average markup of less than 35% Red pie slices indicate an average markup of less than 35%


You have now finished the Graph Assistant tutorial.


Chapter 7. Power Painter

Power Painter is a Web layout and report creation tool. It is built using the new AJAX technology. This allows a thin browser to deliver advanced functionality without add-ons and plug-ins. With HTML, you must update the entire panel. With AJAX technology, the application can update portions of the panel for improved flexibility and performance. Power Painter allows you to create a compound report combining multiple graphs and charts on a single page. You can link the various charts together, all tied to a common sort group. Power Painter supports a live feed to your data to allow for real What You See Is What You Get (WYSIWYG) report creation. With Power Painter, you can use multiple data sources to build your compound reports.

In this tutorial, we build reports similar to those that we built using Report Assistant and Graph Assistant. The idea is for you to become familiar with the various ways of achieving similar end results. We lay out the report and graph on one page, link them by COUNTRY, and tailor the request for PDF output.

7


7.1 Tutorial overview (PP1_PDF)

In this tutorial, we build a PDF file that shows profit analysis by region with a separate graph and report for each country. The PDF file has a table of contents that lets users quickly jump to the country in which they are interested. See the example in Figure 7-1.

Figure 7-1 Power Painter exercise PDF output

7.2 Launching Power Painter and tailoring the main window

In this section we explain how to launch Power Painter and tailor the main Power Painter window to look and work in a way that we are comfortable with. We do this before we create our report.

The main Power Painter window is composed of standard drop-down menus at the top (File, Edit, and so on), a row of icons immediately below the menus, an empty canvas on which to design your report, and various palettes. You can move the palettes around the window or you can dock them on the right side. To open the palettes, you can use View → Palette → various palettes. You can open most of the palettes by using the icons below the menus. To know what the function is of each icon, hover over an icon to see a description.


Let us get started:

1. Open DB2 Web Query if it is closed.

2. Navigate to your Tutorials folder, right-click, and select Power Painter.

3. In the Open window (Figure 7-2), select the Cen_Orders table and click OK.

Figure 7-2 Selecting a data source in Power Painter

4. Set Power Painter User Preferences:

a. Changing the Reports & Graphs preview settings to sample data will improve development performance while using Power Painter. You can set your Power Painter user preferences by choosing Edit → Preferences.

Chapter 7. Power Painter 201

b. In the Preferences Window (Figure 7-3) click the Reports & Graphs tab and uncheck the Use Live Data option. You can also change the record limit to 100 to improve building the sample reports and graphs.

Figure 7-3 Changing Power Painter user preferences


You will want to change which palettes are open based on the work that you are doing. The example in Figure 7-4 is of a design that appears to work quite well and we use in this tutorial.

a. Click the pushpin button of the open Properties palette. This temporarily makes it a tab on the right side. We bring it back to the main docking area later.

b. Either choose View → Palettes → Query or click the query icon (multi-colored circle with a question mark, circled in Figure 7-4).

c. Drag the query palette to the right, underneath the Toolbox, and above your Data Sources palette.

Figure 7-4 The main window in Power Painter

While you initially lay out your report, the two main palettes that you use are the Query palette and the Data Sources palette. After you select your columns, you can move the Properties box back to the docking area and click the pushpin button for Data Sources so that it minimizes to the side. This keeps the Query and Properties palettes in full view while you design the desired layout and design of your report. You can have more than two palettes open and docked, but they can become a little small to work with effectively.

In this report, we want our page to start with our logo or picture and a heading, with a graph below the logo and heading, and the main report below the graph.


7.3 Building a graph with Power Painter

The graphing component in Power Painter is a more full function and advanced graphing tool than Graph Assistant. It allows you more control over styling, colors, text properties, legend formatting, and more. Using gauges becomes much more meaningful with Power Painter. You can selectively control the color of the quality bands and the gauge needle. With Power Painter you can add annotations to your graphs. While Graph Assistant allows you to drill down to another report or graph, this function is not available in Power Painter.

We start by building a bar graph that shows the individual regions in a country and their revenue attainment:

1. If you closed Power Painter, open it as explained in 7.2, “Launching Power Painter and tailoring the main window” on page 200.

2. Maximize your window.

3. Click the graph (bar chart) icon in the Toolbox (Figure 7-5).

4. Using your mouse, draw a rectangle on the canvas. This rectangle outlines the margins for your graph. Leave room for a report title at the top of the page. You can move and size the graph by using the mouse after you initially place it.

Figure 7-5 Inserting a graph


5. In the New Chart window (Figure 7-6) that opens, you see that Power Painter offers more advanced graph controls in most areas than Graph Assistant. For this example, select the default Vertical Clustered Bar chart.

If we want to display a series of bar charts, for example, one bar for each year for each representative, then we select the CrossTab box. However, we do not need to do this for this example.

Click Finish.

Figure 7-6 Power Painter selecting a graph type

6. Define the columns that are required in the graph.

Similar to Report Assistant and Graph Assistant, you can view column names in multiple sequences, including in alphabetical sequence, or in a tree type hierarchy based on table names. Remember that our orders data source is composed of multiple tables that are all joined automatically by foreign key definitions. The icons in the Data Source bar allow you to change the displayed sequence.

Use the drop-down arrows on both the hierarchy structure icon and the list icon to see the different choices.


7. To include a field on the report, drag the field name either onto the graph that you just created or onto the Query palette. When you drag a field onto the report area of the canvas, a Query palette opens.

a. Drag LINETOTAL onto the Y Axis label. See Figure 7-7.

Figure 7-7 Field selection for graphing

Tip: Make sure that you select your graph before you drag the field. The open Query palette relates to the highlighted object.


b. Drag REGION onto the X group axis label (Figure 7-8).

Figure 7-8 X group axis field selection

c. Drag COUNTRY onto the Coordinated label (Figure 7-9).

Figure 7-9 Adding a Coordinated field

8. Save your report as PP1_PDF.

9. After choosing most of the fields, you might find it easier to bring the Properties palette to the front and minimize the Data Sources palette:

a. Click the pushpin icon to minimize the Data Sources palette.

b. Double-click the Properties tab on the right side of the window to redock the Properties palette.

Now any time that you select a field in the query palette, you see that field’s properties in the Property palette.

Tip: Coordinated fields are common sort fields and filters that tie together the various reports and graphs on your page. Each change in the coordinated field causes a page break. The report layout that you define is repeated for each new value.


10.Select a graph to open the Basic Chart Properties window (Figure 7-10).

To see all the chart properties, you must open the Chart Editor. Click either the Show Chart Editor icon or select View → Palettes → Chart Editor.

Figure 7-10 Show Chart Editor icon

Tip: The Property box changes between Document properties, Report properties, and Column properties. If you select a column in the Query palette, you see the properties that relate to that column. If you select a graph or report, you see the basic graph properties or report properties. And if you click the white space on the canvas outside of a report, you see the overall properties for the document.


11.With the Chart Editor (Figure 7-11) open, the options that you select control the properties displayed in the properties panel. To read all of our region names, we must orient them differently on the graph:

a. In the Chart Editor panel, select Ordinal axis and then select Labels.

b. From the Properties panel, for Text rotation, under the Value column, select 45 degrees to present the region names on a 45 degree angle.

c. Look at the various properties available between the Chart Editor and the properties box. This is where you will completely control the appearance of your graph. You define your traffic lighting or conditional styling here. You can choose whether one series shows as bars while a second series is displayed as a line chart and much more.

Our graph is now complete.

Figure 7-11 Chart editor properties

12.Add a heading to the report:

a. From the Toolbox, select the Text icon (Figure 7-12).

Figure 7-12 Adding text to a report

b. Draw a rectangle where you want to place the heading of your report.

c. Type a report title of Sales Analysis by Country.

d. Click Font Properties.


e. In the Edit Font window (Figure 7-13), complete these steps:

i. Choose a font. We chose Arial. ii. Under Options, select blue for Text Color. iii. Under Style, select Bold and underline. iv. Under Size, select 14. Click OK.

Figure 7-13 Adding text to a graph

13.Add a date and page numbers to the report:

a. Select the Text icon from the toolbar and draw a rectangle where you want to place the text on your report (Figure 7-14).

Figure 7-14 Adding a text box to your document

b. Select the Insert → Date/Time and select the date format that you want to see (Figure 7-15).

Figure 7-15 Inserting current date and time

c. After the date that you just inserted, press Enter to force a new line and type Page.


d. Select Insert → Page Numbering → Page n of n (Figure 7-16).

Figure 7-16 Inserting page numbering

14.Select Font Properties and make your new text the same color as your report heading (Figure 7-17).

Figure 7-17 Date and page numbering area

15.In the Edit Font window (Figure 7-18), change the font size to 10 so that this text is smaller than the main heading. Click OK.

Figure 7-18 Font changes


16.Save and run your report. Figure 7-19 shows the results of running the report.

Notice that you have one page for each graph. When the coordinated column COUNTRY changes, a page break occurs.

Figure 7-19 Regional Sales Analysis graph

Now that our graph is complete, we create the coordinated report as explained in the next section.

7.4 Building a report with Power Painter

We now add a report that lists each salesperson who made sales in the country and details about the sales. It is conceivable that a salesperson’s results are in different sections of the report if they made sales in different countries.

1. Make sure that your PP1_PDF report is open and maximized.

2. There are multiple ways to start a report in Power Painter. In this example, in the Toolbox, click the Report icon.

3. Outline the area under your graph where you want your report to be located on the page.

Easter

n Can

ada

Wes

tern C

anad

a

Canada

Region

Rev

enue

180M

160M

140M

120M

100M

80M

60M

40M

20M

0

Note: We use the same data source that we used for the graph. If we want to add data from a second data source, we select the Data Sources palette and click the Add data source icon.


4. Drag SALESREP to the new report area and a query palette opens. Drop SALESREP in the By folder. See Figure 7-20.

Figure 7-20 Adding fields to a report

You can drag fields directly to the report or you can drag them to a query palette that you open and dock.

Tip: When creating a report, you can select one or more fields from the data source list and then drag them to the canvas. DB2 Web Query automatically creates a region for the report, autosizes it, and places alpha fields in the Sort By folder and numeric fields in the Sum folder. Try it. If you have a small table or view, you can drag the entire table to the canvas and have an instant one-click report.


5. Drag ORDERNUMBER into the By folder (Figure 7-21).

Figure 7-21 Adding additional fields to the report

6. Drag the remaining columns as shown in Figure 7-22 onto the query palette. You do not have to drag COUNTRY under the Coordinated folder.

After you place a column under the Coordinated folder, it is automatically there for every report or graph in your layout.

You have now specified the columns to use in your query.

Figure 7-22 Completed query palette


7. Add some subtotals when the sales representative changes and when the country changes. Also add grand totals at the end of the report:

a. Open the query palette if it is closed.

b. Highlight SALESREP and go to the Properties pane. Scroll down to Subtotal and click the ellipsis (...) button.

c. In the Sub Total Options window (Figure 7-23), select the Sub Totals radio button. In the Current Subtotal Text field, type subtotal for and click OK.

The default for a column is to sum or total it. This can be overridden, and you can request column functions such as average or count.

Figure 7-23 Adding subtotals

d. Add the grand totals for each section or country in our report. To do this, we need Country as a By column not just a Coordinated column.

i. Select Country from the Data Sources pane, add it as a By column, and then move it to the top of the By column list.

We do not want to see a column for Country in our report since it is the same on the entire page. We must hide the column, but still have the properties available to indicate that subtotaling is desired.

ii. Open the Query palette if it is closed.

iii. Highlight COUNTRY under the By folder and go to the Properties display.

iv. In the Field properties panel, for Visible, select No. Scroll down, highlight subtotal, and click the ellipsis button (...).


v. In the Sub Total Options window (Figure 7-24), click the Sub Totals radio button. Under Current Subtotal Text, type Grand totals for and click OK.

Figure 7-24 Grand totals for each country

e. Add the grand totals to the report. These totals are not associated with any specific column changing but rather with the report itself.

i. Highlight the report and go to the Report properties panel (Figure 7-25).

ii. In the Report properties pane, locate Column totals and select Totals.

Figure 7-25 Column totals

8. If the report is longer than the frame that we have drawn, complete these steps:

a. Highlight the report so that you can work with the report properties.

b. The overflow property controls what happens when the report has too many rows to be displayed in the defined region. The default value of Fixed indicates that the report is restricted to the exact area that you defined. If it overflows, the rows continue in the


same area on the next page until the report is complete. If you select Flowing, the report ignores the vertical boundaries and flows from the top to the bottom of each following page until it is complete.

We want our report to take full pages and flow until it is finished. Make sure that the Sizing and Overflow parameter is set to Flowing (Figure 7-26).

Figure 7-26 Controlling report overflow

c. Next you can add a flow relationship linking the reports location with the graphs in Power Painter. Related objects will allow multiple flowing reports to be presented without overlapping each other. To relate the objects, first select the Report object. Then hold the Ctrl key and select the graph. Once each object is selected click the Relate Object icon, as shown in Figure 7-27. This icon will relate the objects by the order selected. This relationship is graphically shown as an arrow between the report and the graph.

Figure 7-27 Relate Objects Icon


9. Save and run your report. Figure 7-28 shows the results of running this report.

Figure 7-28 Page 2 of a flowing report


10.Notice that the report is quite long, as indicated by the number of pages at the bottom of the window (“1 of 100”). Trying to find any individual country can be time consuming. To solve this problem, add a table of contents with an entry every time that the COUNTRY changes. We have a page break and the report layout starts over again.

From the Query palette under Coordinated, highlight COUNTRY. In the Field properties pane, and for Table of contents, select Yes (Figure 7-29).

Figure 7-29 Table of contents property


11.Save and run your report. Figure 7-30 shows the results of running this report.

Figure 7-30 PDF with a table of contents


12.Now add a URL drill-down menu on the SALESREP field in your Power Painter report. Open the Query Panel and select the SALESREP field. Once the field is highlighted the SALESREP field properties will be toggled into the Properties Panel. Click the Click here to edit Drill Down option to open the prompt and enter http://www.google.com/search?(q=COUNTRY) into the URL field (Figure 7-31).

Figure 7-31 URL drill-down prompt option in Power Painter

13.Save the report and run your report. Notice that the SALESREP field now has a hyperlink on it. Click a hyperlink to see how the URL drill down will open a browser with the dynamic search string.

You have now created your first compound PDF report using Power Painter.

Note You can also specify the drill down to run a DB2 Web Query Procedure. Section 5.4.2, “Drill-down reports: Parent report (RA5_Child)” on page 141, discusses how to use procedural drill downs.


7.5 Adding an image

If you would like to include an image (such as a company logo) in your layout, this can be easily done using PowerPainter. Follow these steps:

1. Using a tool such as System i Navigator or Windows Explorer (with mapped drive), copy/move the image file to the DB2 Web Query BASEAPP folder. This is the following folder in the IFS:

\QIBM\UserData\webquery\ibi\apps\baseapp

2. Make sure that your PP1_PDF report is open in Power Painter.

3. Click the Add image icon in the toolbox, as shown in Figure 7-32.

Figure 7-32 Add image to Power Painter layout

A dialog window opens that displays all of the image files that reside in the \QIBM\UserData\webquery\ibi\apps\baseapp folder.


4. From the list, select the image that you want to add to the layout and click OK, as shown in Figure 7-33.

Figure 7-33 Select image file to add

5. Outline the area where you want the image to be located on the page.

The image appears in the box that you outlined, as shown Figure 7-34.

Figure 7-34 Image added to layout


6. Save and run your report. Figure 7-35 shows the results of running this report.

Figure 7-35 Run report with image

7.6 Building a gauge chart

Another type of graph that can be built using Power Painter is a gauge chart. Also known as a speedometer chart, this type of chart usually indicates the current position of a value within a given spectrum. It is a very useful and common in Business Intelligence dashboards.

1. Open DB2 Web Query (if it is closed).

2. Navigate to your Tutorials folder, right-click, and select Power Painter.

3. In the Open window, select the Cen_Orders table and click OK.


4. Set up all the necessary palettes. Select View → Palettes and make sure that the following are checked (as shown in Figure 7-36):

– Toolbox– Properties– Query– Data Sources– Chart Editor

Figure 7-36 Set up palettes

5. Add a new chart to the layout by select the Chart icon in the Toolbox palette (Figure 7-37).

Figure 7-37 Add new chart

6. From the New Chart dialog window, select the funnel chart on the first row (far right), then select the gauge chart (first chart in the second row) (Figure 7-37).

Figure 7-38 Select gauge chart


7. Click Finish.

8. As shown in Figure 7-39, define the gauge chart’s sum column by selecting the LINETOTAL column (under CEN_ORDERS in the Data Sources palette) and drag it into Sum (under Chart - CEN_ORDERS in the Query palette).

Figure 7-39 Define gauge chart’s Sum column

At this point, your work should look something like the example shown in Figure 7-40.

Figure 7-40 Gauge chart example


9. Change the gauge background style by selecting General (under the Chart Editor palette), and selecting Blue Bevel from the drop-down list for Gauge background style. An example is shown in Figure 7-41.

Figure 7-41 Set gauge background style


10.The gauge chart will contain three band ranges. Set up the format for the first band. Under Gauge axis, select Band 1 format and make the following changes (as shown in the example in Figure 7-42):

d. Maximum value: 800000000 (or 8.0E8)

e. Minimum value: 0.0

f. Border color should already be set to red. If not, click the color icon and set the border color to red.

g. Band color should already be set to red. If not, click the color icon and set the band color to red.

Figure 7-42 Set up band 1


11.Set up values for band 2. Under Gauge axis, select Band 2 format and make the following changes (as shown in the example in Figure 7-43):

a. Maximum value: 1200000000 (or 1.2E9)b. Minimum value: 800000000 (or 8.0E8)c. Double-click the color icon for Border color and select yellow.d. Double-click the color icon for Band color and select yellow.

Figure 7-43 Set up Band 2

12.Finally, set up the third band. Under Gauge axis, select Band 3 format and make the following changes.

a. Maximum value: 2000000000 (or 2E9)b. Minimum value: 1200000000 (or 1.2E9)c. Double-click the color icon and set Border color to green.d. Double-click the color icon and set Band color to green.

13.Save your report as pp_gauge.


14.Run your report. It should look like the example shown in Figure 7-44.

Figure 7-44 Completed gauge chart

Note: There is a lot more that you can do in Power Painter. This tutorial has barely scratched the surface. Try dragging multiple fields at once on the page, and you will have a new report. You can also try looking at relationships and using the advanced graphics.

You can open any Report Assistant or Graph Assistant report in Power Painter. This gives you a starting point before you continue to add new reports using the Power Painter functionality.


Part 3 Tutorials for DB2 Web Query optional features

In Part 2, “Tutorials for DB2 Web Query” on page 89, we covered the base features that are included in DB2 Web Query. In this part we cover the optional components that are ordered as feature codes for 5733-QU2.


� Chapter 8, “Active Reports” on page 233

Active Reports enable the analysis of reports by users even when they are not connected to the System i platform.

� Chapter 9, “Developer Workbench” on page 253

This chapter is a prerequisite for both Chapter 10, “Online analytical processing” on page 261, and Chapter 11, “HTML Composer” on page 295.

� Chapter 10, “Online analytical processing” on page 261

The graphical hierarchy or dimension design components of Developer Workbench is a prerequisite for OLAP-enabling your reports. After you define these hierarchical structures, it is simply a matter of the report developer including them in the existing reports.

� Chapter 11, “HTML Composer” on page 295

HMTL Layout Painter is a component of Developer Workbench. With it, you can create compound reports, dashboards, and highly parameterized reports.

� Chapter 12, “Additional features of Developer Workbench” on page 351

Developer Workbench is a set of advanced tools for programmers. This chapter includes information about advanced metadata definition, data profiling, impact analysis, SQL wizards, and business view creation of your data.

� Chapter 13, “DB2 Web Query Spreadsheet Client” on page 387

Part 3



Chapter 8. Active Reports

Active Reports is an optional feature that is available from IBM for DB2 Web Query. While the base product is licensed to named users, Active Reports is licensed to a System i machine, based strictly on the software tier (P10, P20, and so on). Any user who can create a report using either Report Assistant, Graph Assistant, or Power Painter is entitled to create an Active Report. Since Active Reports is intended for disconnected users, individual users do not require a license to use the reports.

The HTML reports must be made available to users either by e-mail, a shared network drive, or additional tools, such as Report Caster, from Information Builders. As you will see in this chapter, with Active Reports, the data and the reporting controls are all stored within the HTML page. When the user has access to the HTML page, the user can access, manipulate, and analyze the data with no requirement for any additional licensing.

With Active Reports, for example, a sales person might sign on to the System i environment in the morning and run a report for each customer that they plan to visit that day. Then they can save the reports on their local hard drive. From their car, the sales person can then look at and analyze the data for her customer immediately prior to visiting them.

8

Attention: To use Active Reports, the server requires a license key that can be purchased as an optional feature of DB2 Web Query (5733-QU2).


8.1 Overview and highlights of Active Reports

Active Reports allows users to interact with their reports and work disconnected from the System i environment. HTML Active Report pages are self-contained reports. Both the data and the Java Script are compressed within a single efficient file. This file can be stored by the users on their local drive. It can be stored on the server for retrieval by the users or it can be sent by e-mail to users.

Active Reports are well suited for the mobile worker who is frequently disconnected from the Web. With Active Reports, you can create a variety of simple or advanced charts (pie, line, bar, or scatter), roll-up analysis, or pivot reports. You might want to allow your sales people to analyze the buying patterns for the clients that they intend to visit that day. Your service personnel might want to view the service history of a customer before they visit. You might even choose to send reports by e-mail to your customers or partners that detail their activities with you. The user of an Active Report requires no special software, and there are no licensing fees for users.

With Active Reports, users can perform the following tasks:

� Create graphs and charts based on their data.� Filter or highlight their data.� Change the report sort sequence to any column.� Apply calculations such as sum, min, max, avg, count and count distinct to their data.� Change the look of a report by hiding columns, changing the pagination, and more.� Add data visualization bars to compare and contrast values in a column.


Users can continue to work with their reports in a browser window, download the reports to Microsoft Excel, or even pull their data and graphs directly into Microsoft PowerPoint. Figure 8-1 shows a sample of the output generated from Active Reports.

Figure 8-1 Active Reports sample

8.2 Creating a report with Active Report

We enable the RA3_GrossPft report that we created in Chapter 5, “Report Assistant” on page 99, to be used when the user is not connected to the server.

1. From the DB2 Web Query home page, open the RA3_GrossPft report.


Important: Prior to beginning this tutorial, you must have upgraded your license key. The only requirement for Active Reports is that the server be properly licensed. There are no user requirements.

Chapter 8. Active Reports 235

3. On the Report options tab (Figure 8-2), complete these steps:

a. For Generate report as, select AHTML - Active Report. When you select this option, notice that the Active Report Styling button becomes active.

At this point, you might run the report. However, we a make a few formatting and highlighting changes first.

b. Click Active Report Styling.

Figure 8-2 Selecting the Active Reports option

Note: Horizontal (Across) sort fields are not supported for HTML Active Reports.


c. In the Active Report Styling window (Figure 8-3), under Report view, select Tabular. For Row selection, select yellow. For Visualization colors, select red for Negative and dark green for Positive. Click OK.

.

Figure 8-3 Active Report Styling

4. Save your report as AR1_GrossPft.

5. Run your report. Figure 8-4 shows the results of running the report.

Figure 8-4 Active Reports in the tabular format

Note: In this window, we define the presentation and initial look of the report for the user. We discuss Accordion reports later in the tutorial.


6. Click a down arrow next to any column and select Save Changes (Figure 8-5). Save your report as AR1_GrossPft.html.

Figure 8-5 Saving your Active Report for offline use

In the next section, we continue to work with this Active Report, but we do this as though we are the disconnected user and not the developer.

Note: You can also use the Save As option in your browser to save the HTML page. If you choose the Export option instead of the Save Changes option, you export the records without formatting and controls. The records can be exported to an HTML page, Excel, and comma-separated values (CSV) files.

Tip: After you save your report as an HTML file, you can send it to users by using e-mail. In this case, the recipient can view and analyze the report with no connectivity to the System i environment. To run and save an Active Report, you must be a named user. To work with the HTML file after it is created, you do not need to be a named user.


8.3 Using an Active Report

When users receive Active Reports, they open it in their browsers. After your users receive this report, they can then perform various types of analysis on it without connecting to the System i environment.

1. Locate and open the AR1_GrossPft.html report. If you are connected to the System i environment, you can also go to the DB2 Web Query home page, navigate to the report, and run the report.

2. Analyze the product categories and evaluate the gross profit compared with revenue or Line Total. Click the down arrow next to Gross Profit and select Sort Descending (Figure 8-6).

Figure 8-6 Active Reports Sort Descending

3. To make the report fit better on the page, we hide the Cost of Goods Sold column. To hide a column, click the down arrow next to Cost of Goods Sold and choose Hide Column (Figure 8-7).

Figure 8-7 Hiding columns

ActiveX controls: Active Reports use ActiveX controls. Based on your browser security settings, you might see warning messages, and you might be asked whether you want to allow blocked content.


4. The Visualize feature is a powerful tool that allows you to see, at a glance, relationships between various columns. Click the down arrow for the Gross Profit column and select Visualize. See Figure 8-8.

Figure 8-8 Active Reports Visualize Selection

Notice the green or red bars that are displayed in the chart in Figure 8-9. Visualize gives you a quick visual representation of the data in a column.

5. Click the down arrow for the Revenue column and select Visualize.

Now you see the bars for the Revenue column as well. With the visualize bars, it is much easier to spot relationships. Notice that although speakers is not ranked high in the Revenue column, they are extremely profitable and generate the third highest profit of any product category.

Figure 8-9 Active Reports Visualize results


6. Click the down arrow for Gross Profit. Select Calculate → % of Total (Figure 8-10).

Figure 8-10 Adding a % of Total column


Notice that a new column, called % of Total, is now displayed that shows each product category row as a percent of the total Gross Profit in this report (Figure 8-11).

7. Click the down arrow for Gross Profit and select Sum. Your summary prints at the top of the page by default.

Figure 8-11 New % of Total column and Total Sum


8. Filter the report temporarily so that we can concentrate on our audio sales. Click the down arrow for Product Type and choose Filter → Equals (Figure 8-12).

Figure 8-12 Active Reports filtering

9. In the Filter Selection window (Figure 8-13), click the down arrow on the right to see a list of the distinct values in a field. Select Audio from the list, then click Filter.

Figure 8-13 Active Reports Where Equals clause

Highlight button: If you click the Highlight button instead of clicking the Filter button, your report contains all the records, but highlights the ones that meet the filter criteria.

Contains operand: Besides your standard operators, such as Greater Than and Equal, you can search for a string of data anywhere within a field using the Contains operand. By default, Contains is not case sensitive. If case is important, there is an additional operand Contains (match case). There are also similar Omits and Omits (match case) options.


10.In the filtered chart (Figure 8-14), you see both your filtered sum and the total sum for a column. In the upper left corner, click the new SUB/TOT icon. It enables you to cycle through viewing the sum of all your data, the sum of your filtered data, and having both sums displayed concurrently.

At any point you can choose the Restore Original option. To see all the records, close the Filter Selection window.

Figure 8-14 Active Reports Filtered/Total Sum

11.A helpful way to analyze the data involves changing the grouping and looking at your numbers slightly differently. Select the down arrow for Gross Profit and select Rollup → Group By Product Category (Figure 8-15).

Figure 8-15 Active Reports Rollup grouped by Product Category


12.Click the Pie chart graph icon to change the report that you are looking at into a pie chart (Figure 8-16). You can choose line or bar charts as well.

Figure 8-16 Active Report rollup results

13.Export the chart to Microsoft PowerPoint, Excel, and Word. Click the first List type icon and select Export to → Excel (Figure 8-17).

Figure 8-17 Active Reports graph

You can access the same graph directly from your full report by clicking the Gross Profit column and selecting Chart, Pie, and Product Category as your Group by field.

Tip: If you created filters, then plotted your graph and closed the filter, by default, your graph changes to reflect the displayed report or all the data. To keep the chart as is, displaying the filtered data, select the Lock icon.


Figure 8-18 shows the output of the report to Excel.

Figure 8-18 Active Reports output to Excel

14.Export to the other Microsoft product if you have them loaded on your system.

15.Close Excel and close the charting window.

16.To use the Rollup functionality, select the down arrow for Gross Profit and select Rollup → Product Type as the field to roll up, as shown in Figure 8-19.

Figure 8-19 Rollup Gross Profit by Product Type


17.Once a Rollup window is open you can add another measure using Add(Y) to add Revenue to this Rollup window. Click the Add Icon → Add(Y) → Revenue. This adds the Revenue field to the Rollup window. See Figure 8-20.

Figure 8-20 Add Y Function

18.To use the Cross tab or Pivot functionality, select the down arrow for Gross Profit and select Pivot → Product Category → Product Type as the field to go across the top of your table (Figure 8-21).

Figure 8-21 Creating pivot tables with Active Report

Note: You can also add new Grouping Fields to the Rollup window using the Group By (X) selection.


19.When you have a basic pivot table, you can start adding to it, changing it, and pivoting it. Click the left icon above Product Type (circled in Figure 8-22).

Figure 8-22 Pivot Table output with Active Report

Clicking the icon to the left of the arrow moves a field back and forth between being a column or a row, pivoting on that field. Notice in Figure 8-23 that the title changes as the column layout changes.

Figure 8-23 Changing sort breaks and sort priorities for Active Reports

There is quite a bit more that you can do with pivot tables if it makes sense for your data. You might ask to see the average profit numbers, for example, if you have more than one record per row grouped together.

Note: This report is not a good one to demonstrate cross tab or pivot functionality. There are not enough fields shown that relate to each other for us to pivot on. The next steps illustrate additional capabilities of Active Reports.


As you can see, Active Reports allow users to quickly add a level of analysis to their reports, all without being connected to the System i environment.

Let us look at the difference between a tabular and an accordion Active Report:

1. If your report definition is closed, go to the DB2 Web Query home page navigate to it, right-click, and open it.

2. Click the Field selection tab (Figure 8-24).

3. On the Field selection tab, complete these steps:

a. Remove subtotals from PRODUCTTYPE.b. Clear the Add grand totals to the end of the report check box.

Figure 8-24 Removing subtotals and selecting the option to add grand totals to the end of the report


5. On the Report options tab, complete these steps:

a. Click Active Report Styling.b. Select Accordion instead of Tabular and click OK.

Tip: To size the window shown in Figure 8-23 on page 248, scroll down to the bottom of the window. In the right corner is an area that you can drag to widen and size the pivot table. Click once outside the box after you finish dragging to release the cursor.

Restriction: With earlier versions of the software, subtotal and total messages occasionally appeared in an accordion report. It is easiest to remove them now.


6. Run your report. Figure 8-25 shows the results of running the report with the Accordian option selected. Only the data values at the highest level (first vertical sort field) are shown initially.

Figure 8-25 Accordion Active Report

7. Click the plus sign (+) to expand a field. Click the minus sign (-) to compress the data. In our example, we expand Audio and see all the Product Categories within Audio (Figure 8-26). If we had more Sort By columns in our report, we could expand each of the levels.

Figure 8-26 Accordion format in Active Reports

8. Look at some of the other options that are available under the arrows. You will see that you can export data to CSV files, to HTML files, and directly into Excel. If you filter your data, you have the choice of exporting the entire data set or just the filtered records.

Tip: HTML Active Reports can support up to 20,000 rows of data. If you are using a Firefox browser, we recommend that you use only up to 15,000 rows of data. If you are using an Internet Explorer browser, use only 5,000 rows of data.


8.4 Summary

Active Reports is a tool that works extremely well when your users are remote and not connected to the System i environment. Even with local users, there are no named user licensing requirements to work with and analyze an Active Report. You can create an Active Report and send it by e-mail it to a user for the user to analyze. The person who originally runs the report must be a licensed named user. The report is stored in a highly compressed format. Active Reports is just one more powerful reporting tool for you to use with DB2 Web Query.



Chapter 9. Developer Workbench

Developer Workbench provides an integrated development environment (IDE) for building and maintaining a DB2 Web Query reporting environment. Developer Workbench includes additional tools to work with your metadata. The Synonym Editor allows you to change the way in which a field is displayed to the users. You can add commas and decimal signs, convert date formats, convert alpha to numeric fields, or even change the length of a field. The Synonym Editor also allows you to create calculated fields for users. You can predefine joins for the users or create business views that simplify the structure and number of columns that the user sees. If you plan on using the optional online analytical processing (OLAP) feature, you must define your hierarchies or dimensions with Developer Workbench.

Using the metadata layer, Developer Workbench provides the ability to perform impact analysis at both a file level and a field level. If you must make changes to a field, you can see which reports and graphs use that field and the business views of which it is part.

Developer Workbench provides the capability to profile your data. Profiling allows you to see patterns in the text characters. For example, profiling telephone numbers in the Stores table might show us that five records have a format of nine numeric characters instead of 10. We might want to know if these five records are a quality problem. Data profiling also shows the minimum and maximum values in a column and identifies the outliers.

The SQL Wizard allows you to import SQL into Report or Graph Assistant.

One of the major tools within Developer Workbench is the HTML Composer component. HTML Composer is specifically designed to create HTML pages that can contain compound reports or dashboards. You can find a complete tutorial for this component in Chapter 11, “HTML Composer” on page 295.

In this chapter, we configure the System i DB2 Web Query environment and set up Developer Workbench default settings. This chapter is a prerequisite for both Chapter 10, “Online analytical processing” on page 261, and Chapter 11, “HTML Composer” on page 295. For more information about Developer Workbench see Chapter 12, “Additional features of Developer Workbench” on page 351.

9


9.1 Configuring Developer Workbench

To configure Developer Workbench:

1. Because Developer Workbench is a PC application, install the software on the developer’s PC.

2. When you start Developer Workbench the first time, add a definition for your System i environment.

a. Right-click WebFOCUS and select Add (Figure 9-1).

Figure 9-1 Adding System i environment


b. In the next window (Figure 9-2), complete these steps:

i. Type a description of your System i environment.ii. For Host Name/IP Address, type a name.iii. For Port, verify that 11331 is selected.

iv. For HTML Alias, ensure that it is /webquery_html. Click OK.

Figure 9-2 System i environment properties

Tip: If you changed the default DB2 Web Query default port number, you must clear the Use Default box and specify your installation’s port number.

Chapter 9. Developer Workbench 255

3. The first time that you open the System i environment or connection that you just added, you must sign on. Sign on with your administrator or developer authorized profile. See Figure 9-3.

Click Logon.

Figure 9-3 Initial opening of the System i connection

Tip: Select the Remember my User Name and Password on this computer option during this sign-on and the next sign-on so that you are not prompted with these sign-on windows again for this System i connection.


4. Expand system name → Data Servers → EDASERVE (Figure 9-4).

5. Log on again. Enter your user name and password and click Logon.

Figure 9-4 Metadata login

6. Continue down the metadata path by expanding EDASERVE → Applications. Select baseapp.


In the right pane of Figure 9-5, you see all your metadata or your master (.mas) and access (.acx) files. Remember that the master file contains the field names and formats for your table. The access file contains information about the actual name and location of the physical table and the primary keys for the table. Nearly all your work is done with the master file.

The source code or procedures that store your report definitions are located under the Managed Reporting → Domains portion of the tree. Expand that branch if you want to create a new report or modify an existing one.

Figure 9-5 Metadata files

9.2 Setting Developer Workbench default options

Developer Workbench has a set of options that can be tailored to an individual user. To access these options, select Window → Options (Figure 9-6). We use the tailoring options in later tutorials.

Figure 9-6 Displaying Developer Workbench options


Figure 9-7 shows the General options tab.

Figure 9-7 General options tab

Developer Workbench allows you to show your Windows desktop explorer tree in the same window as your DB2 Web Query explorer tree. On the Explorer tab, select the Show Desktop on Explorer tree option (Figure 9-8).

Showing your Windows desktop tree within Developer Workbench has definite benefits. The obvious benefit is the ability to stay within one working environment as a programmer. The less that you have to flip back and forth between your development mode and Windows, the better.

An additional benefit is the ease with which you can copy items from your PC hard drive to the DB2 Web Query folder structure. You might want to move style sheets, company logos, pictures, and other PC files between the different file structures.

Figure 9-8 Explorer options

Restriction: Report Assistant does not pick up all the reporting options set under the Reporting tab at this point in time.


In Figure 9-9, we copy and paste a text file that contains SQL statements into our Other Files folder in the Common Domain. From here, the SQL can be accessed and run via the SQL Wizard in Developer Workbench or the SQL metadata creation option from the DB2 Web Query home page.

Figure 9-9 Copying files between the PC and DB2 Web Query

For more details about using Developer Workbench, refer to the online help text and the following chapters:

� Chapter 10, “Online analytical processing” on page 261� Chapter 11, “HTML Composer” on page 295� Chapter 12, “Additional features of Developer Workbench” on page 351


Chapter 10. Online analytical processing

Online analytical processing (OLAP) is best known as the technology that allows a user to slice and dice data or drill down into data. DB2 Web Query makes it easy to provide users with a sophisticated drill-down, slice and dice interface without the report developers having to do anything at all. You will have a better understanding of this concept by the time you finish this tutorial. After taking a standard report created with Report Assistant, the report developer selects an output option to OLAP-enable the report. This automatically provides an interface with drop-down lists and drill capable columns that allow the user to slice and dice or pivot their data and perform a variety of local analysis on the original report.

Tables must have any embedded hierarchies predefined via the Developer Workbench. After this is done, the users have an easy and intuitive way to navigate and drill down on the hierarchy within their data.

OLAP analysis typically starts with a question such as “What were my regional sales numbers across the United States?” At this point, you might look at the numbers and ask to see the details for the Eastern region, which looks out of line with the other regions. If you then find that a single state is pulling down the region you might ask to see the revenue for that state split out by the different product groups. After you find a product group that appears to be in trouble, you might ask to see the sales for that product group in that state summarized by month for the last two years. This type of analysis is sometimes called having a conversation with your data. It is OLAP technology that enables this quick and easy interaction with the data. A user could have created a separate ad hoc query for each of the above questions but that would probably not occur in real life. If a user simply had to click a specific field of interest to go down to the next level of detail, they would be far more likely to continue with their analysis.

10


10.1 OLAP terminology

Table 10-1 covers basic OLAP terminology to explain the concepts that we use in this chapter.

Table 10-1 OLAP terminology

10.2 Defining OLAP metadata using Developer Workbench

Before a user can successfully OLAP enable a report, the tables used must have any existing hierarchies or dimensions defined to DB2 Web Query.

Term Definition

Dimension A set of columns structured in a hierarchy. For example, a geographic dimension might include a city that belongs to a state, which is in a region, which is part of a country. In this example, Country is the top level and city is the bottom level of the dimension.

A product dimension might include product type at the top level and below that a product category, which contains multiple models and each model contains multiple part numbers or SKUs.

Drill down An action that involves going from one level in a hierarchy to the next lower level. For example, if a user drills down on country, he sees the different regions that make up the country. If he then drills down on region, the states that compose the region are displayed.

Drilling down can also involve invoking more detailed reports or graphs. For example, in an earlier tutorial, we drilled down on product type and passed the product type as a parameter to a second report. If this type of drill down is defined for a column, it takes precedence in an OLAP report over drilling down through the hierarchy.

Hierarchy The structure or sequence of each of column within the dimension. In the example, above the geography dimension is a hierarchy of country, region, state, and city.

Hyperlinks A column that is displayed in blue in a report. The user can click the hyperlinked column to initiate an action. The standard action that is linked to a column is the ability to drill down to the next level of data. A hyperlink can also take you to another report, as previously demonstrated.

Measure Numeric fields that you want to analyze at the various levels of a hierarchy and at various intersection points. For example, you might want to analyze sales of video equipment in the United States. This is the specific intersection or slice of the data in which you are interested. Normally, these fields are summed or totalled, but they do not need to be. For example, you might want to report your revenue by country and then drill down to the revenue in the regions that make up the country. Now the revenue is summed by region. You might also want to see the average profit on an order across states or regions to see if certain areas are offering too deep a discount. In this case, profit is an average measure, not a summed or totaled measure.

Pivot To move a field from a column to a row or vice versa. For example, year might be one of the by fields where the different years are listed down the side of your report. If you wanted the various years across the top of your report instead, you pivot the field or heading Year. You can do this in multiple ways in an OLAP report including dragging the field or using the control panel to pivot your data.

Important: Prior to reading this section, you must read Chapter 9, “Developer Workbench” on page 253.


Before a user can OLAP enable a report, a developer must define any hierarchies that are present in the data. This hierarchy is automatically used by DB2 Web Query whenever any future user asks to OLAP enable a report that references tables that contain these hierarchies. Hierarchies, also known as dimensions, can involve elements from multiple tables, although the norm is to have a single hierarchy composed of columns from a single table.

1. Start Developer Workbench.

2. Expand DB2 Web Query Environments → system name → Data Servers → EDASERVE → Applications → Baseapp.

3. Remember that the term synonym is synonymous with metadata. To define a hierarchy, edit the metadata for a table using the Synonym Editor:

a. Right-click the cen_orders.mas table and select Edit in Synonym Editor (Figure 10-1).

Figure 10-1 Developer Workbench metadata

Chapter 10. Online analytical processing 263

4. At the bottom of the window that opens (Figure 10-2) click Modeling View. This is the easiest way to define hierarchies to DB2 Web Query.

Figure 10-2 Developer Workbench Synonym Editor

Note: In the left pane of this window are four tables pane (Orders, Inventory, Plant, and Stores) even though you only opened the master file or metadata for the orders table. This tells you that the orders table was defined in the System i environment with foreign keys pointing to the inventory, plant, and stores tables. When you do this, DB2 Web Query automatically pulls in the metadata for all four tables into one clustered table.


5. If Dimension Builder is not visible, click Synonym → Dimension Builder. Figure 10-3 shows the Dimension Builder pane. To the right of the Dimension Builder view (Figure 10-3), you see the tables and their relationship to the base table, orders.

Figure 10-3 Dimension Builder


6. You can either view the tables as icons or view a column list for each table. Double-click the Inventory table icon to switch to column view (Figure 10-4). You can double-click the icon again to revert back to icon mode.

Figure 10-4 Icon or detailed table view


7. The columns in the inventory table are structured so that, within product categories, you have product types; within product types, you have models; and within models, you have product names. We must describe this hierarchy to DB2 Web Query.

Right-click Dimensions and select Add Hierarchy → Levels (Figure 10-5).

Figure 10-5 Adding a hierarchy

There are two types of hierarchies. One is based on levels and the other is based on parent-child relationships. We use level hierarchies. The level hierarchy is the example that we have used so far, that is, country, regions, state, and city are a level hierarchy.

For more information about the different types of hierarchies see the Developer Workbench help text.

8. Right-click your new dimensions icon and select Rename. Change the name to Product Hierarchy.

Tip: A quicker way to achieve the same result is to click the hierarchy icon (circled in Figure 10-5) at the top of the Dimension Builder pane.


9. Starting at the top of the hierarchy (Product Type), drag the column name to Product Hierarchy. Repeat this action for Product Category and Product Name (Figure 10-6).

Figure 10-6 Product Hierarchy

10.Define the Date Dimension shown in Figure 10-7:

a. Right-click Dimensions and select Add Hierarchy → Levels.

b. Right-click your new dimensions icon and select Rename. Change the name to Date Dimension.

c. Drag the column name to the Date Dimension for ORDERDATE_YEAR, ORDERDATE_QUARTER, ORDERDATE_MONTH, and ORDERDATE_DAY.

Figure 10-7 Date Dimension


11.Define the Plant Hierarchy as shown in Figure 10-8:


b. Right-click your new dimensions icon and select Rename. Change the name to Plant Hierarchy.

c. Drag the column name to Plant Hierarchy for Plant Country, Plant Region, Plant State, and Plant City.

12.Define the Store Hierarchy as shown in Figure 10-8.


b. Right-click your new dimensions icon and select Rename. Change the name to Store Hierarchy.

c. Drag the column name to Store Hierarchy for COUNTRY, REGION, STATE, CITY, and Store Name.

Figure 10-8 Developer Workbench Multiple hierarchies for OLAP

13.If you do not see the additional date fields such as ORDERDATE_YEAR, decompose your date as explained in 12.1.1, “Date Decomposition” on page 356.

14.Save your definition.

You have now completed the all the definitions that are required for OLAP-enabling your reports. Typically, this is done once by the IT department. After this, any user with authority to create reports can choose to OLAP-enable their report.

You can see how easy it is to define a hierarchy in your data and create the necessary metadata to OLAP-enable your reports for detailed analysis.


10.3 Enabling an OLAP report (OL1_Revenue)

To enable an OLAP report:

1. Navigate to your Tutorials folder, right-click the RA1_Revenue report, and select Open.


3. On the Report options tab, complete these steps:

a. Since we know this is a small report, for Page numbering, select Off (Figure 10-9).

Figure 10-9 Turning off default page numbering

b. Under the Enable OLAP, select Show Tabbed.

Note: OLAP is an optional feature with DB2 Web Query. As you have just seen, Developer Workbench, also an optional feature, is a prerequisite for creating OLAP-enabled reports. Developer Workbench is the only interface for defining the hierarchies that are required by OLAP.

Enable OLAP options: The Enable OLAP options control how users can interact with an OLAP report and access OLAP tools:

� Off: provides an OLAP button to open the OLAP Control Panel. There is no top Selection pane.

� Columns only: allows you to sort, hide, drag, and drop columns. There is no top Selection pane and there is no access to the OLAP Control Panel.

� Columns with panel: looks the same as Columns only, but when you click the square blue button over a dimension, you open the OLAP Control Panel.

� Show filters on top/bottom: adds the OLAP Selections pane to the top (or bottom) of the report. This option is acceptable with a few dimensions and a few levels in each hierarchy. It tends to look messy when you have too many levels within different dimensions. Try it to see the difference between showing dimensions and hierarchies as filters or as tabs.

� Show Panel in Report: is the same as the Columns with panel option but includes a small OLAP symbol in the lower left to more obviously allow the user to open the OLAP Control Panel.

� Show Tabbed: For OLAP reports that have multiple dimensions, this option groups the dimension elements under a tab labeled with the dimension name. This is the option that we use.


c. Under the Automatic drill down, select Dimensions and Measures (Figure 10-10). This gives you the maximum drill-down capabilities. When creating your own reports, you can choose to drill down on the dimensions only and not the measures.

Figure 10-10 OLAP enabling a report

4. Save your report as OL1_Revenue.

You have now OLAP enabled your report. To summarize, we took a basic report and selected an output option to enable OLAP. This simple selection automatically gives you an enormous amount of analysis capabilities, as you will see in the next section.

Automatic drill down options:

� None: The user cannot drill down to a lower level in the hierarchy within the report itself.

� Dimensions: The user can drill down on a dimension to proceed to the next level down in the hierarchy.

� Dimensions and Measures: In addition to drilling down on the dimensions, the user can drill down on the measures within the report. This allows the users to drill down to the lowest level of all displayed hierarchies.


10.4 Working with an OLAP-enabled report

To begin working with the OLAP-enabled report as explained in this tutorial, run your OL1_Revenue report. Figure 10-11 shows this report.

Notice the addition of a completely new panel at the top of the report. This is called the Selection pane. It includes tabs for every dimension described for any of the tables that are part of the orders cluster. You also have the capability to work with the measures and to create graphs directly from the report.

There are three ways to work with your OLAP data:

� From the report itself� From the Selections pane� From the Control Panel

In the report shown in Figure 10-11, you cannot see the control panel. In this example, the control panel starts as hidden or closed. You can open it by clicking the OLAP button or by clicking the blue square to the left of the Product Type heading.

Figure 10-11 OL1_Revenue report

Note: If you run your report from the DB2 Web Query home page, there is a maximize icon to the far right. This sends your report to a new browser window.


10.4.1 Slicing, dicing, and drilling down for more details

Looking at the report in Figure 10-11 on page 272, notice that the heading for every column either has a blue square or a set of arrows. The blue square allows you to drag and drop the column and to rearrange or pivot it. It also allows you to open up the OLAP Control Panel. The arrows allow you to sort the measures or numeric fields.

To use the arrows and buttons to drill down for more details, follow these steps:

1. Because revenue was previously unsorted, neither half of the arrow is dark and the prompt reads sort Revenue. Click the sort arrow to the left of Revenue (Figure 10-12).

Figure 10-12 Sorting a measure

2. Now that you have sorted by revenue, hover over the column again. Notice that the bottom half of the arrow is dark. Click this arrow and sort the column in descending sequence (Figure 10-13).

Figure 10-13 Sorting from highest to lowest

Tip: When working with an OLAP-enabled report, there are multiple ways to accomplish the same end result.


Here is another way to sort revenue. Right-click the column heading Revenue and select Visualize (Figure 10-14).

Figure 10-14 Revenue context menu

As we saw in Active Reports, selecting Visualize displays bars to help you quickly note trends or easily compare two columns. See Figure 10-15.

Figure 10-15 Revenue visualization

3. Click the Store Hierarchy tab.

The Store Hierarchy tab has a drop-down tab for each element in the hierarchy, proceeding from the top of the hierarchy to the bottom.

By default, each of the drop-down lists contains all the unique values for that column. For example, initially every region in the world is available under the Region tab.

Note: Positive numbers are visualized with blue bars, while negative numbers are visualized with red bars.


4. To start to filter and drill down on your data, click the Country drop-down list and select United States (Figure 10-16).

Figure 10-16 Selecting a hierarchy

5. Click the Region drop-down list. Notice that the only regions displayed are for the United States. Select the North region (Figure 10-17).

Figure 10-17 Continuing to filter within hierarchy

6. The filters in the Selection pane do not take effect until you click Run. Review your current totals and click Run (Figure 10-18).

Your report now shows the revenue and number of orders for the North region in the United States.

Figure 10-18 Run your filtered report

7. Notice that immediately to the right of COUNTRY and REGION is an equals sign (=). Click the = button. Each time that you fill in a value you filter your data by creating a WHERE clause. Instead of selecting COUNTRY equal to United States, we can select all countries except the United States by changing the button to not equal. Click the button multiple times to cycle through your choices.

8. Click Reset to reset the report back to its initial state. You can also use the back arrow on the browser to go back one page at a time.

Tip: You can select multiple values using the Ctrl or Shift keys.


9. Click the Product Hierarchy tab (Figure 10-19).

Figure 10-19 Drilling down on Product Type

10.Drill down within the report, not by using the hierarchy tabs. Click Audio.

Notice that not only did you drill down from Product Type to the next level of Product Categories within Audio, DB2 Web Query also filled in the Selection pane tabs for you (Figure 10-20).

Figure 10-20 Drill down on Product Category


11.Drill down on Amplifiers/PreAmps/Tuner to see the products that compose the Amplifier category.

Again notice that the drop-down lists have been filled in for you. You can go back and forth this way between the body of the report and the tabs at the top. See Figure 10-21.

Figure 10-21 Results of Product Category drill down

12.Continuing to analyze our data, drill down to see only the Amplifier sales that occurred in January 2007. Click the Date Dimension tab.

13.For Year, select 2007. You can then select the quarter or go straight to month and select 01 (Figure 10-22).

Figure 10-22 Selecting values in non-consecutive levels

14.Click Run. Figure 10-23 shows the results of running this report.

Figure 10-23 Slice of your data (January 2007)

15.Click Reset to start back at the beginning with an unfiltered report.


16.Try drilling down on a measure or total field. Drill down on the Revenue column for Office products (Figure 10-24).

Figure 10-24 Drilling down on a measure

After drilling on the revenue for office products, the Office product type is expanded to its subcategories and products. The revenue and order count are now grouped at a much more detailed level (Figure 10-25).

Figure 10-25 Results of drilling down on a measure

17.Reset your report now so that all drill-downs are removed.


18.The next request from our users is to generate a report that shows revenue by product type by year.

Drag ORDERDATE_YEAR from the Selections pane into the area of the report where you want it (that is, across the top). The plus symbol (+) shows that you are in a valid area in which to drop the field (Figure 10-26).

Figure 10-26 Dragging and dropping dimensions

19.Right-click Order Count and select Hide (Figure 10-27).

Figure 10-27 Hiding a field


20.We now have a pivot table. If you decide that you prefer to see the years down the left column, drag the column name ORDERDATE_YEAR to the left of Product Type (Figure 10-28). Again, the + sign directs you to where you can drag the field.

Figure 10-28 Pivot report

21.Click Save and select Save Report to save the new pivot report (Figure 10-29). You can also see what happens when you save to the Excel and PDF output formats.

Figure 10-29 Saving an OLAP report

22.In the window that opens (Figure 10-30), specify the folder for your report. If you want to save this report without any OLAP capabilities, select the Save without OLAP option. Since you used the OLAP functionality to design a new report for a user, we do not select this option. Click OK.

Figure 10-30 Saving a report to your folder


23.Our users have changed their minds and decided that they do not want a pivot table. Instead they want to see the year and product type to the left of Revenue.

Drag ORDERDATE_YEAR from the Sort across portion of the report to the Sort by section (Figure 10-31).

Figure 10-31 Pivoting a column

In addition to dragging from the Selection pane area, there are other methods to display additional columns in the report as explained in the following steps.

24.Right-click ORDERDATE_YEAR and select Unhide (Figure 10-32). You see a list of columns that were either part of the initial report or that are in one of the hierarchies. These are the columns that are available for display.

Figure 10-32 Unhiding columns


25.Try the same process for the Revenue field. Right-click Revenue and select Unhide. Notice that you see that only numeric fields are available.

26.Click the down arrow for the Measures tab (Figure 10-33):

a. You will see a list of all the measures that are available to you in this report. Notice that Order Count has no check mark. This is because we hid it. To display Order Count, select it again.

b. Select Revenue. Notice that you can cycle through the different options for displaying, visualizing, and hiding the measure. We visualize Revenue, display Order Count, and run the report again.

Figure 10-33 Measures tab


27.Click the down arrow for the Graph tab (Figure 10-34):

a. Select Revenue.

b. Click the icon to the right of Revenue to cycle through the graph types until you come to pie charts.

c. Click Run.

d. Make the pie chart window larger by dragging down the horizontal break line between the graph and the report.

Figure 10-34 Graphing an OLAP report

Break line


Notice that there is one pie chart for each year that was your major sort by axis. See Figure 10-35.

If the measures in the original report were drill-down capable, then the graph can be drilled into.

Figure 10-35 Graph drill down

Drilling down on the graph generates the same report as though you drilled down on the Revenue field in the original report.

28.Experiment with the various options for drilling down and filtering your report. When you are finished, click Reset to restore the report to its original values.

Tip: To control the scope of the graph, use the drop-down lists in the Selection pane. For example, if you only want a graph for 2007 revenue, you can select the year 2007 from the ORDERDATE_YEAR drop-down list.

Tip: If our report has multiple measures that can be graphed, you can graph them on the same chart. You can select each measure for graphing and choose a different graph type. For example, if our report contains profit, you can superimpose a line graph on a bar graph with the line representing the profit and the bar representing revenue.


10.4.2 Manipulating the data using the OLAP Control Panel

Up to this point, we have manipulated the OLAP report through the Selection pane at the top of the report and directly through hyperlinks in the report itself. Now we use the third method for interacting with the data, which is the OLAP Control Panel.

1. Click the OLAP button at the bottom of the Selections pane to open the OLAP Control Panel. Alternatively, you can click the blue square next to Product Type.

Figure 10-36 OLAP Control Panel

Although the most frequently used functions are available directly from an OLAP report, the Selections pane, or both, several functions can be performed only from the OLAP Control Panel. The OLAP Control Panel can do everything that can be done from the OLAP report and the Selections pane and more.

The following unique OLAP functions, among others, can be performed only from the OLAP Control Panel:

– Selection of a Top or Bottom n rows report– Ability to group numeric data by percentile (or decile, quartile, and so on)– Advanced row selection criteria– Stacking of multiple measures vertically in a report as opposed to horizontally

Tip: If your OLAP Control Panel shows the selection criteria pane, click OK to return to the view shown in Figure 10-36.


2. We want to see our data in columns by quarter:

a. Expand Date Dimension.

b. Click the Drill Across box. When selected, it is surrounded by a blue rectangle.

c. Click the ORDERDATE_QUARTER field. It should appear in the Drill Across box. See Figure 10-37.

d. Click Run.

Figure 10-37 Specifying data in columns by quarter

Tip: If Quarter appears in the Drill Down box by accident, simply highlight it and use the Pivot button to pivot Quarter from rows to columns.


e. Double-click Quarter Q1 to drill down to month (Figure 10-38).

Figure 10-38 Cross-tab drill down

3. Often when you have multiple measures and sort across columns, the report can become wide and unwieldy. Open the OLAP Control Panel and select Stack Measures (Figure 10-39). Click Run.

Figure 10-39 Stack Measures option


There is a potential problem with this report as it stands right now. If the orders table contains data for multiple years, we now have the sales for every Q1 added up together (Figure 10-40). Although this is technically accurate, it probably is not what the user wants to see.

Figure 10-40 Stacked measures report


4. From the OLAP Control Panel, expand Date Dimension and select Values for ORDERDATE_YEAR (Figure 10-41).

5. In the window that opens (lower half of Figure 10-41) select the Range box. This is not appropriate for our data that only contains records from 2006 and 2007, but it is interesting to see the capability. Deselect Range.

For Year, select 2007 and click Add.

Figure 10-41 Filtering an OLAP report

6. At this point you can click Run. However, for demonstration purposes, click OK to see the full Selection Criteria pane.

Note: For most dimensions, when you click Values, you see the list of values from your table. The date components are prefilled in with general dates. If you expand ORDERDATE_MONTH, you see that the actual month names (that is, June) are filled in for ease of use for the user.


7. In the Selection Criteria pane (Figure 10-42), notice that Q1 is prefilled in for ORDERDATE QUARTER because we drilled down and selected Q1 prior to opening the control panel.

Figure 10-42 OLAP filtering

If you use the scroll bar on the right, you see all the various dimensions and their individual elements or columns that were available through the tabs in the Selection pane. You can continue to filter your data here.

If you want to filter on Product Type, you have two choices. You can click the down arrow next to Product Type or you can click Select. In both cases, you see a list of all the unique values for Product Type. Using the Select button takes you to a second window. This is easier to use when you are selecting multiple values.

Again, when filtering, you can modify the operand for each filtered column. Here we do not filter on Product Type.

Click Run.


Figure 10-43 shows the output of running the report.

Figure 10-43 2007 only report

8. If you are still on the Selection pane in the OLAP Control Panel, click OK to return to the initial layout. Notice that you can click Selection Criteria in the bottom right of the Control Panel to return directly to the Selection Criteria layout.

Note: Best practice states that you should always display any filters in effect on a report. DB2 Web Query has the capability from the OLAP Control Panel to document your filters at the beginning or end of your report.


9. In the Measures pane (Figure 10-44) select the Revenue check box. Then click the Revenue name.

Figure 10-44 Measures pane

10.In the Revenue pane (Figure 10-45), if we want to see a Top 3 analysis report:

a. Select the Sort check box.b. Select High to Low.c. Select the Rank (1, 2, 3 ...) check box.d. For Highest, select 3.e. For Measure Calculations, keep the default of None.

Figure 10-45 Top 3 OLAP report


Notice that if you expand Measure Calculations you can ask to see the Revenue column in multiple ways. For example, you can ask to see each Revenue as a percentage of the product type revenue in that quarter (Row Percent). You can ask to see the average revenue per order and much more.

10.4.3 Grouping data into percentiles

The reports and data used in these tutorials do not lend themselves to grouping into tiles (percentiles, deciles, quartiles, and so on), but you should be aware that this capability exists.

The example described in this section starts with a report that has one record for each sales person showing her revenue attainment. The company wants to reward the top 10% of its sales people. For example, if the company has 200 sales people, it wants to know who the top 20 people are. If the twentieth and twenty-first sales people are tied, the twenty-first sales person moves into the top 10% as well.

From the OLAP Control Panel (Figure 10-46), we highlight the revenue field LineTotal1 and click Sort.

Figure 10-46 Starting report showing sales people and their attainment

Tip: If you want to see a report that shows your bottom Products by revenue, sort from low to high and then rank and select your top three.


In the next pane (left in Figure 10-47), we choose a high to low sort sequence and then select the Tiles tab. On the Tiles tab (right in Figure 10-47) we select the options to tile the report in groups of 10 so that we can see our revenue numbers evenly split into 10 groups. We want the new column with the group number to be called Decile. If we only want to see the top 10%, we restrict the report to the first tile only.

If we want to see the top 5% of the sales people, we can ask the system to split the sales people into 20 groups and then we choose the top group. We can also split the sales people into 100 groups with 1% in each group. To get the top 5%, we choose groups 1–5.

Figure 10-47 Sorting LineTotal1 into groups of 10


Chapter 11. HTML Composer

HTML Composer is a component of IBM Developer Workbench. Prior to starting this set of tutorials, you must have completed Chapter 9, “Developer Workbench” on page 253.

HTML Composer is specifically designed, as the name suggests, to design HTML pages. HTML Composer does not create reports or graphs, but rather references existing ones. You can create compound reports with background style sheets and add company logos and other standard HTML components. The design of the HTML page can be set to match your company’s intranet standards.

Both HTML Composer and Power Painter can create compound reports. Power Painter is architected for PDF output and has additional controls specific to large PDF reports. It can also create other types of output such as HTML pages. HTML Composer is architected for HTML pages. It can only create HTML pages. It cannot create a PDF report. The products both have different user interfaces. You have already tried Power Painter. In this tutorial, you try HTML Composer. Choose the option that fits your company’s needs the best.

In this tutorial, we design two different HTML pages. The first is a compound report with a single input parameter. This style of report can be used as the basis for key performance indicator (KPI) dashboards where the user might request the KPIs for a specific country, product type, and so on. This type of report is often designed by IT and deployed to senior management and executives within a company.

The second report that we design is a single, highly parameterized active report. Again, this report is typically developed by IT but, in this case, is often deployed to business analysts or disconnected users who want to highly segment the data that they are analyzing. This tutorial assumes that you have completed the Active Reports tutorial (Chapter 8, “Active Reports” on page 233) and understand those concepts. Here we take an existing active report and initiate it from an HTML page that contains a large number of input parameters in a user friendly manner.

11


11.1 Compound parameterized report (HTML1_KPI)

In the first exercise, using two graphs and one report created in previous exercises, we add a common parameter and bring them together on one HTML page for the user. Figure 11-1 shows the final output page.

Figure 11-1 Compound report

11.1.1 Adding parameters to existing reports

In this tutorial, we do all our work from Developer Workbench. You can run Report Assistant and Graph Assistant from either Developer Workbench or the DB2 Web Query home page.

In Chapter 9, “Developer Workbench” on page 253, we introduce the two main functional areas of Developer Workbench. The first leg of the explorer tree expands through Data Servers to allow you to work with your metadata. The second branch expands down through Managed Reporting to allow you to work with the folder in your domains.


In this section we must add product type as a parameter to the three reports that we want on our KPI page. We modify the existing reports to accept this parameter and then save them under new names.

1. Open Developer Workbench. You see WebFOCUS Environments under Developer Studio Desktop. You may or may not see Windows Desktop. This is an optional setting described in Chapter 9, “Developer Workbench” on page 253.

2. Expand WebFOCUS Environments → your environment → Managed Reporting → Domains → Common Domain → Reports → Tutorials.

3. In your Tutorials folder, navigate to the graph GA3_Trend, right-click, and select Copy (Figure 11-2).

Figure 11-2 Developer Workbench reports

4. Keeping your cursor in the same pane (the list of your reports), right-click and select Paste. You now have a report titled GA3_Trend1 in the Tutorials folder.

Generic term report: The generic term report is used for both text reports and graphs. It is also used to refer to the completed HTML page. In the first exercise, the completed HTML page is a compound report.

Restriction: When accessed by Developer Studio, Report Assistant does not currently support the Save As capability. This is a known requirement. As a workaround, we use Copy and Paste to place the report in the same directory.

Chapter 11. HTML Composer 297

5. Right-click your new report GA3_Trend1 and select Rename. Give the report the name HTML1_KPI_LINE.

6. Right-click HTML1_KPI_LINE and select Edit in Developer Studio Tool (Figure 11-3).

Figure 11-3 Selecting the Edit in Developer Studio Tool option

7. DB2 Web Query knows which tool was used to create your report. Selecting the default option opens the report in either Report Assistant or Graph Assistant, whichever is appropriate. Power Painter is not directly supported in Developer Workbench. In this example, Graph Assistant opens.

8. In Graph Assistant, choose the Selection criteria tab.

Tip: Even though you rename the report in the window to HTML1_KPI_LINE, if you look in the integrated file system or look at the properties of the new report, you see that the object name is still ga3_trend1.fex. You have changed only the display title of the report, not the physical name on disk.


9. On the Selection criteria tab (Figure 11-4):

a. Delete all existing selection criteria.

b. Drag PRODUCTTYPE to the Selection pane.

c. Click Select values.

d. In the EQ Values window, select Parameter and then click Auto Prompt. Accept all the defaults for PRODUCTTYPE prompting. Click OK.

e. Back on the EQ Values window, click OK.

Figure 11-4 Selection criteria and parameter prompting

Notice in the Selection pane (Figure 11-5) that the Select values link has changed.

Figure 11-5 Completed selection criteria


10.Remove the months from the X axis labels to free more room in the small output frame for the graph itself.

a. Click the Properties tab and the X axis subtab (Figure 11-6).

b. On the X axis subtab, clear the Show axis labels check box.

Figure 11-6 Removing the X axis labels


c. Click the Options subtab (Figure 11-7).

d. From experience, we know that the frame for our graph is about 350 pixels wide by 250 pixels high. This can be an iterative process. You might need to design your HTML page, see how much room you have for your graph, and then return to the output options for the graph to ensure that it will fit in the designated space.

Set the output size to 350 pixels wide (Horizontal) by 250 pixels high (Vertical).

e. Save your graph.

Figure 11-7 Properties tab


11.We repeat the previous steps for the existing bar chart GA1_Bar. If you need more detailed assistance, refer to the previous steps and figures.

a. Copy and paste the GA1_Bar and rename it HTML1_KPI_Bar.

b. Add a PRODUCTTYPE parameter, accepting the auto prompting defaults. Your report should have only one parameter.

c. Set the output size to 350 pixels wide by 250 pixels high.

d. Click the Field selection tab (Figure 11-8).

e. Click Show - Field options. To save space for our graph, for the X axis field label field, delete Country.

f. Save your graph.

Figure 11-8 X axis field label deleted

11.1.2 Designing the layout for the HTML report

In this section we explain how to design the layout for an HTML report:

1. Open Developer Workbench.



3. Right-click the Tutorials folder and select New → HTML File (Figure 11-9).

Figure 11-9 New HTML file

4. Call your new report HTML1_KPI and click Create.

Tip: To create a text report or graph, select New → Procedure. You then see a window that allows you to choose between using Report Assistant, Graph Assistant, and the SQL Wizard to create your new report.


In the next subsections, we explain how to include a line chart, a bar graph, and the gross profit report. Figure 11-10 shows the final layout design of our compound report. The sections that follow refer to this figure unless otherwise noted.

Figure 11-10 Design layout for HTML report

Including a line chartTo include a line chart in the HTML report:

5. Click the graph icon from the toolbar (circled in Figure 11-11).

Figure 11-11 HTML Layout toolbar

6. Draw a box similar to the box in the upper left corner labeled 1 in Figure 11-10. Look at the properties box in the right pane. Your box should be 250 pixels high and 350 pixels wide. This is the size for which we designed our graph.

1 2

3


7. Right-click box 1 and select Reference existing procedure (Figure 11-12). This not only shows how the graph will look in this frame, but it also references any parameters that are used by the graph.

Figure 11-12 Reference existing procedure

8. Open your HTML1_KPI_Line file in the Tutorials folder. Notice that the actual file name is displayed (Figure 11-13).

Figure 11-13 Procedure being referenced


9. In the New Parameters window (Figure 11-14), the system presents a list of the parameters used in HTML1_KPI_Line.

a. For Control Type, accept the default of Drop-down list. b. For Parameter grouping options, select Do not create a form.

c. Click OK.

Figure 11-14 Defining a parameter

10.Delete the label PRODUCTTYPE. We reference Product Type in our overall report heading.

11.Move the drop-down list and the Run button as shown in Figure 11-10 on page 304. Your Run button looks slightly different at this stage.

New form element: If you accept the default New form element, the system creates a panel that contains your parameter label, the drop-down box, a Run button and a Refresh button, like the following example. We said no to this because we want to be able to move each of these elements separately on our page.


12.Select the line graph. In the Properties pane on the right, change Name to LineGraph (Figure 11-15).

Figure 11-15 Setting the name property


13.Click the drop-down control box in the report (circled in Figure 11-16). Click the Parameters tab in the lower right corner. Select the Add “ALL” option and specify to display All Products.

Figure 11-16 Adding the ALL option to a parameter

Including a bar chartTo include a bar chart in the HTML report:

14.Click the graph icon.

15.Draw a box similar to the box in the upper right corner in Figure 11-10 on page 304 labeled 2.

16.Select the Properties tab at the bottom of the right pane.

17.Right-click the new graph frame and select Reference existing procedure.

18.Select HTML1_KPI_Bar.

19.To make the two graph frames the same size, you can use the Properties pane and manually size the frames to both be 250x350.

We use the alternative to select both frame 2 and frame 1 by using the Ctrl key and clicking the Make same size icon ( ). Notice that it is the last element selected that controls the final size of all the selected elements.


20.Again select frame 2 and then frame 1 and click the Align top icon ( ).

21.In the Properties pane on the right, change the name to BarGraph.

Including the gross profit report (RA4_Advanced)To include the gross profit report:

22.Select the report icon (Figure 11-17).

Figure 11-17 HTML Composer toolbar

23.Draw a box similar to the box in the upper right corner in Figure 11-10 on page 304 labeled 3.

24.Right-click the frame and point to the RA4_Advanced report.

25.In the Properties pane on the right, set Size and Scrolling to No. This automatically adjusts the size of your frame so that your report fits in it and you do not have to scroll within the frame. Change the name to GrossPftReport.

HTML page optionsTo make this page look a little cleaner, we remove the frames around each of the reports:

26.Highlight each of the three reports.

27.From the Properties pane on the right, set Frame border to No.

28.To have the all three reports in our compound HTML page automatically run when the page is opened, highlight each of the three reports and from the Properties pane on the right, set Auto Execute to True.

29.Give the report a title.

a. Select the text icon (Figure 11-18).

Figure 11-18 Adding text to an HTML page

b. Draw a box in the pane where you want the report title to be.

c. Enter the text Product Type Indicators.

30.Click your text box so that it is surrounded by a straight line frame and not slashes.


31.In the Properties pane on the right, click the ellipsis button (...) next to Styling: Font.

32.Define the styling for your heading by selecting the following options: arial, 18pt, bold, underlined, and blue.

Executing the Run buttonFinally, we tell the system which reports must execute when the Run button is clicked:

33.Right-click the Run button and choose Hyperlink properties.

34.In the Hyperlink Properties window, change the display text to RUN and appropriately size the RUN button.

35.Click the add icon ( ) on the right.

36.The Run button is initially set to execute the original report that was used to import the parameter. We need to tell it to also execute our other two reports when the user clicks Run.

a. To add the second graph, for Action, select External procedure.

b. For Source, click the ... button, and navigate to and select HTML1_KPI_Bar.

c. For Target Name, select BarGraph to indicate which frame the report should run in.

d. Repeat the process and select the external procedure RA4_Advanced and point it to the frame GrossPftReport.

Your Hyperlink Properties window should look like the example shown in Figure 11-19.

Figure 11-19 Hyperlink properties

37.Save your report and then run it by clicking the Run icon (circled in Figure 11-20).

Figure 11-20 Run icon


Your dashboard or KPI should look like the example in Figure 11-21.

Figure 11-21 Completed compound report

11.2 Highly parameterized report (HTML2_Parm)

In this exercise, using an active report that we created previously, we add multiple parameters to it. This allows a user to segment the data that he wants to analyze in different ways. Although we base this tutorial on an active report, we can invoke any report or graph. This highly parameterized technique is effective for subsetting the data that a user wants to download to Excel.

Tip: You can return to the DB2 Web Query home page and run this dashboard. The easiest method is for a developer to stay within Developer Workbench and test from there. Do not forget that the page should be designed small enough to be viewed within the context of the DB2 Web Query home page.


This exercise uses the Active Report AR1_GrossPft, which is shown in Figure 11-22. You might want to quickly run this report and make sure that it looks like the example in Figure 11-22.

Figure 11-22 AR1_GrossPft Active report

To create the report:

1. Open Developer Workbench.


3. In your Tutorials folder, navigate to the AR1_GrossPft report, right-click, and select Copy.

4. Keeping your cursor in the same pane (the list of your reports), right-click and select Paste. You now have a report titled AR1_GrossPft in the Tutorials folder.

5. Right-click AR1_GrossPft and select Rename. Give the report the name HTML2_Parm_AR.

Tip: If your active report is in the accordion format, open the report, go to Report options, choose Active Report Styling and select Tabular for Report view. Save your report.


6. Open the new report. In the right pane, right-click HTML2_Parm_AR and select Edit in Developer Studio Tool (Figure 11-23).

Figure 11-23 Opening the report in Developer Workbench

7. Click the Selection criteria tab and enter, in sequence, the parameters shown in Table 11-1.

Based on this table, all the conditions are WHERE conditions. The table shows the field name to drag to the Selection criteria pane and the condition to use. For all parameters, click Select values. In all fields but ORDERDATE, select the Autoprompt wizard. In the Autoprompt pane, choose Select multiple values. Then click OK.

Table 11-1 Parameters for WHERE conditions

Field name Condition Select values

WHERE PRODUCTTYPE EQUAL to � Select parameter.� Autoprompt.� Select multiple values.

WHERE PRODUCTCATEGORY EQUAL to � Select parameter.� Autoprompt.� Select multiple values.

WHERE SALESREP EQUAL to � Select parameter.� Autoprompt.� Select multiple values.

WHERE COUNTRY EQUAL to � Select parameter.� Autoprompt.� Select multiple values.

WHERE REGION EQUAL to � Select parameter.� Autoprompt.� Select multiple values.

WHERE STATE EQUAL to � Select parameter.� Autoprompt.� Select multiple values.

WHERE PLANTNAME EQUAL to � Select parameter.� Autoprompt.� Select multiple values.

WHERE ORDERDATE GREATER THAN or EQUAL to

� Select parameter.� Enter field name From_Date under

Parameter (do not autoprompt).See Figure 11-24.


8. For the date fields, instead of using the Autoprompt wizard, enter a parameter name that you want to use (Figure 11-24). We use From_Date for the first date parameter and To_Date for the second date parameter.

Figure 11-24 Date parameter

The finished Selection criteria pane should look like the example in Figure 11-25.

Figure 11-25 Selection criteria parameters

9. Save and close the report.

WHERE ORDERDATE LESS THAN or EQUAL to

� Select parameter.� Enter field name To_Date under

Parameter (do not autoprompt).

Field name Condition Select values


11.2.1 Creating the report in HTML Composer

To create the report in HTML Composer:

10.Navigate to the Tutorials folder in Developer Workbench. Right-click Tutorials and select New → HTML File (Figure 11-26).

Figure 11-26 Creating a new HTML file

11.In the window that opens (Figure 11-27), enter a report name of HTML2_Parm and click Create.

Figure 11-27 New report name

12.In this example, we create an HTML page that contains the various parameters and a Run button. When the Run button is clicked, a new window opens that contains the active report. We must import the report onto the HTML page so that DB2 Web Query automatically brings in all the parameters that are defined in the report, saving us from


adding them manually. We remove the report frame itself after we import all the parameters.

Click the report icon (circled in Figure 11-28) and draw a small box in the upper left corner of the pane.

Figure 11-28 Importing a report

13.Right-click the report (the box that you just drew) and select Reference existing procedure (Figure 11-29).

Figure 11-29 Link to existing procedure

14.Select the HTML2_Parm_AR report that you just created.


15.You are presented with a list of parameters that are referenced by this report (Figure 11-30).

a. For SALESREP, change the control type to Double list control.b. For COUNTRY, change the control type to Radio button.c. For PLANTNAME, change the control type to Check box.d. For both dates, change the control type to Calendar.e. Under Parameter grouping options, select Do not create a form.

Figure 11-30 Selecting the parameter control types


The system lays out all the chosen parameters in a column on the HTML page similar to the layout in Figure 11-31.

Figure 11-31 Imported parameters


16.Making sure that you keep the headings and controls together, drag the parameters into a layout similar to Figure 11-32. You must scroll to see the entire page of parameters. See the following steps to size the Country control box.

– Make sure that you leave enough room at the top of the report for a report heading.

– Some of the boxes, such as SALESREP, require resizing. Keep any frames that are within a panel in the panel when they are moved or resized.

Figure 11-32 Rough layout for parameters

Note: This exercise is designed to introduce you to many of the controls and capabilities of HTML Composer. Is it not intended to teach window design. Do not design a window that has this many different controls and looks like this in production applications.


17.We want to change Country from one column widths to two columns widths (Figure 11-33):

a. Highlight the Country control box.b. From the Properties pane, select columns and type 2.c. Size the control box appropriately.

Figure 11-33 Two-column radio control box

Parameter controlsIn this section we illustrate how to define the sequence in which the cursor moves from cursor to cursor, also known as parameter controls:

18.Highlight the Producttype control box.

19.In the Properties pane on the right, select Tab index and enter 1. The Tab index controls the sequence in which the cursor moves from field to field.

20.Click the Parameters tab at the bottom of the right pane. This is where you can override options such as your type of control box or the text to go with the ALL option. Select the add ALL option for every parameter except the dates.

21.Highlight the Productcategory control box.


22.Click the Properties tab (Figure 11-34) and under Tab index, enter the value 2.

Figure 11-34 Properties tab


Chaining the controls togetherWe want to set up our parameters so that the value selected for product type modifies (filters) the values that are displayed in the product category drop-down list:

23.Click the producttype control box. Holding down the Shift key, also select Productcategory.

24.Click the Add chain icon (circled in Figure 11-35). This function chains the parameters together in the sequence in which you selected them.

Figure 11-35 Chaining parameters

25.Highlight the Salesrep control. In the Properties pane, for Tab index, type 3.

26.Highlight the Country control. In the Properties pane, for Tab index, type 4.

27.Highlight the Region control. In the Properties pane, for Tab index, type 5.

28.Highlight the State control. In the Properties pane, for Tab index, type 6.

29.We want the Country parameter to control or filter the Region parameter, and we want the Region parameter to filter the State list box. To chain Country to Region to State:

a. Select the Country control box.

b. Hold down the Shift key and select the Region control box. Still holding down the Shift key, select the State control box.

c. Click the Add chain button shown in Figure 11-35.

30.Highlight the Plantname control. In the Properties pane, for Tab index, type 7.

Tip: If you right-click a control box that is chained to another control, you can override the chaining logic. The default in our example shows all product categories that have a product type equal to what the user selected. You can choose any relationship to the controlling parameter, which is less than, greater than, and so on. In our example, EQUAL is really the only choice that makes sense and it is always the default.


Using calendar controlsIn this section we illustrate how to define the controls when dealing with Date fields:

31.Right-click the calendar icon under From_Date and select Calendar Properties.

32.For Date range, select Static. Specify a range from January 1 2006 to December 31 2007. For Date format in data source, select YYMD. Click OK. See Figure 11-36.

33.Highlight the From_Date control.

34.In the Properties pane, for Tab index, type 8.

35.Repeat these calendar control steps for To_Date using a Tab index of 9.

Figure 11-36 Calendar controls

36.Right-click the Run report1 control box and select Hyperlink Properties.

Tip: The more common calendar option is probably relative dates, for example, within the last two years. Since our data only contains dates in 2006 and 2007, we chose the static dates for this example.


37.In the Hyperlink Properties window (Figure 11-37), complete these steps:

a. Change Display Text to RUN.

b. Change Target Type to Window. This runs the report in a new window instead of in the frame drawn on the current HTML page.

Figure 11-37 Hyperlink properties RUN

38.Delete the original frame that you drew when importing the report. It is located below all the parameters.

39.Select the RUN control box. In the Properties pane, for Tab index, type 10.

40.Resize the Run button by dragging the frame.

41.Add a heading to the report:

a. Click the text icon on the toolbar and draw a box to contain your heading (Figure 11-38).

Figure 11-38 Adding text to a page

42.Enter a title of Gross Profit Active Report.

43.Click your text box so that it is surrounded by a straight line frame and not slashes.

44.In the Properties pane on the right, select the ... button next to Styling: Font.

Note: In addition to text and reports, you can import images to your page using the icon to the left of the text icon. You can use define cascading style sheets to tailor the look of your page.


45.In the Font window (Figure 11-39), select the styling for your heading:

a. For Font, select Arial.b. For Font Style, select Bold.c. For Size, select 18pt.d. For Effects, select Underline. Click OK.

Figure 11-39 Styling text

46.Click the background area of the HTML layout.


47.In the Properties pane, click the ... button next to Background color and select a pale color (Figure 11-40).

Figure 11-40 Background color

48.When we modified all the parameter control boxes, we changed the tab index in the Properties pane. This controls the sequence that the users tab through the fields in the window. We still have a problem in that some of the other elements on the page have a tab index that might conflict with our sequence numbers.

Starting with the title, highlight the frame and find the tab index number. If it is less than or equal to 10, change it to an arbitrary number above 20. The Run button had a tab index of 10 and we want it to be last in our normal sequence. Do not forget to check the arrow elements in Salesrep.

49.Save and run the report.

Tip: If you hover over the icon second from the left that looks like a hand and multiple small boxes, you should see the text Tab Order. Selecting this shows the sequence of your tabs for the user. Make sure that you do not have duplicates and that the order is left to right, top to bottom for INPUT-capable fields.


50.For our first test, select ALL for Salesrep and 2006/01/01 to 2006/12/31 for the dates (Figure 11-41).

Figure 11-41 Prompting for parameters

Tip: Having chosen the double list control for Salesrep means that you always must select at least one item for SALESREP. This can be ALL, but there must be a value in the output list.


51.Click RUN. Figure 11-42 shows the output of running this report.

Figure 11-42 Final output

At this point, you can try and run the report, taking advantage of the parameter chaining. Selecting a product type changes the product categories list box. Similarly, choosing a region changes the state displayed.

Then go back to your parameter design page and start tailoring the page to look like a more practical report that you might show to a user.

Providing multiple report output format options for usersIn some cases your users may want to choose the output format dynamically at run time. For example, user OZZIE may want the Gross Profit report to be generated as an Active Report, while user ARCH prefers that same report to be presented as a PDF file, and SHANEG is a power Excel user and likes his reports as spreadsheets. While there currently is not a setting within the development tools to set up this type of feature, it can be accomplished by creating multiple copies of the reports and setting up buttons to call the appropriate report. In this section, you learn how to provide this type of report output flexibility.

For each desired output format that you want to provide to your users, take the following steps:

1. Make a copy of the report.2. Edit that report and change the output format.3. Rename the report to something meaningful (to represent/indicate the output format).4. Create a new button in the HTML page.5. Change the text of the button so that users know what output format it represents.6. Change the properties of the button to call the appropriate report when pressed.


The process is explained in detail in the steps below:

1. Open DB2 Web Query in a Web browser session, right-click the report HTML2_Parm_AR, and select Open, as shown in Figure 11-43.

Figure 11-43 Open report

The report opens in the Report Assistant development tool.

2. Go to the Report options tab and change the Generate report as setting from AHTML- Active Report to PDF - Portable Document Format, as shown in Figure 11-44.

Figure 11-44 Change output format to PDF


3. Create a new copy of the report by clicking Save As and name the report HTML_PARM_PDF, as shown in Figure 11-45.

Figure 11-45 Save new report

4. Return to the HTML2_PARM file already open in DB2 Web Query Developer Workbench.

5. As shown in Figure 11-46, click the Push button icon to create a new button on the form.

Figure 11-46 Create new button


6. Use the crosshairs to draw the new button on the palette. The new button will be simply labeled Button. This is demonstrated in Figure 11-47.

Figure 11-47 Draw new button

7. To define the action that occurs when user click it, right-click the new button and select Create hyperlink, as shown in Figure 11-48.

Figure 11-48 Create hyperlink for button


8. From the Hyperlink Properties dialog window, change the Display Text field to PDF and click the new Action icon, as demonstrated in Figure 11-49.

Figure 11-49 Hyperlink properties

9. Select External procedure as the Action, click the ellipsis icon under Source, and (from the list of presented procedures) select HTML2_PARM_PDF as the report to run. An example is displayed in Figure 11-50.

Figure 11-50 More hyperlink properties

10.Click the Open button to accept this report as the source and return to the Hyperlink Properties dialog.


11.To display the PDF report in a new browser window, select Window for the Target Type setting and New window for the Target/Template Name. When finished, it should look like the example shown in Figure 11-51.

Figure 11-51 Completed hyperlink properties

12.Click OK to accept the changes.

13.Click the Save icon to save your changes

14.Run the report and click the new PDF button to test it. You should see the report displayed in PDF format, as shown in Figure 11-52.

Figure 11-52 New PDF report


15.For additional output formats such as Excel spreadsheet, repeat the above steps and substitute the new output format for PDF.

16.Close the window.

11.2.2 Additional parameter tips

This section describes additional techniques that can be used to provide more control over how report parameters are displayed and handled.

Displaying the values of one column while passing anotherWhen developing DB2 Web Query reports that require prompt control (input parameters), you may run into a requirement to present a drop-down list that is based on a column in your database (for example, product name) but actually pass the value of a different column (such as product number) as the input parameter value. This can be accomplished by utilizing the display field feature of HTML Composer in DB2 Developer Workbench.

To set up a report and html page that utilizes this feature:

1. Using Report Assistant, create a new report against CEN_ORDERS. The sort fields are PRODUCT NAME and PRODUCTNUMBER, and the measure is LINETOTAL (include commas and floating currency for formatting). An example is shown in Figure 11-53.

Figure 11-53 New report specifications


2. Go to the Selection criteria tab and add PRODUCTNUMBER as a screening condition. Define it as a multi-value prompt control parameter that is based on PRODUCTNUMBER in CEN_ORDERS. An example is provided in Figure 11-54.

Figure 11-54 Set up prompt control parameter for PRODUCTNUMBER

3. Save the report as ra6_parm.


4. Run the report with No Selection. It should look like the example shown in Figure 11-55.

Figure 11-55 Example of ra6_parm report

5. Return to the Developer Workbench tool and create a new HTML file in your Tutorials folder, as shown in Figure 11-56. Name the new html file html3_parm.

Figure 11-56 Create new HTML file for ra6_parm


6. In the HTML Composer tool select the report icon to add a new report to the layout (Figure 11-57).

Figure 11-57 Add report to layout

7. Using the crosshairs, draw/outline the location of the report on the canvas.

8. Right-click the report outline and select Reference Existing Procedure.

9. From the list of reports displayed, select ra6_parm. The New Parameters dialog window is presented.

10.From this window, select Do not create a form under Parameter grouping options, then click OK.

Figure 11-58 Parameters for ra6_parm report


11.Move the elements around on the canvas as shown in the example in Figure 11-59.

Figure 11-59 Move elements on canvas


12.Select the parameter listbox element and on the Properties dialog select the Parameters tab on the bottom (Figure 11-60).

Figure 11-60 Select parameters tab


The properties for the PRODUCTNUMBER parameter are displayed as shown in Figure 11-61.

Figure 11-61 Parameter properties


From the list of field names displayed, select the PRODUCTNAME field and drag it into the area under Display field. An example is shown in Figure 11-62.

Figure 11-62 Make PRODUCTNAME the Display field

13.Click the Run icon to test the report.

Notice that the drop-down list is populated with product names rather than the product numbers.


14.Select multiple product names in the list (by selecting them and holding down the Ctrl key on your keyboard) and click Run Report1. Your results should look similar to the example in Figure 11-63.

Figure 11-63 Example of report that displays one column as parameter but passes another

The drop-down list on the HTML page is populated with product names, yet the value of the correlating ProductNumber column is passed to the underlying report. Because ProductNumber is the parameter that the report is expecting, the report is able to find and display the appropriate rows.

15.Close the browser window.

16.Back in the HTML Composer session, save the report.

17.Close the HTML Composer session.

Using another report to control parameter sorting and filteringAnother useful feature that can be implemented in HTML Composer is the ability to use another procedure (another term for a report) to control the parameter list sorting and filtering. This is useful, for example, if you have a report with a prompt control parameter of the OrderDate column, but you would like the drop-down list sorted in descending order (rather than the default, which is ascending). You would also like to filter this list to only show dates for the year 2007.

To illustrate how this can be set up, the following three components are created in this exercise:

� The base report with prompt control of OrderDate. This report shows revenue for the selected OrderDate by country and region.

� Report (procedure) that sorts by OrderDate in descending order and only includes rows for the year 2007. This report is generated to XML output format.

� HTML Layout that calls the base report and uses the procedure to populate and sort the drop-down list.


The following steps

1. Launch Report Assistant to create a new report based on the CEN_ORDERS synonym.

2. Sort the report by ORDERDATE, COUNTRY, and REGION.

3. Drag LINETOTAL into the Sum pane and specify column formatting of commas and floating currency. An example is shown in Figure 11-64.

Figure 11-64 Using a procedure to sort the parameter list: base report

4. Set up the a prompt control parameter over the ORDERDATE column by doing the following:

a. Drag the ORDERDATE field from the list of available fields into the Screening conditions pane.

b. Click the <Select Values> link.

c. Select the Parameter setting and click the AutoPrompt icon.

d. Select ORDERDATE from list of fields.


These steps are shown in Figure 11-65.

Figure 11-65 Set up prompt control for ORDERDATE

5. Click OK twice.

6. Save your report as Revenue for Selected Order Date.

7. Run your report. Use the prompt control.

Notice that OrderDates are listed in the drop-down list and are sorted in ascending order, as shown in Figure 11-66.

Figure 11-66 Report with prompt control for OrderDate


The behavior that you really want for this drop-down list is to present the OrderDates in descending order. You would also like to filter this list so that only order dates for the year 2007 are presented and can be selected by the user.

To obtain this behavior, you must create another report (procedure) and use it to handle the parameter sorting and filtering.

8. From the Tutorials folder, launch Report Assistant to create another report.

9. Select the CEN_ORDERS synonym.

10.From the list of available fields, specify ORDERDATE as the Sort by field. Do this again so that there are two ORDERDATE columns in the Sort by pane. Change the Sorting of the first ORDERDATE column to Descending order, as shown in Figure 11-67.

Figure 11-67 Order by ORDERDATE in descending order

Next filter the list so that only entries for 2007 appear.

Important: The procedure must return a name and value pair for each parameter value that will populate the list. The first value is the submission value, which is passed to the form control when you click the Submit button. The second value is the display value, which is what you will see in the control. These two values can be the same or different.

The procedure must return the two data values in XML output format.


11.Go to the Selection criteria tab and select the ORDERDATE_YEAR column as a screening condition. Click the <Select Value> link and specify the value 2007 as a Constant. This is demonstrated in Figure 11-68.

Figure 11-68 Filter the drop-down list for year 2007

The last step is to specify XML as the output format.


12.Select the Report Options tab and select Show unstyled formats from the drop-down list at the top. Taking this action causes the list of report output formats to change. From this re-populated list, find and select XML - eXtensible Markup Language. This is demonstrated in Figure 11-69.

Figure 11-69 Change output format to XML

13.Save this report as Parm Sort Procedure.

The final piece of the puzzle is building the HTML layout. This component uses the procedure to sort and filter the drop-down list and will reference the base report to execute the query and display the results.

From the DB2 Web Query Developer Workbench, create a new HTML file in the Tutorials folder, as shown in Figure 11-70.

Figure 11-70 Create HTML Layout for report

14.In the HTML Layout canvas, insert a report and reference the existing procedure Revenue for Selected Order Date.


15.On the New Parameters dialog, select Do not create a form and click OK, as shown in Figure 11-71.

Figure 11-71 New Parameters dialog

16.Select the ORDERDATE parameter element displayed on the canvas and select the Parameters tab at the bottom right of the window, as shown in Figure 11-72.

Figure 11-72 Select parameter

The Parameters pane appears on the right.


17.Under Control Values, select Procedures and click the ellipsis icon to present a dialog from which you can select the procedure. From this dialog, select the procedure named parm sort procedure and click Open.

Figure 11-73 Select procedure to control the values of the parameter

With this setting, the list of parameter values displayed in the drop-down list will be controlled by the parm sort procedure report. This includes the sorting and filtering defined in this report.

18.Save the HTML.

19.Close the HTML Composer session.

20.Return to the Web browser and run the report.


Notice that the list is sorted in descending order by order date and only dates for the year 2007 appear in the list.

Figure 11-74 Report with parameter values sorted in descending order


Chapter 12. Additional features of Developer Workbench

In this chapter we cover the following additional features of Developer Workbench:

� Synonym Editor

– Metadata– Date decomposition– Creating filters– Joining tables– Business views– Impact analysis– Data profiling

� SQL Wizard

We provide a short tutorial for each feature so that you can see how to use it. There are many more capabilities within each feature than are described in this chapter. See the online help text in Developer Workbench for more details.

12


12.1 Synonym Editor

DB2 Web Query can create basic metadata from the DB2 Web Query home page or via the Synonym Editor in the optional, but highly recommended, Developer Workbench tool. When the basic metadata exists, you must use the Synonym Editor if you want to enhance the metadata or take advantage of the more advanced metadata capabilities. Within Synonym Editor, you can change the way that a field is displayed to the users. In our previous examples, if we add commas and floating decimal signs to LINETOTAL in the metadata, then the developers never need to do this in the individual reports. Other examples include converting date formats, converting alpha to numeric fields, or changing the length of a field.

The Synonym Editor also allows you to create new calculated fields for the users. This includes the ability to break dates down into their various components. If you plan to use the optional online analytical processing (OLAP) feature, you must define your hierarchies or dimensions through the Synonym Editor. For more details about defining hierarchies for OLAP use, see Chapter 10, “Online analytical processing” on page 261.

1. To start the Synonym Editor, expand the metadata portion of the WebFOCUS Environments. Expand WebFOCUS Environments → your environment → Data Servers → EDASERVE → Application → baseapp.

Tip: Basic synonyms can be created from within Developer Workbench using the same routines that are used from the DB2 Web Query home page. Right-click baseapp and select New → Synonym to invoke the metadata creation windows.


2. In the right pane, select the table that you want to open in Synonym Editor. In this tutorial, we select cen_orders.mas. Right-click and select Edit in Synonym Editor (Figure 12-1).

Figure 12-1 Starting the Synonym Editor

Chapter 12. Additional features of Developer Workbench 353

The window changes to show the different attributes of the table that are stored in the metadata (Figure 12-2). Look at the file attributes that are available. Some of the attributes, such as DBSPACE, are not applicable to DB2 for i5/OS.

Figure 12-2 Metadata: orders master file

Important: The Synonym Editor does not allow you to make any changes that render the master file unusable.


3. Highlight LINETOTAL to see the metadata attributes of the field displayed (Figure 12-3). In this example, we want LINETOTAL to display in reports with commas and a floating dollar sign. When we make this change, the report uses these settings by default.

Figure 12-3 Field-level and column-level attributes

Tip: The display in Figure 12-3 also allows users to specify a description and title for a column. User’s can set up multiple titles for a column based on the language of the user. Selecting the ellipsis (three dots) next to these attributes allows you to specify which title you want displayed based on the language chosen.


Another interesting attribute on this display is the USAGE attribute (Figure 12-4). To demonstrate this, highlight and select ORDERDATE in the Column pane.

Figure 12-4 Date field attributes

In the Attribute pane, ACTUAL refers to how a column is stored in DB2 for i5/OS. USAGE refers to how the user sees and works with a column. USAGE allows us to override or change the length and attributes of a column from how it is stored and displayed by default.

For many System i customers, USAGE becomes important for date fields. If you have a field defined to DB2 as an integer 8 field that happens to contain the value 20070901, there is no automatic way for DB2 Web Query to know that this is a date field. The ACTUAL for this column displays as integer 8. Using the powerful USAGE attribute allows you to specify a USAGE of type Date with a format of YYMD. This enables many of the date and time functions, calculations, and formatting options that are available in DB2 Web Query to work with your integer field.

12.1.1 Date Decomposition

In many of the reports that we have created so far we have broken the date field into years, quarters, and months. This is a common requirement. To save you from doing this manually in every report, DB2 Web Query provides the Date Decomposition feature to automatically decompose the date in the Synonym Editor.


4. Right-click the ORDERDATE field and select Decompose Date (Figure 12-5).

Figure 12-5 Decompose Date column

5. In the Decompose Date Column window (Figure 12-6), select all four subcomponents of ORDERDATE to be created for you. Click OK.

Figure 12-6 Decomposed date


In the results shown in Figure 12-7, notice that the system has generated four new fields for the users to access.

Figure 12-7 Results of decomposing a date

12.1.2 Additional date manipulation

Our QWQCENT database stores dates in the DATE format. We know that many System i customers do not store dates in the DATE format. We add a few suggestions for how you might want to work with dates that are stored in alphameric or numeric formats. For example, 20070914 might be stored as a char 8 field.

Note: You can manually create these fields by right-clicking a column or the table and specifying Add → Virtual column. This allows you to create any new column that you normally create during the report definition stage. Creating it here means that it is available to all reports.

Creating a column, such as PROFIT, in the metadata means that the definition of the column is standard across all your reports.


First highlight your date column. In this case, the date field is called DATEA8. Then modify the ACTUAL attribute from A8 to A8YYMD assuming that your date is stored in the format 20070914. You can also modify it to A8DMYY (Figure 12-8) if you stored your date as 14092007. If you have a six-character field, change the YY to simply Y. That is, tell the system that you have a two-character year instead of a four-character year. This also works if your date is stored as a numeric or packed field.

Figure 12-8 Defining your current character or numeric date field

Having made these changes, your users can now do basic date formatting. In a report, the user can choose to format the field as a YYMTRD field. This prints the date in the report as 2007, SEPTEMBER 14. The user can also create separate year, month, and day fields from this date.

To use various date functions and date arithmetic, create a true DATE field. That is, create a define field with your new date field name. The format is similar to YYMD. The expression is your original numeric or alpha date field that you formatted as A8YYMD.

As shown in Figure 12-9, you can now use the PROPERDATE field to do date arithmetic or use date functions, such as adding seven business days to a date or finding the end of the next quarter. These functions are described in “DB2 Web Query date built-in functions” on page 572.

Figure 12-9 Redefining a character date

If you use two-digit years, you can use the DEFCENT and YRTHRESH column attributes to define your century. If the year is greater than or equal to the threshold (YRTHRESH), then the two additional significant digits in the year become equal to the default century value (DEFCENT). If your two-digit year is less than YRTHRESH, then the additional two digits equal DEFCENT plus one.

Assume that YRTHRESH equals 40 and DEFCENT equals 19. Any year from 40 to 99 is translated to 1940–1999. Any year from 00 to 39 is assumed to be 2000–2039. If you use a


century field, you can create your own formula in a define field to calculate a new date field correctly.

If you store year, month, and day in individual fields, you must first create an interim field that has the format of A8YYMD (or A6YMD) and equals YRFLD | MTFLD | DAYFLD. Then, using this interim field, you create a new date field, as shown in Figure 12-9 on page 359.

After you create your new date field, this is the one that the users use in all their reports. This format opens up many additional date formatting and arithmetic functions.

12.1.3 Creating filters

You can predefine standard selection criteria in the master file. This allows the criteria to be specified once and used in multiple reports. In this example, we create a filter called Europe. This allows us to easily run a report including European only countries.

6. Right-click the master file name segment that contains the field that you would like to filter and select Add → Filter, as shown in Figure 12-10. In this case, we want to filter on the Country field, which exists in our T4_STORES segment.

Figure 12-10 Adding a filter to a master file

Note: Find the STORES segment because yours might not be T4.


7. In the Filter Calculator window (Figure 12-11) go to Column, type Europe, and define it as an I1 (integer one long) column. This means that we can test if for true or false in our reports. Double-click COUNTRY under the STORES segment to add it to the filter. Change the Relations to CONTAINS because we must provide multiple countries for the value.

Figure 12-11 Creating a filter


8. Double-click the countries or use the > button to move the selections to the right-hand side in the Value(s) Selection window (Figure 12-12). Click OK to close the Value(s) Selection window and then click OK to close the Filter Calculator window.

Figure 12-12 Creating a Filter Detail

9. Verify that it looks like the filter in Figure 12-13.

Figure 12-13 Completed filter


10.The filter is displayed in your list of column names when you create a report. Drag the filter to the Selection criteria pane. A WHERE filter is true statement is generated by default. This report now includes only the countries that are defined in the Europe filter (Figure 12-14).

Figure 12-14 Using predefined filter


12.1.4 Joining tables

If you are unable to define foreign keys in your DB2 tables, you can accomplish the same result for users who are using Developer Workbench. In this example, we start by working with the orders table without using foreign key support. We then join this table to the inventory table that we already defined. This creates a cluster join where the two tables look like one to the user.

1. Create another synonym for the orders table, but without selecting Foreign Key support. Use either the DB2 Web Query home page or Developer Workbench.

In Developer Workbench, expand WebFOCUS Environments → your environment → Data Servers → EDASERVE → Applications → baseapp. Right-click and select New → Synonym (Figure 12-15).

Figure 12-15 Creating synonyms from Developer Workbench


2. In the Create Synonym window (Figure 12-16), since our table is a normal DB2 for i5/OS table stored on our local system, select *LOCAL and click OK.

Figure 12-16 Creating metadata for local DB2 tables


3. In the next window (Figure 12-17), specify that the candidates for synonyms are the list of tables in the QWQCENT library. Select the Tables check box and make sure that the Views check box is cleared. For Library, select qwqcent. Then click Next.

Figure 12-17 Filtering synonym candidates


4. In the next window (Figure 12-18), for Select application, ensure that baseapp is selected and select only the ORDERS table. Do not select “with foreign keys”.

We do not need to create a synonym for the INVENTORY table, as we did that in an earlier exercise.

Click Create Synonym.

Figure 12-18 Selecting tables

5. After you see the window that indicates that the synonym for the ORDERS table was created successfully, click Open (Figure 12-19).

Figure 12-19 Successful creation of a synonym


6. In Developer Workbench, right-click ORDERS and select Add → Segment from Existing Synonym (Figure 12-20).

If metadata for INVENTORY is not yet created, you can select Add → Segment Via Metadata Import.

Figure 12-20 Adding a segment or secondary table

Note: You can add your join from the Modeling view tab at the bottom of the window as well as from the Tree View. Most of the steps are identical. From the Modeling view, right-click the table icon and select Add → Segment from Existing Synonym.


7. In the Select Synonym window (Figure 12-21), select cen_inventory as the table to join to ORDERS. Click Select.

DB2 Web Query creates a default join between the two tables.

Figure 12-21 Selecting the secondary join table


8. In the Developer Workbench window (Figure 12-22), in the right pane, for SEGTYPE, the join defaults to Multiple or a one-to-many join. If you want to specify a one-to-one join, change Multiple to Unique.

In the left pane, to see and possibly modify the join type and join conditions, right-click CEN_INVENTORY and select Join Properties.

Figure 12-22 Specifying Join Properties

Tip: If you are using the Modeling view, either click the file icon or double-click the arrowed lines between the files to see the join properties.


9. In the Join Properties window (Figure 12-23), notice that DB2 Web Query has chosen an Inner Join, where Product Number from both tables is equal.

From this window, you can override the join type and join conditions that you require. Click OK.

Figure 12-23 Default join

12.1.5 Business View

The Business View allows you to define a logical view of your data typically to simplify ad hoc reporting for the user. With the Business View, you can simplify the fields in your master file.

In a view, fields can be grouped into folders for logical partitioning of the data elements. You can choose to have a folder that contains all the elements of an employee’s address or you might want a folder that stores all your filters selected from the master file synonym.

The Business View also allows you to specify changes to your underlying table, such as new column headings, format changes, and so on. These changes are not lost if you need to reimport the underlying table. If you make these changes in the master file for the base or underlying table and you must recreate the synonym for that table, you lose many of the attributes that you changed.


In addition, the Business View enables you to add define and compute fields to a table so that all users have access to them in their reports. The new define fields or virtual columns can contain system variables such as &DATE or the current user name. The current user name can be retrieved using the GETUSER function.

1. From the Synonym Editor (Figure 12-24), right-click cen_orders and select Create Business View.

Figure 12-24 Creating a Business View

2. In the next window, you can create folders (right-click) and drag columns, defined fields, computed fields, or filters to your view.

Create the business view shown in Figure 12-25.

Figure 12-25 Business View


This view is now available to the user who is creating reports just like the original orders table cluster is doing.

12.1.6 Impact Analysis

If you are changing a table layout, you can use Impact Analysis to determine the effects of the change on existing reports or business views.

3. To find the reports in the Common Domain that would be affected by a change to the Orders cluster, navigate to Common Domain, right-click, and select Impact Analysis (Figure 12-26).

Figure 12-26 Starting Impact Analysis

Tip: If you create a business view for a user, the user can open Power Painter and drag the entire business view to the Power Painter palette, instantly creating a report that uses all the columns in the view. This allows the user to basically create a one-step report.

Tip: To see all reports that are affected across all folders and all domains, right-click one level higher on Domains.


4. In the Open window (Figure 12-27), double-click baseapp to see all our tables and views. In the baseapp folder, select Cen_orders.mas and click Open.

Figure 12-27 Selecting a master file


5. At this point, you can either analyze the impact of modifying individual fields or find any report that references the cen_orders table.

In the Developer Studio - Impact Analysis window (Figure 12-28) click Analyze to find all reports that access any column in the cen_orders table.

All reports in the Common Domain that use the Cen_orders table are listed in the bottom pane.

Figure 12-28 Impact analysis results

Tip: To find the business views that use a specific master file or column, open the table in the Synonym Editor and right-click the table or column name and choose Impact Analysis.


12.1.7 Data profiling

Developer Workbench provides the capability to profile your data. Profiling allows you to see both of the patterns in the actual text characters. In Figure 12-32 on page 378, you can see the four different patterns of postal codes that you have in your data. These patterns might be acceptable because the different patterns represent different countries, or they might indicate data quality issues.

Data profiling also shows the minimum and maximum values in a column and identifies 10 possible outliers. This is done by showing you the 10 highest and 10 lowest values in a column, as seen in Figure 12-33 on page 379.

1. To start the Synonym Editor, expand the metadata portion of the WebFOCUS Environments. Expand WebFOCUS Environments → your environment → Data Servers → EDASERVE → Application → baseapp.

2. You can profile all the columns in a table by selecting Data Profiling or selecting an individual column to profile.

Choosing data profiling at the table level can take a while. Every column in the table is analyzed. The system looks at such items as patterns in the layout of the data in a column; average, minimum, and maximum values; and the length of the data. The number of distinct values is calculated. The number and percent of null values in a column is also calculated. In our example, we profile all the columns in the cen_orders cluster table.

After opening cen_orders in the Synonym Editor, right-click cen_orders and select Data Profiling (Figure 12-29).

Figure 12-29 Selecting the Data Profiling option


3. A summary report is produced like the example shown in Figure 12-30. Notice that the fields in blue contain hyperlinks. Click POSTALCODE to see output similar to that shown in Figure 12-32 on page 378.

You can profile an entire table, receive this type of a summary hyperlinked chart, and drill down into the various options. Another way to obtain these options is to directly profile the field.

Figure 12-30 Data profiling results at a table level


4. Return to the list of columns shown in Figure 12-31. This time we profile an individual column rather than the entire file.

Right-click POSTALCODE and select Data Profiling → Statistics. Notice the different choices that you have when profiling a field.

Figure 12-31 Data Profiling selection at a field level

In the Data Profiling window (Figure 12-32) you can see the values and patterns associated with POSTALCODE either by selecting them from the data profiling submenu or by clicking the appropriate columns in the output report from the statistical analysis.

Figure 12-32 Data profiling results at the field level


5. To see data outliers, switch to the QUANTITYINSTOCK column. Return to the list of columns (Figure 12-33), right-click QUANTITYINSTOCK, and select Outliers.

Data outliers are the 10 highest and 10 lowest values for a column.

Figure 12-33 Data outliers

12.2 SQL Wizard

In addition to working with the metadata, Developer Workbench includes report development tools. You can directly access Report Assistant and Graph Assistant from within Developer Workbench. One developer’s tool that is unique to Developer Workbench is the SQL Wizard.

With the SQL Wizard, we have three different ways to provide SQL statements to DB2 Web Query. In all cases, the SQL statements are run, and the temporary result set becomes the input to a query. You can then modify the output with Report Assistant or Graph Assistant. This technique is similar to importing Query/400 definitions.

After a report is tailored with one of the GUI tools, it looks like a standard report to the user. When the user chooses to run the report, the SQL statement or SQL stored procedure is executed on the System i environment, and the result set is passed to the reporting procedure for formatting and further modifications. The output is then presented to the user.

Before we start using the SQL Wizard, we need SQL to import into DB2 Web Query:

1. Create a file on your PC hard drive called SQLStmt.sql. This file should contain the following statement:

SELECT INVENTORY."ProductType", INVENTORY."ProductCategory", SUM(ORDERS."LineTotal") AS Revenue, SUM(ORDERS."CostOfGoodsSold") AS COGS FROM QWQCENT/ORDERS AS ORDERS, QWQCENT/INVENTORY AS INVENTORY WHERE INVENTORY."ProductNumber" = ORDERS."ProductNumber"GROUP BY INVENTORY."ProductType", INVENTORY."ProductCategory" ORDER BY INVENTORY."ProductType" ASC, INVENTORY."ProductCategory" ASC


Running SQL statements from a file requires the file to be in the DB2 Web Query directories in the integrated file system. Although there are many ways to copy your SQL statement there, we use the functionality in Developer Workbench.

2. Make sure that your Windows Desktop is displayed in your Developer Workbench explorer tree. If it is not displayed, see the Explorer options in 9.2, “Setting Developer Workbench default options” on page 258.

3. Open your explorer tree and expand down to Common Domain → Other Files.

4. Navigating in your Windows Desktop tree, highlight SQLStmt.sql and drag it from your PC to Other Files in Common Domain (Figure 12-34).

Figure 12-34 Moving PC files to DB2 Web Query directories


5. Now that we have the SQL that we want to run in the System i environment, start the DB2 Web Query SQL Wizard. Right-click your Tutorials folder and select New Procedure (Figure 12-35).

Figure 12-35 Starting the SQL Wizard

6. In the Create window (Figure 12-36), for File name, create a file called SQL1. For Create with, select SQL Report Wizard. Then click Create.

Figure 12-36 Initiating the SQL Report Wizard

Tip: You can go directly to the prompt in the window shown in Figure 12-36 by using the Quicklinks option of SQL-based reports and graphs.


7. In the Welcome to WebFOCUS SQL Report wizard window (Figure 12-37), you are presented with three options:

– Include an external .sql file.

The .sql file must be located in the DB2 Web Query directories in the integrated file system. The SQL statements in the file should generate a single result set.

– Type SQL commands directly.

This option allows you to directly enter an SQL command that will create a result set that can be used by DB2 Web Query.

– Import an existing .sql file and modify.

This is the same as the first option except that you are presented with an additional display where you can edit the SQL statements in the file.

All options generate an internal, temporary file to hold the results of the SQL execution called SQLOUT.

Select Included from an external '.sql' file.

Figure 12-37 SQL Report wizard

Tip: SQL stored procedures are not included in the SQL wizard because importing SQL stored procedures is part of the base product. You can do this through the Create Synonym functionality in either the base product or optionally through Developer Workbench.


8. In the next window (Figure 12-38), accept the default options for accessing the database. Click Create.

Figure 12-38 Accessing DB2 for System i data

9. As shown in Figure 12-39, for the external SQL file name, click Browse. In the Open window, navigate to Common Domain → Other Files. Select the .sql file SQLStmt and click Open. Then click Next.

Figure 12-39 Browsing for your .sql file

Tip: Prior to continuing, you have the option to test the SQL statement against a limited number of records. The output is sent, in default HTML format, to your display.


10.In the Summary window (Figure 12-40), review your options. Then either select Report Assistant or Graph Assistant. Instead of selecting a table that you want to query, you are presented with the output from the SQL. Click Finish.

Figure 12-40 SQL Wizard option summary

11.In the window shown in Figure 12-41, notice that the input fields to Report Assistant are the output fields from your SQL execution. You can now choose to format the fields, create additional calculated fields (such as PROFIT = REVENUE - COGS), apply style sheets, and do anything else that you normally do to query a table in Report Assistant.

Make some formatting changes, add a heading, and run your report.

Figure 12-41 Report Assistant with SQL output

12.3 Summary

Between Chapter 9, “Developer Workbench” on page 253; Chapter 10, “Online analytical processing” on page 261; Chapter 11, “HTML Composer” on page 295; and this chapter, you have been introduced to many of the features of Developer Workbench. Developer Workbench is a complete GUI development environment. We highly recommended Developer Workbench to DB2 Web Query developers.


You have now completed all the tutorials for DB2 Web Query. Now it is time for you to start using this query and reporting tool against your own data. We introduced you to the more common features within this product. There are many additional features that we have not touched upon. Feel free to experiment and remember that you can always turn to the help text if you need assistance. The help text accessed in Developer Workbench is much more detailed and complete than the basic help text that is available for the other Web components.



Chapter 13. DB2 Web Query Spreadsheet Client

In this chapter, we cover the DB2 Web Query Spreadsheet Client. While Web Query has always had tight integration for Microsoft Excel, with items like drill downs, conditional styling and formatting, and formula support, it has required that the user first go into the Web interface. From here, they could run their reports and open up the output in Excel. However, many analysts have requested the ability to simply pull in the data from within Excel. Using the DB2 Web Query Spreadsheet Client, clients can now do just that. In this chapter we cover the installation and usage modes available inside the Spreadsheet Client. We also look at how we can use these features to build a powerful dashboard inside Excel.

13


13.1 Overview

DB2 Web Query has always had the ability to push data out to Microsoft Excel. However, by using the Spreadsheet Client, users can now pull data from Web Query directly from within Excel. This allows them to avoid the trip out to the Web browser to request the report and have it directed to Excel output. Instead, the user simply launches Excel and requests the data from there.

13.2 Installation

First make sure that you have the latest copy of the Web Query media. If you are unsure, you can download the image from the IBM ESS Web site. Do a RSTLICPGM LICPGM(5733QU2) DEV(OPT01) OPTION(5), where OPT01 is the name of your optical drive. Install the latest PTFs for Web Query listed in the Info APAR. Finally, do not forget to add your license key for this option.

After installing the new feature, an Excel add-in is made available to clients in the IFS, in the same manner in which the Developer Workbench is provided. Users simply copy the wqsclient.xla and wqsclient.cfg files from /QIBM/ProdData/WebQuery/ibi/webfocus76/utilities to the Microsoft Office Add-in directory on their PC. For Windows XP that is C:\Documents and Settings\userid\Application Data\Microsoft\AddIns\ and for Windows Vista that is C:\Users\userid\AppData\Roaming\Microsoft\AddIns\, where userid is the user name with which they logged into the PC.

Once the XLA file is in the correct directory, launch Excel and go to the Add-ins Manager. In versions below 2007, this is off of the Tools → Add-ins menu. In Excel 2007, click Office → Excel Options → Add-ins. Make sure that the Web Query Spreadsheet Client option is checked. Now the setup is complete and we will move on to usage.

Predefined Server configurationsOne of the files listed above that users will move to their PC is the wqsclient.cfg file. This is a configuration file that allows the administrators to pre-define connections to their IBM i servers. Users always have the option of entering their own server connection definition. However, this provides a way for the administrators to set up all the existing connections in advance. This can be a great way to save on support calls from users typing in the wrong information.


This is a very simple text file that contains internal comments that explain how to work with the file. The main items that administrators will want to add are server blocks at the end of the file. Let us assume, for example, that our server is myi.mycompany.com. Just add a block to the end of the file, as shown in Example 13-1.

Example 13-1 Server blocks example

# Web Query server: SERVER_START PROTOCOL = "http" HOST = "myi.mycompany.com" PORT = "11331" HTML_ALIAS = "/webquery_html" CLIENT_PATH = "/webquery/WFServlet"SERVER_END

The only line that was changed was the HOST line. Everything else (protocol, port, alias, and path) is always the value that is entered. The line that starts with a pound sign (#) is just a comment. Simply add one of these blocks for each connection that you want. Besides DNS names, you can also enter IP addresses, as shown in Example 13-2.

Example 13-2 IP addresses example

# Web Query server: SERVER_START PROTOCOL = "http" HOST = "192.168.2.1" PORT = "11331" HTML_ALIAS = "/webquery_html" CLIENT_PATH = "/webquery/WFServlet"SERVER_END

13.3 Usage

To pull data into Excel, simply right-click the first cell that you want to import data into or select the cell and use the Web Query menu or ribbon item. Select Create Query. The first dialog box asks for your server's name. The next dialog asks you to sign in with your user ID and password. At this point we see one of two options, depending on your user licensing.

13.3.1 Report Assistant mode

To use the Spreadsheet Client, we have two modes. The first mode is called Report Assistant mode. In this mode, you will see a dialog box that provides almost all the same functionality that you see in the Report Assistant inside the Web version of Web Query. The only items not shown are those such as headers or footers that you can add directly in Excel. The purpose of the add-in is to simply pull the data set into Excel. This allows you to define your report on the fly. Because you have these designer/developer capabilities, users of this mode must be explicitly licensed.

Chapter 13. DB2 Web Query Spreadsheet Client 389

If you go the Report Assistant route, you will be presented with the Report Assistant form, as shown in Figure 13-1. From there you can select the measures that you want reported on as well as the grouping and ordering. The selection criteria are also set at this point. However, the selection criterion must be static at this time. This means that you cannot set a parameter that can be selected at runtime.

Figure 13-1 Report Assistant Mode

13.3.2 Structured Ad-hoc Form mode

The second mode of usage is known as Structured Ad-hoc Forms (SAF). SAF mode is similar to an HTML launch page. There the developer pre-creates an HTML form that provides the various drop-down menus and options to select. The user is not actually creating a new report. He is just running a report that already was created by a developer. Because of this limitation, to use SAF the user may have an explicit license or may be a member of a Run Time Enabled group using 5733QU2 Option 4.

If your profile does not have an explicit license, you will not be given this choice, as you can only use the SAF mode. However, if you do have a license allocated to your profile, you have the choice of which mode to use, Report Assistant or SAF.

In the SAF route, the developer builds an HTML Form and attaches that to an existing report. When you select this method, you will then be prompted with a list of available forms. Select the form and fill in the selection criteria. This allows the user to determine what values will be used for the selection portion of the report. However, no other attributes of the report can be changed at this level. In addition, once the parameters are set and the report run, refreshing


the report will use the same values set. You will not be re-prompted to allow for the values to be changed.

DB2 Web Query will populate the list of available SAFs by looking at a particular folder in a domain. This can be any folder that you want. We recommend that you create a folder that contains nothing but the SAF Forms. Place all of the HTML Layout files in this folder. Then use the WF Console (http://yoursystem:11331/webquery_html/wfconsole.htm), logged in as QWEBQRYADM, to select the domain and folder that contains the forms. You cannot set more than one folder, so you must place all forms to be used via the SAF mode into this one designated folder. For complete details, see the manual referenced at the end of this chapter.

13.4 Dashboards in Excel

With the Web Query Add-in, you can only pull data over, not graphs. This is because Excel has always had excellent graphing capabilities. And with Excel 2007, Microsoft has made it even easier via the ribbon interface. So when we think about creating composite dashboards, we should think about first pulling in one or more data regions and then creating graphics in Excel based on that pulled data, as shown in Figure 13-2. This way you simply update the data in the sheet and Excel will update the images.

Figure 13-2 Sample Excel Dashboard

Once the data is returned into Excel, the user can do what she wants with it. In order to make integration into Excel templates easier, we automatically name the data ranges. This allows for access to various regions of the report without knowing the exact size. So if your data set


contains five rows or 500 rows in the Sales column, you can refer to them all simply as QDATA1__Sales.

There are several new features in Excel 2007 that make it more powerful than ever for data analysis. Check out features such as themes for building dashboards with consistent formatting. Look to the data bar feature of conditional styling to quickly pull out visual values for numbers. And of course, do not forget the increased limits on rows and columns (from 65,536 rows by 256 columns (16,777,216 cells) to 1,048,576 rows and 16,384 columns (17,179,869,184 cells)).

13.5 Data range properties

Once we have the data in Excel, there are several options that we can set. We access these options via right-clicking in the report data and selecting Data Range Properties. See Figure 13-3. Here we can set features such as refreshing the data when the worksheet is opened and automatic background refresh. This ability to do automatic refresh is a key feature if we want to use this as a dashboard.

If we are using a template, we want to check the option to preserve cell formatting. This way, when data is added or updated, it takes on the formatting in the template and does not reset to the default format.

Figure 13-3 Data Range Properties


13.6 Spreadsheet Client Manual

For complete details about using the Web Query Spreadsheet Client download a copy of the Spreadsheet Client manual from the Web Query Space located at:

http://www.ibm.com/developerworks/spaces/DB2WebQuery




Chapter 14. Adapter for Microsoft SQL Server

The DB2 Web Query Adapter for Microsoft SQL Server extends your reporting environment by incorporating access to data stored in one or more Microsoft SQL Server databases. Current versions supported are 2000 and 2005.

Although the majority of your data is likely in DB2 on i, access to data stored in Microsoft SQL Server databases may also be key to creating desired reports. By installing option 6 as part of your DB2 Web Query installation, you can seamlessly incorporate SQL Server data in your reports in real time without the need of a complex replication process. The Microsoft SQL Server adapter allows your organization to use a single query and report writing tool, DB2 Web Query, to access all of the necessary data for your reports.

In earlier chapters you learned how you can extend the value of the information stored in DB2 for i by doing online analytical processing, active reports, dashboards, and automatic report distribution. With this adapter, you can do the same with information stored in your Microsoft SQL Server databases.

This chapter will take you through the steps necessary to establish a connection to your SQL Servers. But, before we get started, you must install the option.

14


14.1 Installation

To begin, you must install the product option 5106 from media. Also make sure that you have the latest PTF group installed for DB2 Web Query. This option has a 70-day trial period. If you are installing before purchasing, please proceed. If you have already purchased this option, use the ADDLICKEY command to add the key to your system.

Due to Microsoft's licensing agreements, we are unable to ship required code as part of the Web Query package. Therefore, to complete the installation you must install a version of Microsoft's JDBC driver for SQL Server on your system.

To determine which version to download, we briefly discuss versions. Microsoft currently offers three levels of its JDBC driver. Version 1.1 is designed for SQL Server 2000, Version 1.2 for SQL Server 2005, and Version 2.0 for SQL Server 2008. At the time of writing, Web Query only supports the 1.1 and 1.2 versions of the JDBC driver. Microsoft only finalized the 2.0 version before the General Availability date for this option. Because of this, we are still working on adding official support for Version 2.0 of the driver.

When configuring Web Query, we can only configure it for one level of driver, either 1.1 or 1.2. If you have only SQL Server 2000 servers, we recommend using Version 1.1. If you have only SQL Server 2005 servers, you must use Version 1.2. Luckily, Version 1.2 is also backwards compatible to SQL Server 2000 and forward compatible to SQL Server 2008. Therefore, if you are in doubt as to which version of driver to choose, we recommend the 1.2 version, as that will work with all levels of SQL Server.

As we are discussing configuration settings, it is important to note that the settings are tied to the driver level and not the level of SQL Server. Let us assume that you are using the 1.2 version to connect to both SQL Server 2000 and 2005 servers. Even when you are defining the connection to the SQL Server 2000 server, you follow the settings for the 2005 server since those correspond to the 1.2 version of the driver that you are using.

So now that you know which version of the driver you want to download, use your favorite search engine or Microsoft.com to find links to the 1.1 or 1.2 version of the JDBC driver. Searching for “Microsoft SQL Server JDBC Driver" usually returns the correct page at the top of the results. If prompted, download the UNIX® version of the driver, not the Windows version. This will download a tar/gz package containing the required Java Archives (JAR) files. Use your favorite decompression utility, such as the open source 7-Zip, to extract the required files. For Version 1.1 of the driver the files are msbase.jar, mssqlserver.jar, and msutil.jar. For Version 1.2 of the driver, it is just one: sqljdbc.jar.

Once you have the JAR files, FTP them in binary mode or use a mapped drive to put them onto the system. The JAR files must be placed into the Java Extensions directory located at /QIBM/UserData/Java400/ext. By placing them in this directory we do not have to worry about setting the proper classpath. This directory is always included.

14.2 Establishing a connection to your MS SQL Server

To configure the adapter within DB2 Web Query, you must provide both connection and authentication information. To configure the adapter from DB2 Web Query, follow these steps:

1. Log on to Web Query as a developer or an administrator.

2. Expand the Domains folder and then select and expand a domain.


3. Expand the Reports folder in the domain, right-click a folder, and choose Metadata from the menu.

4. You will see an Adapters folder, as seen in Figure 14-1. Right-click Adapters and select Add or click the New Adapter menu item.

Figure 14-1 Adding a SQL Server Adapter

5. Under Add Adapter Configuration in the Select Adapter to Add frame, expand SQL and then the MS SQL Server option. You will see two possible MS SQL Server versions (2000 for Version 1.1 of the driver or 2005 for Version 1.2 of the driver) represented. Again, choose the version that matches the level of driver that you installed, which may not be the same as the level of SQL Server to which you are connecting.

Chapter 14. Adapter for Microsoft SQL Server 397

6. Click the appropriate 2005 or 2000 version for your installation. This opens the Configuration pane, as seen in Figure 14-2.

Figure 14-2 Configuring connection to SQL Server

7. In the configuration panel, name your adapter as desired. In this example the connection name is called SQLTEST. This can be any name that you want.

8. Enter the URL location for your SQL Server data source. This consists of the driver prefix, the separator (://), followed by the host name (location) of the SQL Server, the separator (:), and the port, in the format as follows:

prefix://hostname:port

If you are using the 1.1 version of the driver (2000), the prefix is jdbc:microsoft:sqlserver. If you are using the 1.2 version (2005), the prefix is jdbc:sqlserver. The host name for your system can be either the DNS name (sqlserver.mycompany.com) or dotted IP address (1.2.3.4). If you use a DNS name, make sure that IBM i can resolve it by doing a simple PING from the command line to the SQL Server's DNS name.

The final piece of this URL is the port number. The default port for the SQL Server is 1433. However, not all SQL Servers run on that port. To find your SQL Server's port number, do the following. First open up the Windows Task Manger. Add the PID (Process ID) column by clicking View → Select Columns → Check the PID option → OK. Find the image name sqlservr.exe and record its PID. Then open a command prompt and run netstat -a -n -o and look for the matching PID number. Under the Local Address column will be 0.0.0.0:xyz. The value xyz after the colon is the port number.

Assume that the DNS name of our SQL server is sqltest.rchland.ibm.com, the port is 1547, and the version of the driver is 1.2. The URL would then be:

jdbc:sqlserver://sqltest.rchland.ibm.com:1547


If the above were the same but using the 1.1 version of the driver, the URL would then be:

jdbc:microsoft:sqlserver://sqltest.rchland.ibm.com:1547

9. Select for Security the option Explicit and provide a SQL Server user and password necessary for authentication. All connections to the SQL Server will use this profile. Therefore, it is important that this profile is granted access to all tables to be accessed in the SQL Server. In this example, a user of sqlserver and corresponding password was provided. This will be unique to your location.

10.The final step is to enter the driver name. This too is varied with the version of the driver. If you are using the 1.1 driver, enter com.microsoft.jdbc.sqlserver.SQLServerDriver for the driver name. If you are using version 1.2 of the driver, enter com.microsoft.sqlserver.jdbc.SQLServerDriver for the driver name.

11.Do not be concerned that the CLASSPATH is NOT SET, provided that you posted the JDBC driver JAR file in the above directory location. Web Query will find the necessary driver.

12.Click Configure once the appropriate information is provided. Note that at the time of writing, Test was not functional.

13.Once you have configured the new adapter you should restart the DB2 Web Query servers before moving on to create metadata. Use the ENDWEBQRY and STRWEBQRY commands.

14.3 Creating Metadata

Just as in Chapter 3, “DB2 Web Query fundamentals” on page 25, once you have established a connection to a data source, you can create various synonyms over the data (tables, views, stored procedures) at that data source that you want to query.

1. Again, right-click a DB2 Web Query reports folder in the desired domain and select Metadata.

2. In the Adapter pane you should now see your MS SQL Server as a data source. Right-click the newly created connection and select Create Synonym, as shown in Figure 14-3.

Figure 14-3 Adapter panel


3. Defining this synonym is a two-step process. You will first see a panel similar to Figure 14-4.

First identify the target database on the SQL Server. Remember, SQL Server is different from IBM i in that is has a concept of multiple databases. Within each of those databases are the schemas that contain the tables. In this example, we have downloaded the Microsoft's AdventureWorks sample database so that it appears in the Select database list. In this example only table objects are requested from the selected database.

Click Next to advance to the second step.

Figure 14-4 Identify the target database

4. In the second step, select the tables that you are interested in querying.

In this example, the selection is key employee and department tables and specifying the With foreign keys option.


Provide the prefix or suffix if desired and click Create Synonym once you have selected the tables of interest. As a best practice, we recommend using the schema name followed by an underscore as the prefix and a suffix such as _mssql. This way, your Employee table appears as HumanResources_Employee_mssql. This groups all items from the HumanResources schema together and provides you with a reminder that this data source is from a SQL Server, as shown in Figure 14-5.

Figure 14-5 Selected tables of interest from the AdventureWorks sample database

5. You will see a summary completion panel similar to Figure 14-6. Close that window.

Figure 14-6 Create synonym completion message

6. You now have a synonym that is specific to tables located in a database on a MS SQL Sever. You can now use this new synonym to build reports using Report Assist, Graph


Assist, Power Painter, or Developer Workbench, exactly the same way that you do with local data synonyms.

14.4 Additional SQL Server Adapter information

For additional information about the DB2 Web Query SQL Server adapter, a documentation PDF file is located under the documents link on the DB2 Web Query Getting Started page located at:

http://www.ibm.com/systems/i/software/db2/webquery/gettingstarted.html

Some of the information available in this document is:

� How to customize your SQL Server environment� How to call SQL Server stored procedures� Information about SQL Server data types


http://www.ibm.com/systems/i/software/db2/webquery/gettingstarted.html

Part 4 Companion products

In this part we explain more specific topics about DB2 Web Query. This part includes two of the companion products of DB2 Web Query:

� Chapter 15, “Report Broker” on page 405� Chapter 16, “Software Development Kit” on page 431

Part 4



Chapter 15. Report Broker

DB2 Web Query Report Broker is a separate licensed program product (5733QU3) that builds on the strengths of the Web-based query and reporting tool, DB2 Web Query. With Report Broker you can automate the process of running your reports and schedule them for distribution to individuals, distribution lists, printer destinations, or for storage in a Web Query folder for shared online viewing or archival purposes.

Although Report Broker is a separate licensed product, once installed, it is tightly integrated with DB2 Web Query. The scheduling function and the ability to view and change existing schedules, create and view distribution lists, view Distribution Server log entries, establish schedule blackout dates, and other Report Broker services are all presented to a Report Broker scheduler or administrator by logging in to DB2 Web Query.

To be a Report Broker scheduler or administrator you need the corresponding MRSCHEDULE or MRADMIN as a group profile in your user profile. Also, a scheduler (MRSCHEDULE authority) must have developer access to one or more report domains.

This tight integration extends to the maintenance of Report Broker services as well. Regularly applying DB2 Web Query maintenance fix packs will also keep you up to date with any existing Report Broker fixes or new functions.

Report Broker services are included in the DB2 Web Query online help. Report Broker help text is context sensitive and will position you to the appropriate help for the corresponding screen or topic. Look for icons with a question mark. Report Broker help text is available in the same language translations as DB2 Web Query.

A final point of integration between Report Broker and DB2 Web Query is the starting and ending of the Report Broker Distribution Server. All three CL commands used to start or end of Web Query services (Start Web Query (STRWEBQRY), End Web Query (ENDWEBQRY), and Work Web Query (WRKWEBQRY)) include the Report Broker Distribution Server as part of the command default '*ALL'.

To see how the Report Broker Distribution Server fits into the DB2 Web Query architecture, see Figure 1-1 on page 11 in the architecture overview in Chapter 1, “Product architecture and overview” on page 3.

15


In this tutorial we go in to detail about how to schedule a report for distribution, view the various frequency options when scheduling a report, show how to get failure notifications, create a distribution list, enable a report for a capability known as intelligent bursting, and view the log entries for a scheduled distribution. In addition, we cover Report Broker capabilities specific to the MRADMIN authority level. We show how to set schedule blackout dates, do a global update, and import a distribution list from another Broker server.


15.1 Tutorial overview and preparation

To facilitate this tutorial we reference a predefined report already created in the Report Assistant section, call RA4_Advanced. As you click that report to run it, if it contains a prompt for input of product type, open the report for edit, click Selection criteria, and remove the input option at this time. If you output the product type in the Report Headings, you should remove that value as well.

If you have an existing report of your own that follows the report criteria similar to that of the one being scheduled in this tutorial, the same steps can apply to that report.

That said, if you have an existing report of your own that follows the report criteria of the one being scheduled in this tutorial, the same steps can apply to that report.

15.2 Installing and Configuring Report Broker

In order to use Report Broker, it must first be installed and configured for use. To install Report Broker, you must already have installed DB2 Web Query V1R1M1, the base option, and you should be up to date with DB2 Web Query maintenance fix packs.

1. End the existing Web Query services (ENDWEBQRY).

2. Sign on as QSECOFR or a user profile with *SECADM or *ALLOBJ authority.

3. Issue RSTLICPGM, specifying your optical device. Note that Report Broker only has a base option.

RSTLICPGM LICPGM(5733QU3) DEV(opt01)

4. Read the license agreement and press F14 to accept it.

5. If you have a license key for 5733QU3, issue the ADDLICKEY CL command to apply the key. You are allowed a 70-day grace period to try out the product.

After installing Report Broker, you must configure the product for use. You only must do this once per installation. Report Broker uses underlying DB2 tables to store schedule requests and other information, such as distribution lists. The Distribution Server queries these tables using the DB2 Web Query administration profile shipped with the product, QWEBQRYADM.

Note: The most up-to-date information about installing and configuring Report Broker can be found on the DB2 Web Query Getting Started Web page.

Chapter 15. Report Broker 407

To do this configuration you must sign in to the DB2 Web Query Administration console as QWEBQRYADM. The Web Query servers must be started to do this. Only by logging in as QWEBQRYADM will you be able to see the Report Broker configuration options in the side panel, as illustrated in Figure 15-1. The URL again for the console is:

http://<yoursysname>:11331/webquery_html/wfconsole.htm

Figure 15-1 Report Broker configuration

1. The first step is to establish the connection settings needed by the Report Broker repository. Click Connection and provide the QWEBQRYADM profile and password, then click Save at the bottom of the screen. To test that the connection profile and password are correct, click Test Repository in the side panel. You will receive a pass or fail indication. You may need to click Test Repository a couple of times before getting a pass indication. If you persist in getting a fail, it could be that the password in not correct.

2. The next step is to create the underlying DB2 tables used by Broker. Click the option Create All Tables. You will receive a message when the tables are successfully created.

Tip: Because the Report Broker Distribution Server will regularly connect to the local database to poll for schedule requests using the QWEBQRYADM profile and password, if that password is changed due to password policies at your location, you must immediately update the Report Broker configuration with the new password. Failure to do so will quickly render the QWEBQRYADM profile disabled and that will prevent both Report Broker schedule requests and DB2 Web Query user logins from being successful.


The final step is to set the necessary Report Broker configuration settings. See Figure 15-2. It is on this screen that you determine key aspects of how the Distribution Server will run on your IBM i. For example, the name of your e-mail server, how often you want the Distribution Server to wake up and look for scheduled requests, how far back you want the Distribution Server to recover missed reports should the server be down, what name and e-mail reply address you want to default on the delivered reports, and a handful of other settings.

3. Click Configuration. We recommend that you minimally set the Default Mail From value, the Default Mail Reply Address value, and, most importantly, your e-mail host server name in the Mail Host value. The Notify Mail Host will be equivalent to the Mail Host value unless you designated a different server. You have the ability to request e-mail notification for reports that fail to distribute. Click Save.

Figure 15-2 Configuring Report Broker

The Distribution Server also keeps a detailed log of all distribution activity, what reports were generated and distributed, when and who received the reports, and any problems encountered during distribution. The log purge period is the number of days that the log entry is retained. The log purge time is the time of day when Report Broker purges expired log entries. By default the configuration setting allows 30 days for log retention.


You also have the ability to automatically recover missed report distributions should the Report Broker Distribution Server be down. To determine the appropriate configuration setting options for your environment, click Help to get additional information about the settings provided. See Figure 15-3.

Figure 15-3 Help for additional information


15.3 Schedule an existing report

To schedule a report, you must first identify the report to be scheduled. In this example we select the report by expanding Common Domain, then Reports, then the Tutorials folder, and finding the report called RA4_Advanced.

1. Right-click RA4_Advanced and choose Schedule, as shown in Figure 15-4.

Figure 15-4 Report Broker Schedule


Clicking Schedule presents the Report Broker Schedule panel, as illustrated in Figure 15-5.

Note that along the top you have a menu bar with several options. You can save the schedule, run the schedule, view schedule log entries, or request help or the panel. If you exit the panel without doing a save, you will be asked if you are sure.

Figure 15-5 Report Broker Schedule options

The description supplied at the top of the Schedule panel is primed with the name of the report selected and the current date and time. This description becomes the name by which this schedule request will be known on the Report Broker tab for any future actions on this request. You can change this description to reflect key aspects of the report. For example, if this is the monthly gross profit report by product type sent to upper management, you could designate that in the description by providing Monthly Management Gross Profit Product Report.

The schedule panel consists of five key sections:

� Distribution� Frequency � Report Options� Notification � Advanced

Note that all required fields in all of these sections are designated by an asterisk (*).


The Distribution section indicates how and where the report will be distributed. You have the choice of Email, Printer, or a Web Query distribution. These are reflected in the Distribute report by option. The Web Query option allows you to schedule and store the resulting report in a Web Query folder. The folder name is supplied by the schedule request and will become part of the same report domain as the original scheduled report. Using the Web Query distribution option, generated reports can be viewed by multiple Web Query users without each rerunning the report. The Web Query option is also a good way to generate an archive of reports.

In this example, however, we distribute a report by e-mail.

1. Under Distribute report by, select the Email option.

2. On the Distribution list pull-down menu, select Single Address and supply your own e-mail address in the required field location designated by an asterisk.

3. The From and Reply Address fields of the report are primed with the values supplied when you configured the Report Broker server (Figure 15-2 on page 409). You can override those values if you wish.

4. The Subject field of this report distribution is primed with the name of the selected report being scheduled and the current date and time. It is unlikely that you would want the subject of repeatedly distributed reports to reflect the initial create time of the schedule request, so clear that portion of the subject line or clear the entire subject and provide a more meaningful subject, such as My first Report Broker schedule request.

5. By default, the report is sent as an attachment.

6. You have the option to add reports to the zip file by clicking Add Reports to Zip File. As this report is small, we leave that box unchecked.

The Frequency section determines when and how often the report is distributed. By default the run interval is Once on a create and it is primed with the current date and time. For now, we leave that frequency setting as Once. We recommend that newly schedule reports be set to run once and to a test distribution e-mail address (such yours) to make sure that the subject and additional report options are at desired settings before scheduling a report to deliver to multiple people.

Tip: If you receive a pop-up message of MSGV0004 on the Save or Run of a scheduled distribution by Email it means your the mail host server was not properly configured. See Figure 15-2.


Under the Report options section designate how you want the report to be distributed. We discuss the Burst this Report option in another example, but another important option here is the Send the Report in this Format designation. Based on the type of report being distributed, a Report or Graph, different format options will present themselves. As the RA4_Advanced report was created with Report Assist, you see the allowable options for distributing a text-based report. Even though RA4_Advanced was defined as an HTML report in Report Assist, we choose to distribute the report as an Excel spreadsheet, as shown in Figure 15-6.

Figure 15-6 Report as Excel spreadsheet

7. From the pull-down menu select EXL2K FORMULA - Microsoft Excel 2000 Formula.

8. Because this report is scheduled to be delivered as an attachment, an attachment name is predetermined. You can choose a different name if a more meaningful one would be helpful for you target audience.

9. Expand the Notification and Advanced sections of the schedule panel. Click the Notification will be sent out and the Type drop-down menus to view the options available. For this example, we leave these two sections at the default values of no notification, default priority, and enabled.

The Notification section allows you to specify if and when you want failure notification and who should receive that notification. You can Always get a notification, Never get a notification, or get one only On Error. If you designate notification, you will be required to provide a To and From e-mail address, Full Notification and Reply Address. Note that the

Tip: If you have trouble with your distributed report not opening or displaying correctly, verify that this format option is compatible with the initially created report, particularly for Graph reports or reports targeting printers.

Note: Although this report being scheduled does not have any input parameters, the Report Options section allows you to check and select parameter values required as input parameters when a report is defined with inputs. In fact, if the input parameters were defined in the report as prompted, those same prompted values will be displayed here for your selection. The name of the parameter fields and values when provided would be stored with the report. By scheduling a parameterized report multiple times with different input values, designating different target distribution lists and in a preferred format and on a scheduled basis that works best for that target audience, you further extend the value of your highly parameterized reports.


Subject is populated with the subject of the original report. You should change the subject to indicate the appropriate notification state.

The Advanced section allows you to temporarily disable a schedule report or change the priority of a schedule. A schedule's priority determines which report is served first when multiple reports are scheduled at the same time. The Delete this schedule option gives you the capability to schedule a report designed to run once, at some future date and time, and then is deleted. Refer to Figure 15-7.

Figure 15-7 Notification options

Now we have defined our report to run once and distribute to a single e-mail address, which is your own.

10.Click Save at the top of the schedule panel. This both saves your report for future use and runs your report once. You will see confirmation of your create, as shown in Figure 15-8.

Figure 15-8 Confirmation message

After a minute or two, check your e-mail. The RA4_Advanced report should be in your e-mail. Open the e-mail and you will see a spreadsheet attachment that reflects the Gross Profit by Product Type report.


15.4 Scheduling Frequency options

We now find the report that we just scheduled and experiment with the different Frequency options available in Broker.

11.To find the schedule request just created, click the Report Broker tab, as illustrated in Figure 15-9.

Figure 15-9 Schedule requests

Notice that there are two menu bars in Figure 15-9. The top menu bar lists various options in Report Broker such as work with Schedules, work with Distribution lists, check current running Status, do Global Updates, perform some Change Mgmt, and work with Blackout Dates. By default, working with Schedules is the active option and you see the existing schedules.

The second menu bar relates to existing schedules. From this menu bar you can open a schedule, view a schedule's log, delete a schedule, purge log entries, clone (copy) a schedule, run a schedule, or view the schedule list by applying a filter option.

By default you see all the scheduled requests that you create as a profile with MRSCHEDULE authority. Note that if you have MRADMIN authority, you have the ability to see ALL schedule requests by clicking the Filter option.

12.Open the scheduled request by double-clicking the selected schedule. Again you will again see the Schedule panel.

Now let us play with the various frequency options available to you.

13.View the various schedule options under the Run Interval tab and select Weeks, as shown in Figure 15-10.

Figure 15-10 Frequency: Run Interval


14.To schedule a report to run every day of a normal work week, Monday through Friday, at 6 a.m., select the settings as seen in Figure 15-11.

Figure 15-11 Frequency: Run Interval

15.Change the Run Interval to Months.

16.To designate that a report runs on the 1st and 15th of each month, select both dates in the setting, as seen in Figure 15-12.

Figure 15-12 Selecting dates

Another option on this screen is to designate that a report run on The (radio button) first Monday of the month or the third Thursday. To schedule the same report to run on both a first Monday and a third Thursday, two separate schedule requests would be necessary. To facilitate copying the same schedule request for slight alterations, use the Clone option mentioned above under the main Report Broker Schedules menu. Note that cloned schedules are automatically marked disabled until you enable them under the Advanced settings section.


In addition to a primary schedule, you have the ability to schedule a secondary run interval.

17.Click the Apply secondary run interval check box, illustrated in Figure 15-13. You can apply a secondary run interval every n minutes or hours after the initial run interval is triggered. The secondary run interval is available for schedules that run daily, weekly, per month, quarter, or year.

Figure 15-13 Applying a secondary run interval

18.In order to make a schedule change permanent, you must save the schedule request. Change the report back to Run Interval - Once

19.Click Save.

15.5 Creating a Report Broker distribution list

As noted in the Schedule report example defined earlier, when distributing a report you can send the report to individual e-mail addresses or to a predetermined distribution list defined within Report Broker.

Creating a distribution list is particularly helpful when you want to use a function within Report Broker known as intelligent bursting. The process of report bursting is one in which a report is broken into sections and those sections are distributed to particular recipients. Bursting works by segmenting the report based on the first Sort by field of the report. This could be County, Sales Region, Product category, or any one of a number of possible values given by your reports. For reports defined specifically for bursting, this Sort By value could also be hidden from the main report and one that is a composite of a couple of report values when a stand-alone value is not definitive enough.

In this example we create a distribution list to facilitate the bursting of the Gross Profit by Product Type report (RA4_Advanced), so that each separate product type (Audio, Video, and so on) will have that section of the report sent to the person responsible for that product line.

1. From the DB2 Web Query page, click the Report Broker tab.


2. From the Broker menu bar, click the Distribution List option, as noted in Figure 15-14. This list shows you all distribution lists that you created that are private for your use and those that are designated as public.

Figure 15-14 Distribution lists

Under the main options bar, you will notice the options available for working with distribution lists. You can create a distribution list (New), Open for edit or view, or Delete a distribution list.

3. Click New to create a new distribution list.

The Create Distribution List panel looks as shown in Figure 15-15. Distribution lists can be public or private. A private distribution list is only available to the scheduler who creates it. Distribution lists can also be of type Email or Printer. In the case of a Printer list, multiple line protocol printers can be the target for your reports, where the printer name is designated as queue@printserver. Note that Printer distribution lists can also be the target of bursted reports. In this case we create an Email distribution list.

Figure 15-15 Distribution list pane

4. Provide a name for you Distribution list, such as ProductTypeDist.

5. Keep the Access as public and the Distribution method as Email.


6. List the various product types (Audio, Video, and so on) in the Burst Value column and provide corresponding Destination e-mail addresses for that burst value, similar to the example in Figure 15-16.

7. Once you have completed filling in the distribution list, click Save.

Figure 15-16 Saving a distribution list

You can maintain a distribution list, inserting and deleting list entries, by clicking within the list and selecting the Insert or Delete menu option.

15.6 Busting a report

Now that we have a distribution list to facilitate intelligent busting, let us reopen our existing schedule request and designate a bursted report:

1. From the DB2 Web Query page, click the Report Broker tab.

2. By default the existing schedules are presented. Double-click the RA4_Advanced schedule request, bringing up the Schedule panel as filled in previously.

3. Change the Single Address option to Distribution List and select the new ProductTypeDist list.

Tip: Note that the match of the burst values in the distribution list to the corresponding section of the report noted by the first Sort by is case sensitive and an exact match is required.


4. In the Report Options pane click the Burst this Report setting, as shown Figure 15-17.

Figure 15-17 Burst this report option

5. Click Save.

After confirmation of the save, you now have a schedule request saved that bursts a report and targets a distribution list.


6. To run this report, immediately click Run on the Schedules menu bar. You will be prompted to confirm that you want to run the report Off schedule, as shown in Figure 15-18. Click Yes.

Figure 15-18 Running a report Off Schedule

If you are quick enough, you can click the Status option on the main menu bar and see that you are running report. From the status screen you can view currently running distribution requests and you have options such as removing a running report or changing a priority, as shown in Figure 15-19.

Figure 15-19 Status option

Note that a distribution list is not required for selecting intelligent bursting. If a distribution list is not provided with burst values and Burst this Report is checked, the report will still be segmented into the leading Sort by sections and sent as individual attachments to the designated e-mail addresses. Also note that a distribution list with burst values can be used if no bursting is requested on the schedule. Each member of that distribution list would receive the full report.


15.7 Viewing the Distribution log

Each time that the Distribution Server runs and distributes a report, it creates an entry in the distribution log. The retention period for the log is specified in the Report Broker configuration and can be changed. By default, 30 days of distribution activity is maintained in the log.

This log can be viewed for audit purposes or as a source for troubleshooting an initial or changed distribution request that does not appear to be working as desired.

7. To view the distribution log for a particular schedule request, select the desired schedule and then click Log, as shown in Figure 15-20.

8. This brings up a dialog box. Click OK to see the Log entry for the Last Executed. You could also choose a date range or all log entries for this schedule.

Figure 15-20 Log options

Tip: Burst values can be embedded in the subject line of a distribution by using '%burst' in the subject. Similarly, with a parameterized report, the supplied input values can be embedded in the subject line of the distributed report by using '&parmname'. For example, if country was a required input in to the report, '&Country' would provide that country value in the subject line.


Each log entry looks similar to Figure 15-21. The entry designates the report that was distributed, the time, and the target distribution. If problems were encountered generating the report or connecting to the e-mail server or connecting to a remote database, that information will be denoted in red.

Figure 15-21 Job Process Log

15.8 Report Broker and highly parametrized reports

As mentioned earlier in this book, you can add a number of parameters to a report and thereby have one report serve multiple target audiences just by varying the input values. We call this a highly parameterized report.

Figure 15-22 illustrates the defined parameters for an existing Gross Profit report. Given the parameters defined, select the Country, Region, and State via auto-prompting and specify a date range used in the generation of the report. After selecting inputs, click Run.

Figure 15-22 A highly parameterized report’s input prompts

Report Broker also allows you to provide parameter values on a schedule request. In fact, if the report is parameterized you must provide valid parameters within the schedule request so that the report can be generated in the batch distribution environment.

With Report Broker you can schedule that same highly parameterized report multiple times, and just by selecting different input values and designating a different target distribution list you can reuse the same created report to meet the needs of many report consumers. In fact,


your report consumers can get the reports they want, when they want them, just by using Report Broker.

Figure 15-23 illustrates how a report scheduler selects the appropriate report parameters. By clicking each specified input parameter, you will either be provided with an auto-prompt pull-down list for your selection or an input box for providing manual values. If auto-prompting was made possible on the report creation, that same prompting is available during the report scheduling. Note that when you manually enter report parameters, the values provided must be an exact match of the data stored or your report could come up short on data.

In this example, Country, Region, and State are auto-prompted and the From and To date range is manually designated by the scheduler.

Figure 15-23 Report scheduler

15.9 Report Broker Administrator functions

A Report Broker user with MRADMIN authority is able to do three additional Report Broker tasks that a MRSCHEDULE user cannot. An administrator can schedule blackout dates, do global updates, and perform some change management functions.

To set schedule blackout dates:

1. Sign in to DB2 Web Query with an MRADMIN authorized profile.2. Click the Report Broker tab.3. Click the menu bar option Blackout Dates.


From the Schedule Blackout Dates panel, as shown in Figure 15-24, you can navigate to a different calendar year. By default, you are presented with the current calendar year, in this case 2009. To schedule a blackout date click the date, for example, January 1. It will go gray. To make the date a non-blackout date, unselect the date.

Figure 15-24 Blackout dates

4. Click Save when you have determined the desired blackout dates.

MRSCHEDULE authorized Broker users can view the scheduled blackout dates but cannot alter them.

As an administrator, you can perform a limited type of global update. These updates are unqualified, so they are an ALL or nothing determination. So, for example, if Tom is leaving the company and all his existing reports should now go to Sue, you could perform that type of update by doing the following:

5. Click the Report Broker tab.

6. Click the menu bar option Global Update.


7. Provide the Old Value e-mail address and a New Value e-mail address for Tom and Sue. Then click Update. You will be prompted to confirm the update, as shown in Figure 15-25. Click OK.

Figure 15-25 Confirmation window

The global update request will change the appropriate columns in the DB2 repository tables that reflect e-mail addresses and will report back the number of changes performed.

If a printer changes or an existing e-mail server changes, you can update all existing reports to the new value with one global update request.

The final administrator task is one of change management. Say, for example, that instead of creating the distribution list used previously you want to import that distribution list from another Report Broker server. Change management allows you to poll another Report Broker repository, via a DB2 connection, and present the existing public Distribution lists from that other server by the user who creates the lists.


Figure 15-26 shows how you configure the connection to that other server.

Figure 15-26 Connecting to another server

1. Click the menu option Change Mgmt.

2. Provide the necessary connection information by providing the location of the other broker server in the Source URL field and the user ID and password needed to connect to the repository, then click OK.

3. Click the user whose distribution list you want to import and you will be presented with the corresponding distribution lists. Click the desired distribution lists and click Insert, as shown in Figure 15-27.

4. A summary panel reflecting the import will display the results of the transfer request. Click to close that window. You can now use this distribution list on future schedule requests.

Figure 15-27 Importing distribution lists

15.10 Report Broker and Active Reports

In the summary of the chapter on Active Reports, we v discussed how an Active Report could be generated and saved to a local PC and then sent as a file attachment via e-mail to mobile users. With Report Broker, the active report recipient would not need to log in to DB2 Web Query to manually generate and save the report.


Instead, the active report could be scheduled to automatically run at a designated interval convenient for the target audience and automatically be sent as an e-mail attachment in AHTML format via Report Broker. Your mobile users would never need to see a DB2 Web Query screen and would never need to wait for the report to be generated.

15.11 Report Broker and runtime user enablement

As mentioned in the runtime enablement discussion, the number of licenses that your organization needs for DB2 Web Query can depend on many things, such as how many people will be developing reports versus the number of users or distinct report domains necessary for those just viewing reports. One aspect of that decision is also whether your report recipients need live, real-time access to the report data. If most of your users do not need live, real-time access to data, or if control over when queries of the data are run is important, then Report Broker is another option.

15.12 Event-driven distribution request via RUNBRSCHED

One question often asked of Report Broker is whether a schedule request can be triggered by a condition or event. Currently, there is no support in the Broker scheduler to put a condition on a request that could be polled prior to a batch generation and distribution of a report. But, a CL command called RUNBRSCHED gives you the capability to run a schedule request outside of Report Broker.

The inputs to this command are the 12-character, unique Broker Schedule ID, as seen in Figure 15-9 on page 416, and a user ID, which defaults to *CURRENT. You can use this CL command in your application code or database triggers or any scenarios where you can test for or determine a condition where you would like a schedule to be run, for example, triggering a report distribution after some lengthy batch processing has completed.

15.13 Report Broker summary

You have now completed the tutorial of the Report Broker function. Report Broker is a tool that extends the value of DB2 Web Query by allowing you to distribute batch-generated reports to your target audience without requiring the target audience to know about or ever log in to DB2 Web Query. Report Broker features, such as intelligent bursting, flexible output formats, support for parameterized reports, and customized distribution lists, give you the ability to schedule a report for a multitude of users, giving them the information that they need, when they need it, and in a format that compliments the way that they want to work with data.



Chapter 16. Software Development Kit

In this chapter we introduce you to the optional Software Development Kit (SDK) for DB2 Web Query. This feature allows companies to build software products that harness the power of Web Query. We explore the various ways to use the SDK in your shop. Finally, we cover the requirements for use. Note that this feature is only available to customers running Version R111 or later of Web Query.

16


16.1 Overview of the Software Development Kit (SDK)

DB2 Web Query comes complete with a Web-based interface into the product. However, some customers have requested the ability to build the power of Web Query into their own applications. In addition, ISVs have inquired about harnessing the power of Web Query into their applications. To satisfy this need, IBM released the SDK for Web Query, product 5733QU4. This product provides a set of Web services accessible via SOAP, the industry standard for Service Orientated Architecture (SOA). Because of this, the Web can be easily integrated into PC-based as well as Web-based programs.

16.2 Uses of the Web Query SDK

In this section we provide a few of the common uses for the SDK. This is by no means an all-inclusive list. These samples are provided simply to give you some idea of how the SDK could be used in your environment. The possibilities are endless.

With the SDK, you can write your own frontend to Web Query. This allows you to provide an experience that is completely branded as your own. This also allows you to integrate reports and graphs into your existing Web infrastructure. Rather than sending users to log in via http://system:11331/webquery, put the reports directly in your existing intranet site.

If you would rather not use the Web at all, you can quickly build a PC-based application with a language such as VB.net. Here your users are not even aware that they are using a Web application—it simply appears to be a client-server type application.

Web Query requires a user profile to the IBM i system to log in. Do you not want to give all your intranet or extranet users a profile? Build your own page that displays the results using a single embedded user ID and password that the user never sees.

Want to make your existing Web applications more powerful? We have taken the popular open source software program SugarCRM and modified some of the basic opportunity screens. Now, instead of pulling a static list of contacts, we have integrated the power of Web Query. We now provide interactive Active Reports as well as graphs of the various opportunities and potential to close. This small change to the base SugarCRM application has dramatically increased the usability of the data that it stores.

Are you limited to using green screen Telnet connections? Not to worry. The SDK can come in handy here. We have modified an RPG application to call the Web Query SDK. Using the SDK, we pass information from our display file into a query. The output is a PDF file that we write to the IFS and then post the URL on the screen. Using the hotspot capabilities of IBM Personal Communications, the URL is a hot link. This means that from our green screen application we can launch a PDF showing more details for our transaction. See this below in our sample figures.

One final example could be an ISV that builds an application. Rather than building their own reporting and graphing facility, they could build their application on top of Web Query. By the ISV purchasing the SDK, they have the right to develop on top of Web Query and then sell that application. The users purchasing the application would be required to have Web Query installed and licensed, but would not need to purchase the SDK. Only the entity creating the application needs the SDK. An application developed with it will run on any Web Query instance.


16.3 Requirements

To use the SDK for development work, the purchaser would need the base product at level R111 or later. They would also need at least one copy of the Developer Workbench product.

To use an application written in the SDK, the user system would require a system with the base product at level R111 or later. They also need the RunTime User Enablement Feature (5733QU2 Option 4) to allow for unlimited runtime users.

Assuming that the developers of the code would like to test it, developers will also need the RunTime User Enablement feature.

To summarize, to develop using the SDK you need:

� DB2 Web Query R111 or later (5733QU2 *BASE)

� Developer Workbench (5733QU2 option 3)

� RunTime User Enablement (5733QU2 Option 4)

� DB2 Web Query Report Broker (5733QU3) (optional: only needed if the application will invoke the Report Broker Features)

� DB2 Web Query SDK (5733QU4)

To run an application developed with the SDK you need:

� DB2 Web Query R111 or later (5733QU2 *BASE)

� RunTime User Enablement (5733QU2 Option 4)

� DB2 Web Query Report Broker (5733QU3) (optional: only needed if the application will invoke the Report Broker Features)

16.4 Web services

The SDK is implemented via a set of Web services. There are eight core Web services and four additional ones specific to Report Broker. Below you will find a quick overview of each of the APIs. For complete details, see the DB2 Web Query SDK Manual available from the DB2 Web Query home page located at:


16.4.1 Core APIs

The following list are the core APIs:

� WebQueryLogOn provides login and security checking.

� WebQueryRunFex runs a report or graph.

� WebQueryFexReflection provides a list of required parameters for a report.

� WebQueryLink runs linked data returned, such as a graph.

� WebQueryDrill passes a drill-down value into a report.

� WebQueryFieldValues lists possible values for a field and can be useful in conjunction with WebQueryFexReflection for building user interfaces.

� MREGetUserDomains returns a list of domains to which a user is authorized.

� MREOpenDomain opens a domain to get the list of items in it.

Chapter 16. Software Development Kit 433

http://www.ibm.com/systems/i/db2/webquery�

16.4.2 Report Broker APIs

The report Broker APIs are:

� logon logs on to the Report Broker server.� getSchedule returns information about an existing schedule entity.� getScheduleInfoListByCaller returns a list of scheduled entities owned by the ID logged in.� run runs an existing schedule entity.

16.4.3 Sample code path

To provide a quick overview of how your application would use the APIs, here is a quick explanation of the code path that your application would take. First, the user would ask for his user profile and password. WebQueryLogOn would be called to verify this information. Next MREGetUserDomains would get the list of domains for that user and the user would be asked to select one. After the domain is picked, that information would be used for MREOpenDomain to get the list of folders and reports in that domain.

Let us assume that the user wants to run a graph. He would select that item from the MREOpenDomain return. The application would call WebQueryFexReflection to get a list of any parameters required for that graph. Let us assume that one exists. We would then call WebQueryFieldValues to get the list of possible valid values for that parameter and ask the user to pick.

Once we know the graph and have the parameters, we would use WebQueryRunFex to actually create the graph. Since it is a graph coming back, we must use the WebQueryLink function to actually return the image to the user. If it were a report, we could skip this last step, as the report would come back as part of the WebQueryRunFex.


16.4.4 Samples

To help illustrate how the SDK can be used, we include three sample figures below. Figure 16-1 is of a VB.net application that uses most of the functions described above. The user interface shows the various options discussed in the previous section.

Figure 16-1 PC VB.net application sample


Figure 16-2 is of the enhanced SugarCRM screen, as shown in Figure 16-2.

Figure 16-2 Web-based SugarCRM application sample


Finally, Figure 16-3 shows an RPG-based application enhanced to use the SDK. These last two items are some of the possible ideas discussed in 16.2, “Uses of the Web Query SDK” on page 432.

Figure 16-3 RPG based application sample

For a detailed discussion about using the SDK to integrate DB2 Web Query content into a PHP application see the white paper titled DB2 Web Query Integration from PHP - Leveraging DB2 Web Query web services from IBM i applications, which can be downloaded from the following URL:

http://ibm.com/partnerworld/wps/whitepaper/i/php_db2/webquery

This white paper explores the usage of the DB2 Web Query for i Software Development Kit with PHP applications running on IBM i. Included in this paper is a reusable PHP application that may be used as a starting point for PHP application providers to integrate DB2 Web Query Web services into their Web applications.


http://ibm.com/partnerworld/wps/whitepaper/i/php_db2/webquery


Part 5 Miscellaneous and additional topics


� Chapter 17, “Using DB2 Web Query to run existing Query/400 reports” on page 441� Chapter 18, “Performance considerations” on page 449� Chapter 19, “Frequently asked questions” on page 495

Part 5



Chapter 17. Using DB2 Web Query to run existing Query/400 reports

In this chapter, we discuss the similarities and differences between Query/400 and DB2 Web Query. We also discuss common uses for Query/400 and how DB2 Web Query can maintain that same functionality. In addition, we show how to create metadata from your QRYDFN objects so that DB2 Web Query can run your existing queries.

17


17.1 Query/400: a reliable reporting tool

By now you understand that DB2 Web Query is the intended replacement for Query/400. This does not to imply that familiar commands such as WRKQRY and RUNQRY are going away, but rather that the product Query/400 is going away. You can still use older, yet robust, technologies that have stood the test of time and are useful to your business. It is likely that Query/400 falls into this category and has been a reliable reporting tool that your users have become easily adept with. Query/400 appeals to users because it is easy to learn and does not require programming skills or knowledge in SQL. Also, since IBM development has not made recent changes to the Query/400 code, the user interface has remained familiar and code defects are practically non-existent.

DB2 Web Query has the ability to run your existing Query/400 reports without you changing or running a conversion process on the QRYDFN object. You only must create metadata on the QRYDFN object like you do for a DB2 table. Then DB2 Web Query submits the actual RUNQRY command to the server and displays the results to your browser. Just as RUNQRY has the three output options of display, spool file, or database file, DB2 Web Query also performs the output option that is defined in the QRYDFN.

As discussed in Chapter 3, “DB2 Web Query fundamentals” on page 25, DB2 Web Query requires special metadata to read from table objects. This is also true of QRYDFN objects. The process of creating metadata on QRYDFN objects is quite similar to the process for tables. After the metadata is created, DB2 Web Query treats table and QRYDFN metadata in the same way.

17.2 DB2 Web Query versus Query/400: function similarities

In the following list we summarize how DB2 Web Query and Query/400 have the same functionality:

� Report appearance: Based solely on report appearance, a basic user is unable to tell if the report that is running is based on a DB2 object or a QRYDFN object. The information and appearance of both final reports based on QRY/400 metadata versus DB2 file metadata are identical.

� Spooled file output: If your QRYDFN object is defined with the output option of Printer, DB2 Web Query sends the output to a spooled file.

� Database file output: If your QRYDFN object is defined with the output option of Database file, when DB2 Web Query runs that report it sends the output to a Database file.

� Batch capabilities: It is common to submit a CL program to batch that performs several RUNQRY commands. DB2 Web Query can also perform this functionality. The eventual goal in some shops might be to completely replace their QRYDFN objects with DB2 Web Query reports. With this in mind, DB2 Web Query has a thread-safe command that allows all your reports developed in DB2 Web Query to be used in your batch jobs.

� Right Join: WRKQRY does not support Right Join and neither does DB2 Web Query.

Just as DB2 Web Query supports Query/400 functions, likewise the reverse is true. With the exception of what we discussed in Chapter 5, “Report Assistant” on page 99, all Report Assistant functions can be used on Query/400 metadata. Recall that DB2 Web Query sees the Query/400 result set much like a table.


17.3 DB2 Web Query versus Query/400: function differences

In this section, we discuss the functionality that Query/400 has that DB2 Web Query does not have. In all cases, the limitations are explainable and workarounds are provided.

17.3.1 Parameter passing

It is possible to create a QRYDFN object that can accept parameters at run time. This is done by using a variable in the selection clause. Figure 17-1 shows how this is used. Then the QRYDFN object is called by using the STRQMQRY ALWQRYDFN (*YES) command, which prompts the user for parameters.

Figure 17-1 QRYDFN with parameters

As noted earlier in this chapter, DB2 Web Query sends the RUNQRY command to the server. It does not send any version of STRQMQRY. This limitation means that QRY/400 queries that were coded for use as STRQMQRY ALWQRYDFN(*YES) to allow parameter input must instead use the DB2 Web Query parameter passing. First, you must change your QRYDFN object to not accept parameters. After you create the metadata, you can use Report Assistant to code the parameters into the selection criteria. See 5.4.1, “Parameterized reports” on page 137, for creating a parameterized report.

17.3.2 Using output files for the next query

It is common to use RUNQRY outfile results for use in the next RUNQRY. It is still possible to do this chaining in DB2 Web Query, although you must first create metadata on the intermediate output files. The metadata is hardcoded only with a library and file name. It does not check the format-level identifier of the file as some programs do.

For example, library QGPL is used to hold the work files. You must run all the reports and generate the outfiles to QGPL. Do not delete the QGPL files. Then you create the metadata only once on the QGPL work files and create reports from the work files. When the job is done, the work files are deleted. The next time that the job runs, the work files are created again. As long as the files are created with the same fields and format as before, the previously created metadata successfully runs the report. DB2 Web Query does not know that the underlying files have since been deleted and recreated.

Commonly, the library QTEMP is used to store these intermediate work files. The limitation of DB2 Web Query is that you cannot create metadata on any object in QTEMP. Therefore, the intermediate file must be in a different library. Then the metadata can be created. If you cannot change your work files to be in the QTEMP library, you will be unable to do query chaining. If you change your work files from QTEMP to another library, be mindful to change your program to delete the work files.

In summary, metadata remains valid even if the underlying object is deleted and recreated. However, if the underlying object is changed, then the metadata is stale and must be recreated.

Chapter 17. Using DB2 Web Query to run existing Query/400 reports 443

17.4 Creating metadata from Query/400 objects

Just as DB2 Web Query requires metadata to read from DB2 files, it also requires metadata to read from Query/400. When creating metadata on QRYDFN objects, you must remember to complete a few extra windows, otherwise the metadata creation will not be complete.

As noted earlier, if you change the format of your underlying files, you must recreate the metadata on those files. If you change the QRYDFN on the server side, you must recreate the metadata on that QRYDFN.

The process of creating metadata on a Query/400 runs the query at that time. This is because it is gathering information about the files and columns that were used in the query output. For this reason, the processing of creating metadata on a Query/400 object can be somewhat longer than on a DB2 table.

DB2 Web Query asks for the library name where your Query/400 objects are stored. You can choose to create metadata for all queries in a library in a single execution. In the following steps we explain the process for creating Metadata for Query/400. There are two additional windows for creating metadata on a Query/400 object versus on a DB2 object. Remember to click Next until you no longer see one.

1. In the left pane of the Data Adapters page (Figure 17-2), select the adapter to use. In this case, click Query iSeries adapter and select Create Synonym.

Figure 17-2 Selecting the data adapter


2. In the Query Synonym for Query iSeries pane (Figure 17-3), enter the library where the QRYDFN object resides. In this case we enter the RMMASON library. Click Submit.


3. In the Select Synonym candidates for Query iSeries pane (Figure 17-4), complete these steps:

a. Select the Query/400 object on which you want to create metadata.

b. If you previously created a synonym on this object and want to replace it, select Overwrite existing synonym.

c. In this case, this is the first time for creating metadata on QRYDFN in this library. Therefore we select Default synonym name. By selecting this option, every QRYDFN in the entire library is selected.

Figure 17-4 List of QRYDFN objects


d. You see a warning message like the one in Figure 17-5, which says that the synonym creation process can take a long time. Click OK to indicate that you want to continue.

Figure 17-5 Warning message: creation of synonyms

e. Click Create Synonym.

4. In the Create Synonym for Query iSeries pane (Figure 17-6), if synonyms creation was successful, you see a status of Create successfully. Click Next.

Figure 17-6 Created successfully status message


5. In the Create Synonym for Query/400 File: Save Reports pane (Figure 17-7), notice the Report Name column. Click Next.

This is the last pane on which you must click Next. DB2 Web Query creates a report from your QRYDFN.

Figure 17-7 Final confirmation window: Creation Synonym for Query/400

6. In the Create Synonym for Query/400 File: Save Reports Status pane (Figure 17-8), notice that the status indicates Created successfully for the Query/400 metadata creation. Close this window.

Figure 17-8 Created successfully message: conversion from Query/400 to DB2 Web Query

Now if you go back into your DB2 Web Query domain, notice that the metadata is already created as a report. You can click this report to run it or right-click it for the editing options.

Options when creating metadata: prefix and suffixThe guidelines for adding a prefix and suffix to metadata are the same as outlined in Chapter 3, “DB2 Web Query fundamentals” on page 25. Keep in mind that after metadata creation, you will be unable to tell whether the underlying object is a DB2 table or a QRYDFN.


You might want to add a prefix or suffix that can help you to identify that the object being queried on the server side is a QRYDFN.

17.5 Using DB2 Web Query to edit a QRYDFN

After you create metadata, DB2 Web Query understands the metadata as a result set. You can use DB2 Web Query to edit, sort, and filter the report, but you can only work within that result set. You cannot add new columns to the report, even if the column is from a table that is used in the report. DB2 Web Query, in effect, sees the Query/400 result set as any other table. For example, in Chapter 5, “Report Assistant” on page 99, we learn the difference between compute and define. Since compute is data manipulation done on the client side, you can still use compute on your Query/400 reports. However, the define operation is data manipulation performed on the server side. Therefore, you are unable to do this when editing a Query/400 object. Currently bad data is returned and might change into an error message instead.

If you edit the report from DB2 Web Query, those changes are not reflected in the QRYDFN object. When editing a Query/400 report that contains a join, you can add a new join with DB2 Web Query. However, you will be unable to edit the joins already defined in Query/400.


Chapter 18. Performance considerations

Minimizing the processing time for report requests and maintaining the accuracy and integrity of the report data are major goals for most organizations. In this chapter we discuss DB2 Web Query performance considerations and recommendations. We include a case study that is intended to demonstrate steps that you can take to tune a DB2 Web Query report.

18


18.1 Performance basics

When the objective is to obtain optimal report performance, keep in mind the following DB2 Web Query characteristics regarding how it approaches performance optimization:

� When a DB2 Web Query report is run, the tasks of row selection, joining, ordering, and aggregating must be performed. These tasks can be carried out by the DB2 for i database engine, the DB2 Web Query Reporting Server, or a combination of both.

� DB2 Web Query attempts to translate the source code of a DB2 Web Query report into equivalent SQL statements. When the report is run, the SQL statement is submitted to the database engine for processing.

� Like most other relational databases management systems (RDBMS), the DB2 for i database engine knows its own data. Its optimizer component uses complex costing algorithms to determine the ideal access plan, which indexes to use, and so on, so that it can retrieve the data in the most efficient manner. To aid in its decision-making processes, it maintains various forms of statistics about the data. In addition, much of the database code lies below the Machine Interface (MI) layer of i5/OS, which is an attribute that can yield great efficiencies during the query optimization and execution steps.

� For accomplishing all processing tasks in an efficient manner, the database engine should be preferred over DB2 Web Query. Therefore, the goal of DB2 Web Query optimization is to push as much of this processing, decision making, and execution as possible down to the database level.

If a request is not optimized, the DB2 Web Query Reporting Server performs the tasks such as joining, sorting, and aggregating. In these cases, the database engine retrieves all the rows that are necessary for the request based on the translation. DB2 Web Query then completes that processing necessary to prepare the data for the report. This can have the following results:

� Higher processing costs for both the database engine and DB2 Web Query

� Potentially higher network communication costs since larger-than-necessary result sets are moved around the network

� Higher personnel costs since time is wasted waiting for inefficient queries to execute and return the requested data

18.2 DB2 CLI adapter performance

In this section we discuss performance considerations that are specific to the DB2 call-level interface (CLI) adapter.

18.2.1 Report request process flow

As a foundation for understanding DB2 Web Query performance factors, you must first understand the overall process flow when reporting from relational data. It is important to comprehend this process flow so that you can see where the different phases of optimization occur when a report request is made and how you can influence them.

Attention: SQL translation does not occur for reports that go through the Query/400 or DB Heritage Files adapter. Those adapters use different methods to access the data.


The process of running a DB2 Web Query request consists of two phases:

� The execution phase� The report production phase

Figure 18-1 illustrates the flow of the request through these two phases.

Figure 18-1 Flow of DB2 Web Query report run request

Report execution phaseThe following steps occur during the execution phase of a report request:

1. The Web browser client sends the request to the Web server or application server for processing.

2. The Web server or application server routes the request to the DB2 Web Query Reporting Server.

3. The Reporting Server component handles the following tasks during this phase:

a. Reads and parses the DB2 Web Query metadata

b. Parses the procedure (checks the syntax of the source code)

c. Sends a DESCRIBE request to DB2 for i, so that the Reporting Server can create metadata for the result set that will be returned

d. Passes the procedure to the data adapter for processing

4. The DB2 Web Query data adapter component handles the following tasks during this phase:

a. Analyzes the DB2 Web Query master file for the specific SQL module and dialect to use, and to retrieve the SQL column names

b. Analyzes the DB2 Web Query access file for the specific table to access and which connection to use

Databaseresult set

DB2 fori5/OS

HTTP ClientsWeb Server/

Application ServerWeb Query

Reporting Server

Execution phase

Report production phase

Report

Web Queryresult set

Chapter 18. Performance considerations 451

c. Translates (optimizes) the DB2 Web Query request to the appropriate SQL statement or statements

d. Passes the SELECT statement or statements to the DB2 for i database engine

5. The database engine component handles the following tasks during this phase:

a. Analyzes and optimizes the SQL statement or statementsb. Chooses the appropriate access path and retrieval methodc. Retrieves the datad. Creates the database result set

6. The report execution phase ends.

Report production phaseAt the completion of the report execution phase, the report production phase begins. During the report production phase, the database engine component sends a row and an SQL status code to the Reporting Server.

The Reporting Server component handles the following tasks during this phase:

1. Reads the row from the database result set and processes any remaining actions on that row (IF/WHERE, DEFINEs, and so on, that were not translated by the database engine)

2. Converts nonstandard data into DB2 Web Query format, making it available to DB2 Web Query

3. Puts the valid row into the DB2 Web Query result set

4. Asks the database engine for the next row (FETCH)

5. Repeats tasks 1–4 (loop) until the end of the database result set (SQL status code +100)

6. Processes the DB2 Web Query result set, applies style sheets, and formats the report output as requested by the instructions in the procedure

7. Displays the report via a browser or native program based on the type of output produced (for example, Adobe or Excel)

18.2.2 Adapter processing and optimization

When reporting from relational data sources, the data adapter attempts to translate the source code of a DB2 Web Query procedure into equivalent SQL statements. Adapter optimization is the degree to which a DB2 Web Query request is translated to pure SQL statements to be handled by the database engine. Maximizing the adapter optimization should be a major goal of any DB2 Web Query application. If all the commands in a DB2 Web Query report request are translated into the equivalent operation in SQL, then all joining, sorting, or aggregating functions are handled by the database engine. When this occurs, the request is considered (from a DB2 Web Query perspective) to be totally optimized.

Note: The database engine is now interfacing with the database result set and not the native relational data on DB2 for i.


Table 18-1 displays the DB2 Web Query operations and the SQL equivalent.

Table 18-1 DB2 Web Query operations and SQL equivalent

Operation SQL equivalent

Retrieve rows for columns specified. SELECT

SELECT DISTINCT(….)

Identify the table from which to report. FROM

Simple aggregation functions. SUM, COUNT, AVG, MIN, MAX

Retrieve specific rows. WHERE

Ordering rows. ORDER BY

Retrieve specific aggregated rows. HAVING

Create logical table structures (joins). FROM...WHERE...


Selection and projectionTwo important processes that occur during the SQL translation step of the execution phase are selection and projection. Each is discussed in this section.

� Selection

Selection is the process of retrieving the table rows that meet the request criteria. Selection is translated into various predicates of the SQL WHERE clause except those expressions listed in Table 18-2.

Table 18-2 Selection disablers

Table 18-3 lists the DEFINE expressions that can be translated to SQL.

Table 18-3 DEFINE expressions that can be translated to SQL

Selection disabler Description

Non-translatable DEFINE fields

Certain DEFINE expressions can be translated to SQL as part of aggregation or record selection operations. In some circumstances, they can be used as part of a define-based join. The following examples are of translatable DEFINE expressions:� For selection, the DEFINE expression must be an arithmetic valued

expression, a character string valued expression, or a logical expression.

� For aggregation, the DEFINE expression must be an arithmetic or character string valued (COUNT) expression.

� These expressions are based on what is built (for example, on the right side of the equal sign) in the DEFINE expression, not on the format of the field that is being defined.

Table 18-3 provides more information about the DEFINE field expressions that can be translated to SQL.

Non-translatable DATE fields

DATE fields with formats other than YMD or YYMD.

Spanned DEFINE fields DEFINE fields that span more than one segment in a joined structure.

Expression SQL translatable conditions

Arithmetic expressionsNEWSAL/D12.2 = ((CURR_SAL + OTIME_SAL) x 1.1) - 100;

� Real-field operands of numeric data types (I, P, D, F)� Numeric constants � Arithmetic operators (**, *, /, +, -)� Subtraction of one DATE field from another� DEFINE-field operands satisfying any of the above

Character string expressions FORMAL_NAME/A36 = LAST_NAME | ', ' | FIRSTNAME;

� Real-field operands of alphanumeric data types (TEXT field formats are not supported with DEFINE expressions.)

� String constants � String concatenation operators� DEFINE-field operands satisfying any of the above

Logical expressions (Expressions that are evaluated as true, 1, or false, 0.)

SALES_FLAG/I1 = (DIV_CODE EQ 'SALES') OR (COMMISSION GT 0);

QUOTA_CLUB/I1 = (SALES_FLAG) AND (UNITS_SOLD GT 100);

� Real-field operands of any DB2 Web Query-supported data type (including DATE fields)

� Constants with same data type as fields in the predicate� Relational operators (EQ, NE, GT, LT, GE, LE)� Logical operators (AND, OR, NOT)� Arithmetic or character string expression operands

(above) � DEFINE-field operands satisfying any of the above


For more information about creating DEFINE fields refer to “Defining and computing fields” on page 118.

� Projection

Projection is the process of retrieving the table columns that meet the request criteria. Projection is translated to be objects of the SELECT statement, as follows:

– Columns referenced in PRINT, SUM, or COUNT commands.– Columns used as objects in JOIN or DEFINE operations.– PRINT * and SEG.fieldname return all columns in the master file only.

It is important to understand the DB2 Web Query selection and projection operations because they are both processes that reduce the volume of data that is returned from the database, which helps to improve performance, efficiency, and report response time.

Optimization hierarchyIn addition to individual operations being optimized, a progressive optimization hierarchy affects the SQL that is being generated. Figure 18-2 shows the order of adapter optimization.

Figure 18-2 DB2 Web Query adapter optimization order

This hierarchy is mentioned because it is important for you to know what to focus on first. If your report’s ordering or aggregating is not being performed by the database engine and you are unable to determine why, it might be because join optimization is failing. Therefore, if you

Note: SELECT * is never generated by DB2 Web Query.

Translation to SQL: Regardless of the hierarchy in Figure 18-2, the adapter always tries to translate row selection (WHERE) and projection operations to their SQL equivalents.

Creation of logical table structures (JOIN)

Aggregating rows (SUM/COUNT)

Ordering rows (SORT)

If the join optimization fails, so does the sort and aggregation optimization.

If the sort optimization fails, so doesaggregation optimization.

Aggregation optimization occurs only if the join and sort operations were optimized and aggregation was required.


have a poorly performing report that is joining two or more tables, your analysis should begin with join optimization.

Join optimizationA join operation is a complex function that requires special attention in order to achieve good performance. Again, it must be stressed that the goal is to allow the database engine to perform as much of the optimization and processing as possible. Due to their potential complexity, this is especially true for join operations.

If the join is processed by the database engine, the following steps occur:

1. The DB2 Web Query request is optimized and is translated to a single SQL select statement.

2. The database engine retrieves the data from the tables specified in the select statement.

3. The database engine merges the rows using its chosen join implementation.

4. Screening conditions are applied, if any.

5. The columns in the request are applied.

6. Any column function values or expressions are calculated.

7. One result set is produced.

Table 18-4 illustrates the strengths of DB2 Web Query as well with the corresponding strengths of DB2 for i.

Table 18-4 Quick guide to strengths of DB2 Web Query and DB2 for i

DB2 for i usually handles the join if all the DB2 Web Query commands (where possible) are translated to their SQL equivalent. However, because of the processing hierarchy, sorting and aggregation can still fail.

DB2 Web Query strengths DB2 for i strengths

DB2 for i federated joins Joining on local tables (SELECT...FROM...WHERE)

Complex calculations Row and column selection (SELECT…WHERE)

Sophisticated formatting Sorting (SELECT…ORDER BY)

Generate graphs Aggregation (SELECT…GROUP BY)

Referential integrity and constraint awareness: As of V5R3, the SQL Query Engine also has referential integrity and constraint awareness. This means that the optimizer is capable of using the referential integrity conditions to rewrite the queries to eliminate unnecessary join combinations. This can result in significant performance gains for queries with complex joining and is another compelling reason to try to achieve full DB2 Web Query optimization.


Conditions that prevent full DB2 Web Query optimizationAfter a query request is submitted, there are several conditions that cause the adapter to disable the optimization of the join operation. These join disablers are shown in Table 18-5. You must eliminate these conditions if you want full DB2 Web Query optimization to occur.

Table 18-5 Join disablers

When you create a join connection (via the join tab) between tables, DB2 Web Query might choose to generate and run multiple SQL statements to compute the correct output for your report. In some cases, DB2 Web Query can reduce these multiple SQL statements to a single SQL statement, thereby improving DB2 Web Query’s performance considerably. In particular, when the joined-in table (called the target table to the right of the join panel) is joined via a unique join, DB2 Web Query can process the entire report in one underlying SQL query. A unique join is one where given a row from the initial tables (called host tables to the left of the join panel) matches at most one row in the joined-in target table (on the right tab). The join must be unique over the entire set of target table joined columns. Note that no one column must be unique in the target table.

Optimization and avoiding the multiplicative effectDB2 Web Query allows developers who know that they have a unique join to the target table to configure their report with this knowledge. As a result, DB2 Web Query can potentially reduce the number of SQL statements that are generated, thereby improving performance.

Join disabler Description

DEFINE-based JOINs (only if the DEFINE expression is not translatable)

A DB2 Web Query define-based join allows joining a cross-reference file to a host file field that was created by a DEFINE statement. As mentioned previously in “Selection and projection” on page 454, there are cases in which DEFINE fields are not translated to SQL. When this happens, and that DEFINE field is used as a join field, the join is not translated either.

DEFINE fields that span more than one segment in a joined structure

Joining tables based on DEFINE fields prevents the database engine from processing the join.

Multiplicative effect An aggregation at any level other than the lowest level of the JOINed structure or a child table whose foreign key does not totally cover its primary key (causing the parent table rows to be duplicated). For more information about the multiplicative effect, refer to “Optimization and avoiding the multiplicative effect” on page 457.

Federated joins Joining DB2 for i/OS tables on different systems, partitions, or independent auxiliary storage pools (IASPs) is carried out by DB2 for DB2 Web Query and not the database engine.


On the Report options tab, the developer can select the Use SQL Engine Joins check box, as shown in Figure 18-3. Doing so instructs DB2 Web Query that it is safe to construct a single SQL statement with the appropriate join syntax and submit it to the database engine. Note that choosing the Use SQL Engine Joins option, when there is no unique join to the target table, can result in incorrect results in the report (due to the multiplicative effect described earlier). Consequently, it is important to select this option only when you are certain of the uniqueness of the underlying data.

Figure 18-3 Database optimization setting

To determine whether it is safe to select the Use database optimization check box and avoid the multiplicative effect, you can use one of two verification methods:

� Database constraint verification

If either a primary or a unique database constraint is in place for a table against a specific column or combination of columns, the database guarantees data uniqueness based on that constraint. In such cases, it is safe to select the Use database optimization check box for that join.

� Manual verification

Tables might have unique data without strict database constraint enforcement. You can also verify that the data is unique by inspection or knowledge of the data. The database administrator can run queries similar to the following example to see if the current state of the data is unique:

SELECT CASE WHEN count(*) = count(distinct JoinColumn1||JoinColumn2||...||JoinColumnN) then 'Unique' else 'Not Unique' END FROM target_table


If the state of the data is currently unique, the administrator must use her judgement and knowledge of the data to decide whether future states of the data are also unique. If you are not sure whether future states of the data will be unique over the join columns, then it is better to err on the side of caution and not select the Use database optimization check box.

Sorting optimizationIf any of the conditions listed in Table 18-6 are true, DB2 Web Query performs the sorting.

Table 18-6 Sorting and aggregating disablers

Aggregation optimizationIf any of the conditions listed in Table 18-7 are true, DB2 Web Query performs the aggregation.

Table 18-7 Aggregation disablers

Other ways to influence optimizationThe conditions that we discussed in the previous sections help dictate whether DB2 Web Query or the database engine performs the bulk of the report processing. In addition, there are techniques that you can use to influence this behavior and improve report response time.

Creating SQL viewsDuring DB2 Web Query report development, you might encounter situations in which a report does not fully translate to an SQL statement. If this happens, one technique to help move toward full DB2 Web Query optimization is to create an SQL view with all of the appropriate selection, join, and aggregation syntax specified. Next create the synonym for the view, and in your report definition select that view, rather than the tables from the database description list. This instructs DB2 Web Query to use the view and push the selection, join syntax, and aggregation to the database engine. This particular technique is used to tune a problem report in 18.5, “Performance case study” on page 480.

Sort disablers Description

DB2 Web Query managed join See Table 18-5 on page 457.

Sort on a non-translatable DEFINE field Any request that contains a sort on a non-translatable DEFINE field.

Interface-managed join SQL sorts the answer set by the table’s primary key, causing DB2 Web Query to re-sort for the display report.

Aggregation disablers Description

DB2 Web Query managed join or sort See Table 18-5 on page 457 and Table 18-6.

DB2 Web Query managed row selection Some WHERE clauses are not passed to the database engine.

Non-direct SQL operators The request contains direct operators, such as PCT. and TOT., that cannot be translated into SQL.

Aggregation on a non-translatable DEFINE

Aggregating on a DEFINE field that cannot directly translate to SQL.


The advantages of using views are many. The following list provides an idea of what SQL views can do:

� Provide the ability to specify additional join types that are not supported by the DB2 Web Query product.

DB2 Web Query allows you to specify inner joins and left outer joins. With SQL views, you can define those and the following join types:

– Right Outer– Left Exception– Right Exception

� Allow you to specify CASE statements to handle more complex, conditional logic.

� Provide fullselect support.

SQL fullselect is the term for generating an SQL result set by combining multiple SELECT statements using the UNION, INTERSECT, or EXCEPT operators. This is a feature that helps you solve more complex business requirements.

� Provide Common Table Expression (CTE) and recursive SQL support.

CTEs can be thought of as temporary views that exist only during the execution of an SQL statement. When defined, the CTE can be referenced multiple times in the same view. This can be used to reduce the complexity of the view, making it easier to comprehend and maintain.

Among the V5R4 enhancements for DB2 for i was the ability for a CTE to reference itself. This feature provides the mechanism for recursive SQL, which is especially useful when querying data that is hierarchical in nature, such as bill of materials, organizational charts, and airline flight schedules.

For more information about recursive CTEs, refer to the article “V5R4 SQL Packs a Punch,” which you can download from the Web at:

http://www-03.ibm.com/servers/eserver/iseries/db2/pdf/rcte_olap.pdf

� Allow business logic to reside in the database layer, making it available to all users and all SQL interfaces.

� Provide a database abstraction layer.

� Provide security granularity.

When the views are in place, you can restrict users from accessing tables directly and only allow access through the views. Because both selection and projection can be specified on the views, you can control specific rows and columns that users (or groups of users) can access.

Establishing and using foreign key relationshipsIf you have foreign key relationships explicitly defined in i5/OS database, you can take advantage of a DB2 Web Query feature to include with the selected table’s synonym, every table related to the selected table by a foreign key. The resulting multi-table synonym describes all of this table’s foreign key relationships. This can greatly simplifying the process of creating reports with joins. In fact, in this scenario, you do not even define a join in your report. All columns from the related tables are displayed on the Field Selection tab and you simply select the columns that you want to include in the report. Through the foreign key

Important: Views should not be confused with indexes. They are implemented as non-keyed logical files. This means that views, unlike indexes, have no access paths and thus no access path maintenance. If you or your database administrator (DBA) are concerned about access path maintenance, this is not an issue with views.


http://www-03.ibm.com/servers/eserver/iseries/db2/pdf/rcte_olap.pdf

relationships, DB2 Web Query is able to understand the join syntax that must be created and generates the appropriate SQL statement.

The process of creating synonyms with foreign key relationships is discussed in “Referential integrity” on page 57.

Creating materialized query tablesMaterialized query table (MQTs) provide another method of improving performance of your queries. An MQT is a table that contains the results of a previously run query, along with the query’s definition. It provides a mechanism for improving the response time of complex SQL queries. While it can be thought of as a summary table, what sets an MQT apart from a regular summary table is the fact that the SQE optimizer is aware of it and its relationship to the query and base tables that were specified when it was created and populated. This means that the optimizer considers using the MQT in the access plan of subsequent similar queries if it determines that it is appropriate to do so. Because the MQT is already created, populated, joined, aggregated, and sorted, this can result in significant performance improvements for complex queries.

It is important to understand that an MQT is a table (a physical file with an object type of *FILE) that resides in a library (schema) in the System i environment. Because of this, it can be accessed directly, just like any other table on the system. While it is usually the optimizer’s job to select and implement an MQT in the access plan of a query request, DB2 Web Query has the ability to create metadata against an MQT. This means that you can create DB2 Web Query reports that access an MQT directly, and not be forced to rely on the optimizer to select the MQT.

To obtain this behavior, you must first create the metadata for the MQT:

1. From the DB2 Web Query home page, right-click your reports folder and select Metadata.

2. In the Data Adapter browser window, from the left navigation pane, expand the DB2 cli folder and click *LOCAL. Select Create Synonym.

3. In the Select Synonym Candidates for DB2 CLI (*LOCAL) pane (Figure 18-4), specify the collection and select the MQTs check box. Click Next.

Figure 18-4 Creating a synonym for MQT: specifying the collection


4. In the Create Synonym for DB2 cli pane (Figure 18-5), specify a prefix and suffix, select the MQTs that are listed, and click Create synonym.

Figure 18-5 Creating synonym for MQT: select MQT

After the synonyms are created for the MQTs, you can create reports against them as you would for any other table object on the system.

While their potential performance efficiencies are appealing for DBAs, query developers, and report users, MQTs have several attributes and limitations that must be understood prior to implementation. Probably most important, you must know that MQTs are not automatically maintained. This means that as the base tables used to populate the MQT change, the data in the MQT does not also change. If the data in your reports must be up to date, the MQT must first be manually refreshed. Therefore, before implementing MQTs, you must be willing to accept some level of data latency. This is can be acceptable for queries that report on data that is historical in nature. However, if your report requires data that is dynamic and up-to-the- minute, you might come to the conclusion that an MQT is not the right fit.

For more information about MQTs see the white paper Creating and using materialized query tables (MQT) in IBM DB2 for i, which you can find on the Web at:

http://www-304.ibm.com/jct09002c/partnerworld/wps/servlet/ContentHandler/SROY-6UZ5E6

18.2.3 Remote database access considerations (including cross-system joining)

One feature of the DB2 Web Query base product is the ability to access data on remote DB2 for i systems or partitions. This feature, which is available only for the DB2 CLI adapter, gives you the option to pull data for your reports in one of the following ways:

� Local: All the data resides on the local system.

� Remote: All the data resides on one remote system or partition.

� Cross system: Data is spread across the local system or one or more remote systems or partitions.

If full DB2 Web Query optimization can be performed for Local and Remote database access, and no other external factors are negatively influencing query performance, you can expect your reports to perform reasonably well. Again, this is because DB2 Web Query can generate one SQL statement and allow the DB2 for i database engine to process the request.


http://www-304.ibm.com/jct09002c/partnerworld/wps/servlet/ContentHandler/SROY-6UZ5E6

However, you must be aware of the performance implications if the data is spread across two or more System i machines or partitions. In this scenario, DB2 Web Query generates a separate SQL statement for each connection and submits the statement to each connection. The answer set from each of these multiple sources is then joined together by the Reporting Server. Depending on how the joins are specified, this can be a lengthy and time-consuming process. Consider the following scenario.

A fact table (ORDERS) has 32,283 rows and is joined to a dimension table (STORES) that has 116 rows. If both of the tables are on the local (or even remote) system, DB2 Web Query generates a single SQL statement and submits it to DB2 for i. Example 18-1 shows how the statement looks.

Example 18-1 Single SQL statement

SELECT T2."Country",T2."State", SUM(T1."LineTotal") FROM CENTURY/ORDERS T1,CENTURY/STORES T2 WHERE (T2."StoreCode" = T1."StoreCode") GROUP BY T2."Country",T2."State" ORDER BY T2."Country",T2."State" FOR FETCH ONLY

Since one statement is generated and the database engine handles all the joining, grouping, and ordering, you can expect this report to run quite efficiently.

However, if the dimension table STORES resides on another system and Report Assistant is used to create a nearly identical report (the only difference being a cross-system join specification to STORES), DB2 Web Query now creates two SQL statements, one for each system.

� Local system

Example 18-2 Local system SQL statement

SELECT T1."StoreCode",T1."LineTotal" FROM CENTURY/ORDERS T1FOR FETCH ONLY

� Remote system

Example 18-3 Remote system SQL statement

SELECT T5."Country",T5."State" FROM "CENTURY"/"STORES" T5 WHERE (T5."StoreCode" = ?) FOR FETCH ONLY

Inefficiencies occur because the remote SQL statement is submitted multiple times on the remote system. The local system fetches each row from the (local) ORDERS table result set and generates the appropriate local selection to return the matching row from the remote STORES table. With this implementation, the report takes significantly longer before the results are displayed to the browser.

If the report is modified to specify STORES (with only 116 rows) as the base table, the join fan-out is greatly reduced. This results in a report that runs significantly faster, but is still not nearly as fast as when all tables are on same system. Therefore, we generally recommend that you avoid creating reports with cross-system joins when the tables have a substantial


number of rows. However, if such an implementation is required, consider the following suggestions to enhance the report’s performance:

� Eliminate the report’s requirement of multiple connections by making local copies of the remote tables. After all tables are on one system, join optimization can be enabled and DB2 Web Query attempts to generate a single SQL statement.

� Determine which of the tables has the smallest number of rows (after applying local selection) and make that the base table of the report. This reduces the fan-out effect of the join, thereby reducing the number of rows that must be retrieved from the other (larger) tables.

� Edit the report source and add the following line:

SQL DB2 SET JOINTYPE SORTMERGE

Figure 18-6 shows an example of this setting specified in the report source. This setting impacts the number of FOR FETCH lines when one of the tables is remote. In effect, it turns all of the tables into local internal tables and sort merges them.

Figure 18-6 SORTMERGE setting

18.3 Query/400 adapter performance

Another feature of DB2 Web Query is the ability to run most existing i5/OS Query/400 queries. This is done by using the Query/400 adapter that is provided with the base offering of 5733-QU2. This adapter functions by running the Query/400 query during both the synonym creation process and report execution. This means that if you have an existing Query/400 object that does not perform well and takes several minutes to run to completion, it requires just as much time (and perhaps more) to create the DB2 Web Query synonym. After the synonym is created and you run the new DB2 Web Query report, you can again expect it to require at least the same amount of time to run.


Because the adapter is running the existing query, you are limited in the tuning that can be done to make each of the DB2 Web Query processes perform better. In most cases, the sole tuning knob ensures that the appropriate indexes are in place for the optimizer to use when creating the access plan for the query. Refer to 18.4.3, “Indexes” on page 475, to learn about approaches for implementing an indexing strategy.

As we mentioned earlier in this chapter, Classic Query Engine (CQE) processes non-SQL database requests such as those from Query/400 queries. CQE provides index advisory information for query selection. Missing from CQE is the ability to create index advisories for joining, grouping, and ordering. Analysis and tuning, which are more manual in nature, are required for these types of requests. If your Query/400 reports are not performing to your satisfaction, make sure that the indexes exist over all join fields, order by fields, and fields that are aggregated.

18.4 DB2 for i optimization

By now you should be convinced that getting DB2 Web Query to hand off as much of the processing as possible to the database engine is a key factor in achieving optimal report performance. There are also factors within the i5/OS database itself that can affect efficiency.

These types of factors are usually the responsibility of the DBA and not the users. However, a little knowledge of these factors and how they can affect efficiency enables a user to communicate effectively with the DBA.

When the users have done everything that they possibly can in the efficiency spectrum to ensure that the report definitions are as good as they can be, the following DB2 for i factors can still influence the overall efficiency of the request:

� Database design� Query Engine used� Indexes� Available hardware � Number of concurrent users

18.4.1 Database design

Good performance starts with a good database design. If your database structure is flat in nature and not normalized, the files are likely to have redundant data that is difficult to navigate, retrieve, and maintain. The complexities of retrieval and maintenance are often handled by a high-level language (HLL) program written in RPG or COBOL. This approach works when such programs are the only interface to the data and can hide the complexity from users. However, problems and confusion are likely to result when you expose your database and allow other interfaces, such as DB2 Web Query, to access and report against the data. In the following list, we highlight the shortcomings of a poorly designed database:

� Complexity

The application programs contain most, if not all, business rules and data relationships. Therefore, the data is difficult to query because it is hard to understand rules and relationships. Because of the complexity, programmers (and not users) are forced to develop the reports. Often the reports themselves are HLL programs that can be complex and difficult to maintain. Programmers can find themselves constantly creating new copies of reports to satisfy a seemingly endless list ad hoc reporting requirements by the user.


� Lacks flexibility

The database is difficult to maintain, adapt, and expand. Repeating groups must be squeezed into a single record, which places limits on the number of repeating groups that can fit into a single record format.

� Less optimal access methods

Performance of these reports can suffer because of the database complexity. Programmatic selection, joining, ordering, and grouping are often implemented with a row-at-a-time coding techniques. Record blocking and set-at-a-time processing are not used and, therefore, the report performance is not maximized.

If this describes your current database design, you might want to consider investing in a robust data modeling tool that can help you implement a database design that is both functional and efficient.

18.4.2 Query Engine used

As described earlier in this publication, DB2 for i employs two database engines. Both CQE and SQE are used to process database access requests. Although SQE is the engine designed for SQL access, there are still inhibitors that can prevent SQE processing for SQL requests. The SQE inhibitors for each supported version of the operating system are listed in Table 18-8.

Table 18-8 SQE inhibitors

Your goal as a database administrator or DB2 Web Query administrator/developer should be to ensure that each DB2 Web Query request is processed by SQE. Why is this so important? Because SQE is the IBM strategic optimizer, and as such, it will be the one on which the IBM development team focuses. Enhancements that add new features and boost performance will only be applied to SQE, not CQE. Consequently, when a query is processed by SQE you can

5.4 SQE inhibitors 6.1 SQE inhibitors

� Sort sequences � Non-SQL Interfaces (OPNQRYF, Query/400,

QQQQRY API)� Logical File reference on FROM Clause� Select/Omit Logical Files defined on tables� User Defined Table Functions (UDTFs),

UPPER and LOWER functions� Read Triggers

� ICU 2.6.1 Sort Sequences � Non-SQL Interfaces (OPNQRYF, Query/400,

QQQQRY API)� Logical File reference on FROM Clause� Select/Omit Logical Files defined on tables

Important: While as of 6.1 the SQE optimizer is still unable to utilize Select/Omit logical files when building query plans, IBM did change the default value for the Ignore_Derived_Index QAQQINI parameter to enable more SQE usage. This QAQQINI parameter was first added back in V5R3 to allow the SQL Query Engine to be used in environments where SQL statements are referencing DB2 objects created with DDS. Prior to 6.1, the default value for this parameter was *NO, causing the SQE optimizer to reroute execution of any SQL request to the Classic Query Engine (CQE) anytime that a derived logical file was encountered during the query optimization process. The default value in 6.1 for the Ignore_Derived_Index QAQQINI parameter has been changed to *YES. This value allows the SQE query optimizer to ignore any keyed logical files that contain select/omit criteria during optimization and process the query instead of rerouting execution to CQE.


expect vastly superior performance over the same query handled by CQE. Some of the reasons for this include:

� Enhanced optimization techniques—a smarter, faster, and more efficient optimizer� Self-learning query optimization� Ability to self-adjust during query execution� Better/faster database primitives to access the data

In addition, SQE provides many more features than CQE. Among them are:

� Materialized Query Tables (MQTs)� Maintained Temporary Indexes (MTIs)� SQE plan cache� Ability to cache results

Achieving SQE processing for every DB2 Web Query request is quite simple: avoid SQE Inhibitors. The following list provides the major issues to look out for in a proactive mode:

� Avoid creating metadata for DDS logical files.

– Only create metadata over tables/physical files, SQL views, or MQTs.

– If you need the filtering or joining provided by a DDS Logical File, create an SQL View that performs the equivalent filtering/joining.

� Watch out for Select-Omit logical files against physical files.

Again, this is not as important in 6.1because the default behavior is for SQE to ignore Select-Omit logical files. But if you are at 5.4 of the IBM i operating system and you need to create metadata over a physical file that has Select-Omit logical files against it, you will can instruct the optimizer to ignore this derived logical file by using the IGNORE_DERIVED_INDEX parameter in the QAQQINI query options file. This process is documented in the tech tip Maximize SQL Query Engine (SQE) Usage of Your DB2 Web Query Reports, which can be access from the following URL:

http://www.mcpressonline.com/database/db2/maximize-sql-query-engine-sqe-usage-of-your-db2-web-query-reports.html

� Use the DB2 CLI adapter whenever possible.

– Keep in mind that both the Heritage File and Query/400 adapters use CQE.

– Recreate Query/400 reports as new reports that use synonyms based on the DB2 CLI adapter.

– There is no way to avoid it for multi-format files (must use Heritage File adapter).

– Use SQL Aliases to access multiple members.

Determining which engine is usedYou can also work in a reactive mode to determine which engine is handling your query requests. This can be done by collecting a database monitor and analyzing the results. Two of the most common ways to do this are as follows:

� Run the statement in Run SQL Scripts window (System i Navigator) and use Visual Explain to analyze the results.

� Start a database monitor collection, run the query, and use the System i Navigator dashboard to analyze results.

Using Run SQL Scripts window and Visual ExplainWith this method, you capture the SQL statement that DB2 Web Query is producing for a report and copy and paste the statement into the Run SQL Scripts window of System i Navigator. Visual Explain is then launched against the statement to produce a graphical


http://www.mcpressonline.com/database/db2/maximize-sql-query-engine-sqe-usage-of-your-db2-web-query-reports.html

representation of the optimizer’s chosen access plan for the query, as well as a wealth of information about the plan. Part of the information provided in this process is which query engine is used.

To implement this method, take the following steps:

1. Right-mouse the report and select Run w/SQL Trace.

Figure 18-7 Run w/SQL Trace

Rather than running the report and displaying the results, this option displays the generated SQL statement.

2. As shown in Figure 18-8, copy this statement to your clipboard.

Figure 18-8 Copy the SQL statement

3. In System i Navigator open a connection to your system and launch a Run SQL Scripts window.


4. Paste the statement from your clipboard into the Run SQL Scripts window. This is shown in Figure 18-9.

Figure 18-9 Paste the SQL statement

5. As shown in Figure 18-10, swipe/highlight the statement and click the Explain icon in the tool bar.

Figure 18-10 Explain the SQL statement

Tip: Depending on your configured naming convention (*SQL or *SYSTEM in the format tab of the JDBC settings for your System i Navigator connection), you may have to edit the statement after you paste it into the window. The naming conventions are:

� The *SQL naming convention uses a period (.) between the library and object names.

� The *SYS naming convention uses a forward slash (/) between the library and object names.

This means that you may have to the replace the / character with a period (.) for all qualified object references.


This action launches the Visual Explain utility. Visual Explain provides information about the optimizer’s chosen access plan. It also renders a graphical representation of the query access plan.

6. Select the Final Select icon on the plan and scroll down to the bottom of the Attribute pane on the right. This is shown in Figure 18-11.

Figure 18-11 Visual Explain example

The Query Engine Used attribute appears at the bottom. The value of this attribute provides the information for which you are looking. In this case, SQE was used.

Using database monitor collectionAnother technique is to run the report in DB2 Web Query after starting a an SQL monitor. You can then use the dashboard provided with the On Demand Performance Center tool to quickly determine which query engine is used.

The following steps describe this process:

1. Open a System i Navigator connection to your system and expand Databases → <name_of_your_database>.


2. Right-click SQL Performance Monitors and select New → SQL Performance Monitor, as shown in Figure 18-12.

Figure 18-12 Start new SQL Performance Monitor

3. On the SQL Performance Monitor Wizard dialog window, specify the following:

– Name: DB2 Web Query Redbook monitor– Type: Detailed– Schema for data: QGPL

Click Next. An example screen is provided in Figure 18-13.

Figure 18-13 SQL Performance Monitor Wizard window 1


The second dialog window for SQL Performance Monitor Wizard is presented. This window allows you to specify pre-filtering criteria for the monitor collection. Using pre-filtering is strongly recommended because it can greatly reduce the amount of monitor data collected. This will help keep your analysis simple. In this example, you pre-filter on the user profile running the request and the schema (library) name of the object being queried. This should keep the collection small (ideally to a single SQL statement).

4. As shown in Figure 18-14, specify the following prefilter criteria and click Next:

– Check the box for Current user and specify your user profile name.

– Check the box for the setting Statements that access these objects and under Schema, enter QWQCENT.


5. On the third dialog window for SQL Performance Monitor Wizard, select the radio button for All jobs and click Next. An example is displayed in Figure 18-15.



On the final dialog window for SQL Performance Monitor Wizard, click Finish.


6. Return to your DB2 Web Query browser session and run the report.

At this point the monitor data has been collected for the report run. The monitor can now be ended.

7. Return to the System i Navigator session. Under the connection, select Databases → <name_of_your_database → SQL Performance Monitors.

A list of available SQL Performance monitors is displayed.

8. Find the monitor that you just started and select End from the right-click menu (Figure 18-17).

Figure 18-17 End SQL Performance Monitor


9. Now you can analyze the results. Again, right-click the monitor entry. This time select the Analyze option, as shown in Figure 18-18.

Figure 18-18 Analyze SQL Performance Monitor

The SQL Performance Data Analysis dashboard window is launched. Under the Overview category, find the lines for SQE and CQE. As displayed in Figure 18-19, the dashboard shows the value of 1 for SQE and 0 for CQE. This means that your query was processed by SQE.

Figure 18-19 SQL Performance Data Analysis dashboard


18.4.3 Indexes

Like any other application that accesses information from the database, efficient DB2 Web Query performance heavily depends on having the correct indexes in place. When your database is in production, it might be difficult to implement recommended database design practices such as database normalization. However, at this point, you can still implement an indexing strategy that helps to optimize the performance of your query reports.

Indexes over your database tables have the following advantages:

� Provide statistics to the optimizer.

Indexes against the queried tables give the optimizer a better opportunity to select the most efficient access method. This is because they provide relevant statistics and information, such as the average number of duplicate values and column cardinality of the tables being queried. Such useful information provided to the optimizer results in a better access plan and a better performing query.

� Improve efficiencies.

The optimizer can choose to use the index during implementation, thus avoiding more costly implementation alternatives such as table scans or creation of temporary structures. If a table scan is performed, every row in the database table must be read. Depending on the size of the tables and the complexity of the query, this an be a lengthy process and can consume a significant share of system resources.

� Ensure uniqueness.

A unique index on a column ensures that no duplicate values exist for that column.

Using indexes might result in the following ramifications:

� As mentioned previously, indexes can speed data retrieval. In some cases, requests might only need to use the index, never accessing the actual data (a condition referred to as Index Only Access).

� Even secondary indexes can be used in the case of data selection statements.

� Indexes add overhead to a database. Indexes must be maintained by the database whenever the data in the underlying table changes. Sometimes DBAs are reluctant to add indexes for reporting application efficiency if the database is one that is not dedicated to reporting purposes.

Indexing strategies is a broad topic that is covered in detail in the white paper Indexing and Statistics Strategies for DB2 for i. You can download this paper from the Web at the following address:

http://www.ibm.com/servers/enable/site/education/ibo/record.html?indxng

In addition, the following tips can help you get started:

� Take a proactive approach and make sure that there are indexes available over all of the selection, joining, ordering, and grouping columns of your queries.



� In a reactive mode, run your queries and use the available database feedback mechanisms to determine what indexes the optimizer wants created.

When a query is executed, the database engine provides index advice during the optimization phase. This occurs when it determines that a useful index does not exist against the tables that are being queried. It makes a recommendation that the index be created. Afterward, this advice can be obtained from various sources, including the following sources:

– Index Advisor– SQE Plan Cache– SQL Plan Cache snapshot, 3020 record– SQL Performance Monitor, 3020 record– Visual Explain

The index advisories can be extracted from these sources of optimizer feedback and used to create the recommended indexes.

For more information about SQL and database performance analysis, refer to OnDemand SQL Performance Analysis Simplified on DB2 for i5/OS in V5R4, SG24-7326.

18.4.4 Available hardware

Hardware is certainly a critical component when considering the factors that can impact an application’s performance. Insufficient resources usually mean that users sit and wait while the work is being done. Typically, older hardware equates to fewer resources: slower processors, less memory, and overall inferior throughput. While DB2 Web Query can run on any system with V5R4 or later, newer models do offer the advantages of more processing power and better overall throughput. The product makes heavy use of JAVA and SQL, two technologies that will consume system resources. The bottom line is that factors such CPW ratings and amount of available memory do matter when it comes to DB2 Web Query performance. This is true of any application running on the system. If its been a while since your last upgrade, you must evaluate your performance expectations and decide whether you want to run modern software on a server that is, for example, 12 years old.

A balanced systemWhile sufficient hardware resources to run your workloads is critical factor, it is also important that you have a balanced hardware configuration. What does this mean? It means that simply adding more memory or another processor to your system may not improve overall performance and create an unbalance in the environment. This is because when it comes to driving workloads, the ultimate goal is to keep the processor busy while minimizing wait times (queuing). To help illustrate this, consider the following dish-washing analogy.

Let us say that you own a restaurant and one of the workloads to be performed is washing dishes. In this subsystem the busser (term used for both busboy and busgirl) brings the dirty dishes and places them in the sink and the dishwasher (a person) takes the dishes out of the

Important: When an advised index is created and the query is run again, you might observe that the optimizer does not use that index during implementation. Indexes are sometimes recommended for the information that they can provide to the optimizer. This information is used to help the optimizer cost each access method. It might also help the optimizer determine that the advised index is not the optimal one to use during query execution.


sink and washes them. Each component in this process can be analogous to a component in your hardware configuration:

� The dishwasher = the processor� The sink = memory� The bussers = disk units/arms

The goal is to keep the dishwasher busy (as long as there is work to be done) so that the dishes are cleaned as fast as possible. Therefore, acceptable performance and a balanced system are largely dependent on the following:

� The speed of the dishwasher� The number of dishes to be washed� Performance expectations

Let us say that the process is not going as fast as you would like and not enough dishes are being cleaned. Your performance expectations are not being met. So you take the following steps:

1. You walk into the kitchen and discover that Frank, the dishwasher, is waiting for work. This means that queuing is occurring earlier in the process. You observe that there are four bussers (working frantically) and they cannot bring dishes into the sink fast enough (queuing at the disk I/O level is occurring). So you hire four more bussers.

2. This corrective action helps and Frank becomes busier but is still waiting for work. So, again, you hire four additional bussers. This has no effect on performance because now the bussers are queued up, waiting to place dishes in the sink because the sink is full (not enough memory). This is an example of an unbalanced system.

3. Showcasing your sharp business acumen, you purchase a bigger sink (more memory). This eliminates the queuing at the sink and Frank stays busy all the time. You now have a balanced system, but you are still not satisfied with the pace of which the dishes are being washed.

4. Because it worked before, you decide to trade in that sink for one that is even larger. You then observe that many more dishes can be placed in the sink, but it does not help overall performance whatsoever, This is because the dishes are piled up in a big heap in the sink and Frank cannot work any faster (too much memory). At this point the system is again out of balance.

5. Evaluating the situation, you ascertain that hiring more bussers will not help. And an even bigger sink would be a foolish purchase. You conclude that there are two choices: you can either fire Frank and hire a faster dishwasher (upgrade) or you can hire another dishwasher to help Frank out (add another processor). Frank is a good guy and has never called in sick once in the three years he has been employed, so you decide to help him out and hire his third cousin Gus. This new hire proves to be the right move: Frank and Gus become a formidable dishwashing duo, producing clean plates at a brisk and more than acceptable pace. The number of bussers is optimal, as is the size of the sink, thus there is no queuing. You finally have a balanced system that meets your performance expectations.

This simple analogy is meant to illuminate the fact that the amount of work to be done, performance expectations, and a balanced system must be considered when it comes to evaluating your hardware resource needs.

Workload estimator for DB2 Web Query Determining the system resources needed to run your query workloads while maintaining a balanced system is not a trivial task. To help you with this venture, IBM has provided a Work Load Estimator (WLE) for DB2 Web Query. This tool is a sizing guide that is provided to help


you estimate your hardware resource needs for DB2 Web Query workloads and is part of the IBM suite of sizings guides. It is based on a series of workload benchmarks defined and performed by the IBM STG Lab Services team.

To access the DB2 Web Query WLE, open a Web browser and specify the following URL:

http://www.ibm.com/servers/sizing

Once on this site, specify DB2 Web Query as the search refinement text string, as shown in Figure 18-20.

Figure 18-20 Search sizing guides

Once you are into the DB2 Web Query WLE, you define the workload characteristics to the tool. Information such as the following should be included:

� Users

Includes the number of concurrent users and developers and the types of users (heavy, medium, light).

� Environment

Attributes about the environment in which the DB2 Web Query product will be running. This include factors such as the size of your database.

� Specifics of production environment, if applicable

Specify whether queries are running in a shared environment (for example, against production databases) or a dedicated environment (for example, a data warehouse).

Once you have completed these steps, the sizing guide provides an estimate of the minimum hardware configuration necessary to run the defined DB2 Web Query workloads.


http://www.ibm.com/servers/sizing

Figure 18-21 provides an example of the output produced by the DB2 Web Query WLE.

Figure 18-21 Sample output of Workload Estimator for DB2 Web Query

18.4.5 Concurrent users

Unless they sign on to the system and do nothing, application users typically equate to more workload on the system. More units of work means that more system resources are being

Note: Although DB2 Web Query does not require Power6 hardware, the DB2 Web Query WLE produces Power6 hardware recommendations only.

Important: The use of the Workload Estimator and its results are restricted to the purpose of helping you predict a possible system solution. These results are estimates and averages based on certain assumptions and conditions, and are based on measurements and analysis with a variety of workloads (internal to IBM and by third parties), performance characterizations of systems hardware and software, and best performance practices. Ensure that realistic inputs have been provided for the high-level configuration, the workload definitions, and user options. Actual customer results may differ significantly.

The system recommendations are based on measurements of a fixed set of reasonably well-tuned queries. Resource requirements for any specific user workload will vary depending on the complexity of the queries, the make-up of the database, and the extent to which the queries have been tuned.


consumed. You may have a balanced system with satisfactory performance, but at some point (as you add more users or those existing users request more work or work that is more resource intensive) you will either experience queuing or a processor that cannot keep up.

Getting back to the dish-washing analogy, as the word spreads and your restaurant gains popularity, you suddenly have an influx of new customers. More customers means more dirty dishes that must be washed. Frank and Gus may need some help, perhaps in the form of more bussers, a larger sink, or another dishwasher. The balanced system may need an adjustment.

Much of this is obvious, but you may find it difficult to find the right balance. This again is where the DB2 Web Query WLE can prove to be helpful, because it does consider the number of concurrent users in its calculations.

18.5 Performance case study

In this section a case study is conducted against a long-running DB2 Web Query report to delve further into performance analysis and demonstrate available optimization techniques. The objective is to determine why the particular report has an excessive runtime and provide example approaches in order to reduce the overall runtime.

In this section we describe the following steps:

1. Identify a long-running report.2. Perform analysis, looking for optimization disablers.3. Determine report-tuning options.4. Create an SQL view and synonym and change the report to use view.5. Create a new report based on the SQL view.6. Perform additional database analysis and tuning.

18.5.1 Identifying a long-running report

During unit testing, a report that was created using Report Assistant and the SQL CLI adapter was identified as one that required an excessive amount of time to run to completion. This report, named “Order Revenue within 180 days by Year, Month”, took several minutes to run. However, reports that were similar in nature, meaning that they had the same general format and approximately the same number of rows returned, ran in seconds.


18.5.2 Performing analysis and looking for optimization disablers

To help determine the reasons behind the substantial run time, DB2 Web Query provides the Run w/SQL Trace option (Figure 18-22) to run the report and generate an SQL trace. The trace statements that are displayed help reveal any optimization disablers that might be present in the report.

Figure 18-22 Run w/SQL trace

When the report is run using the Run w/SQL Trace option, the SQL trace information is displayed as HTML output to the browser, as shown in Figure 18-23.

Figure 18-23 Report trace results

This trace reveals a couple of interesting points. First, it shows that part of the report cannot be translated to SQL. In this case, translation failed for the Defined field DAYS_DIFF because


of an unsuccessful IF/WHERE Test. Second, notice how the trace shows the SQL statement that is generated (and what is ultimately submitted to the database engine). Even though part of the translation failed, the Reporting Server was able to construct a meaningful SQL statement.

Using the trace, you can conclude that the problem with this report is the use of the define field DAYS_DIFF. The line in the trace FOCUS IF/WHERE TEST CANNOT BE PASSED TO SQL. DAYS_DIFF indicates that DB2 Web Query attempted (and failed) to generate an equivalent search condition for the SQL statement’s WHERE clause (Figure 18-24).

Figure 18-24 Define field DAYS_DIFF

Anytime that a define field can be passed to the database engine, a more efficient report results, particularly when the define field is part of the selection process, which it is the case in our example. If the define field cannot be passed to the database engine, then all the rows from the result set of the generated SQL statement are returned to the Reporting Server, which now is responsible for the selection (and sorting if the report is sorted by the define field). This kind of behavior can negatively impact performance and should be avoided if at all possible. Again, we must emphasize that the report is more efficient if the entire database access portion of the report definition can be pushed down to the database engine for processing.

18.5.3 Determining report-tuning options

Tuning this particular report basically means selecting one of the following actions:

� Eliminate the culprit define field.� Modify the report in an attempt to enable SQL translation for the define field.� Push the define field logic down to a database using SQL views.

For this example, the define field is required to deliver the necessary information in the report (and therefore cannot be removed). In addition, repeated efforts to fix the translation for the define field prove to be futile. Therefore, only the third option remains, which is to push the define field logic down to a database using SQL views.


18.5.4 Creating an SQL view and synonym

The next step is to create an SQL view that contains all the required tables, join syntax, columns, and selection, including the DAYS_DIFF field selection that DB2 Web Query was unable to directly translate to SQL. To provide the ability to calculate the number of days between the date 1998-01-31 and the value of the SHIPDATE column, a new result column is added to the view. Example 18-4 shows this result column, also named DAYS_DIFF.

Example 18-4 DAYS_DIFF result column

DAYS('1998-01-31') - DAYS(T1.SHIPDATE) AS DAYS_DIFF

To create the new view:

1. From a System i Navigator, open a connection to the System i environment and open a Run SQL Script window.

2. Type the CREATE VIEW statement or use the SQL selection statement that is displayed in the trace as a base for this view definition and make the necessary modifications. Copy and paste the statement into the Run SQL script window and begin making the changes. For the copy and paste method, Figure 18-25 shows more details about what to add and remove from the selection statement to form the CREATE VIEW statement.

Figure 18-25 Anatomy of the CREATE VIEW statement

Notice that the local selection is removed from the CREATE VIEW statement. This is added to the statement that references the view. Also observe that the ORDER BY clause is removed. This is because views cannot be ordered. Ordering is specified in the report definition.


After all the necessary modifications are made, Example 18-5 shows how the CREATE VIEW statement should look.

Example 18-5 Create SQL view

CREATE VIEW STAR1G.DAYS_DIFFERENCE_VIEWAS SELECT T1."SHIPDATE",T1."CUSTKEY",T1."REVENUE_WO_TAX",

T2."CUSTOMER",T3."YEAR",T3."MONTH", DAYS('1998-01-31') - DAYS(T1.SHIPDATE) as DAYS_DIFFFROM STAR1G.ITEM_FACT T1, STAR1G.CUST_DIM T2,STAR1G.TIME_DIM T3 WHERE (T2."CUSTKEY" = T1."CUSTKEY") AND (T3."DATEKEY" = T1."SHIPDATE")

3. Execute the statement to create the view.

4. From the browser, open the DB2 Web Query metadata window and create a synonym against the new view.

18.5.5 Creating a new report based on the SQL view

When the new view and its synonym are in place, a new report is created to access the contents of the view:

1. From DB2 Web Query home page, select Report Assistant to create a brand new report.

2. In the Select from available database descriptions window (Figure 18-26), select the new view. Click OK.

Figure 18-26 Report Assistant: selecting a new view


3. Continue creating the new report with the view, specifying the same field format and selection criteria fields (as the original report). Examples are shown in Figure 18-27 and Figure 18-28 on page 486.

Figure 18-27 Report using SQL view: Field selection tab


Figure 18-28 Report using SQL view: Selection criteria tab

4. Save the report and click Quit.

5. Run the new report.

6. Record performance measurements.

In the case of this example, significant improvements in performance are observed. In fact, simple benchmark measurements reveal that the report, using the view, runs over 10 times faster than the original version of the report. This is not meant to imply that you will experience the same improvements if you conduct such a tuning exercise. It is only intended to serve as an example of the kinds of efficiencies that you can obtain. Many factors can affect report performance, so your results might vary.

18.5.6 Performing additional database analysis and tuning

When your report is using the SQL view and all database processing is being handled by the database engine, your work might not yet be done. You can potentially gain further efficiencies by performing regular database analysis and tuning. You can use the following tools and technologies to assist in this effort:

� SQE Plan Cache

First made available in V5R2, the SQE Plan Cache is an internal, matrix-like repository that is used to store all of the statements and access plans implemented by SQE. In V5R4, an interface to this information has been made available through the System i Navigator toolset. From this interface, you can find the SQL statement generated by DB2 Web Query and begin performing your analysis.


� Visual Explain

Visual Explain provides a graphical representation of the optimizer implementation of a query request. The query request is broken into individual components with icons that represent each unique component. Visual Explain also includes information about the database objects that are considered and chosen by the query optimizer. Visual Explain’s detailed representation of the query implementation makes it easier to understand where the greatest cost is incurred.

� Index Advisor

Introduced in V5R4, this feature provides an easy and quick interface to index advisories that are issued by the optimizer. If the optimizer determines that a permanent index against a reference table might be beneficial, it returns the key columns necessary to create the suggested index. The data of the system-wide Index Advisor is placed into the SYSIXADV table in the QSYS2 schema.

� Database monitor

The Database Performance Monitor is a set of integrated tools that is used to collect database-specific performance information for all SQL requests. It can be thought of as an SQL tracing facility, one that tracks all SQL statements, access plans used to implement the statements, resources used, and subsequent performance results. All this information is stored in a database tables, where it can be analyzed and used to identify and tune performance problem areas.

� Materialized query tables

As mentioned previously, an MQT is a DB2 table that contains the results of a query, along with the query’s definition. Because the selection, joining, and aggregation have already been performed and the results stored in the MQT, great efficiencies can be gained if the optimizer uses this table for implementation.

� Index Only Access

The database optimizer can use Index Only Access if all of the columns specified in the SQL statement are represented in the index as key columns. Because all of the columns that are necessary to satisfy the request are present in the index, the database engine does not have to perform random access to the table to retrieve this data. The elimination of this additional I/O operation can result in significant improvements in query response times.

Database performance analysis and tuning are rather broad topics that are briefly discussed in 18.4, “DB2 for i optimization” on page 465. For a more extensive discussion about this subject refer to OnDemand SQL Performance Analysis Simplified on DB2 for i5/OS in V5R4, SG24-7326.

For this exercise, feedback from the optimizer (obtained by locating the statement in the SQE plan cache and launching Visual Explain) suggests the creation of the indexes shown in Example 18-6.

Example 18-6 Indexes created for the case study

CREATE INDEX STAR1G.CUST_DIM_CUSTKEY_CUSTOMER ON STAR1G.CUST_DIM ( CUSTKEY ASC , CUSTOMER ASC ) PAGESIZE( 64 ) ;

CREATE ENCODED VECTOR INDEX STAR1G.ITEM_FACT_CUSTKEY_EVI

ON STAR1G.ITEM_FACT ( CUSTKEY ASC ) WITH 65355 DISTINCT VALUES ;

CREATE INDEX STAR1G.ITEM_FACT_CUSTKEY_SHIPDATE


ON STAR1G.ITEM_FACT ( CUSTKEY ASC , SHIPDATE ASC ) PAGESIZE( 64 ) ;

CREATE ENCODED VECTOR INDEX STAR1G.ITEM_FACT_SHIPDATE_EVI

ON STAR1G.ITEM_FACT ( SHIPDATE ASC ) WITH 65355 DISTINCT VALUES ;

CREATE INDEX STAR1G.TIME_DIM_YEAR_MONTH

ON STAR1G.TIME_DIM ( "YEAR" ASC , "MONTH" ASC ) PAGESIZE( 64 ) ;

These indexes are created and the report is run again. Simple benchmark testing reveals modest improvements to the runtime after these indexes are created.

18.6 Performance benchmark

A performance benchmark was conducted to help determine DB2 Web Query runtime performance expectations relative to the equivalent Query/400 objects and SQL statements.

18.6.1 Objectives

The benchmark had the following objectives:

� Measure the overhead and resource usage of using the DB2 Web Query product to execute existing Query/400 reports.

� Measure the overhead and resource usage of running DB2 Web Query reports versus equivalent SQL statements.

18.6.2 Scenarios

The benchmark test bucket included six scenarios, each with a set of eight different queries or statements. Each query was run with 10 different sets of host variable values to measure variances in selectivity and cardinality. We measured the following scenarios of queries:

� Query/400 *QRYDFN objects (using the i5/OS RUNQRY command)� DB2 Web Query running the *QRYDFN objects� Direct SQL statements� DB2 Web Query reports using the DB2 CLI adapter� Direct SQL statements with all full open and re-optimization� DB2 Web Query reports using the DB2 CLI adapter with all full open and re-optimization

For each measurement, we captured the following data:

� Total execution time for a given number of loops of the executed queries and reports

� Performance monitor data

� Task-profile trace, also known as TRPOF

This is a sample-based trace that queries the processor, at user-defined intervals, to gather data on what is currently running on the processor (or processors).


18.6.3 Database and system configuration

For all of the benchmark measurements, a sample database with approximately 1 GB of data was used.

The measurements were done on a Model 515 System i environment with one or two processors, 7.5 GB of memory, and six disk arms. After running sets of measurements on the system, it was determined that one processor was a better match for the amount of memory and number of disk arms on the system. All measurements reported were done with a one-processor configuration.

18.6.4 Metrics

The measurement data was summarized into four key metrics:

� Minimum average response time per query� Maximum throughput� CPU usage� Memory usage

Minimum average response time per queryThe metric for minimum average response time shows the average response time per query for a single user. The results of this metric are shown in Figure 18-29. The average response time (sec/query) is computed as the inverse of the measured throughput (queries/sec) for a single user running back-to-back queries with no think time.

Figure 18-29 Minimum average response time chart

Figure 18-29 shows that there is a moderate response time increase for *QRYDFN objects that are run through DB2 Web Query compared to *QRYDFN run through Query/400. Some response time increase is expected when running from a remote client. As expected, the direct SQL statements have the fastest response time. The response time of the DB2 Web Query reports, although longer than the direct SQL statements, is significantly faster than the response time of the *QRYDFN objects. This is primarily due to the efficiencies of the SQL generated by the DB2 Web Query running through SQE. Because it is an SQL CLI application that runs in server mode, each server job is recycled after every DB2 Web Query request. This means that all queries are ad hoc in nature and do incur full opens. However, the DB2 Web Query response time is only slightly increased due to this. This is the case due


to server jobs being recycled after each DB2 Web Query report. The extra overhead of more full opens is incurred in the base DB2 Web Query response time numbers as well.

Maximum throughputThe objective of measuring maximum throughput is to show the maximum number of queries per second that ran before reaching a system bottleneck, such as processor or disk utilization. See Figure 18-30. This limit is measured by increasing the number of users who are running queries until no additional throughput is gained.

Figure 18-30 Maximum throughput chart

The maximum throughput for *QRYDFN objects that run through the Web Query interface is almost equivalent to the maximum throughput of running the *QRYDFN objects through Query/400. As expected, the executed SQL statements have the greatest throughput. DB2 Web Query introduces additional overhead compared to SQL. However, the maximum throughput for the DB2 Web Query reports is much greater than the throughput of the DB2 Web Query *QRYDFN runs. This is due to the efficiencies of the SQL generated by the Web Query product running through SQE. With all queries incurring full open and optimization, more like ad hoc queries, the Web Query maximum throughput is only reduced slightly. This is the case due to server jobs being recycled after each Web Query report. Therefore, the extra overhead of more full opens occurs in the base Web Query throughput numbers as well.


Resource usage: CPUThe chart of CPU resource usage in Figure 18-31 shows the amount of CPU resource used per query on average. The CPU utilization is measured when the system was running at maximum throughput. The CPU usage is then calculated as the CPU utilization divided by the queries per second at the maximum throughput point.

Figure 18-31 CPU usage chart

Figure 18-32 on page 492 shows a small increase in CPU resource used when *QRYDFN objects are run through the Web Query interface compared to the CPU used by *QRYDFN objects run through Query/400. The chart also shows the dramatic reduction in CPU used by Web Query reports and SQL compared to the *QRYDFN objects. This is due to the efficiencies of SQL running in SQE. The Web Query reports use more CPU than the equivalent plain SQL.

Resource usage: memoryThe chart of memory resource usage shows the minimum amount of base pool memory needed to be able to maintain the corresponding maximum throughput rates shown in the maximum throughput chart (Figure 18-32 on page 492). The memory requirement is determined by collecting a memory curve. Throughput for a fixed number of users is measured at various base pool sizes. The smallest memory size measured with the high level of throughput is the memory requirement point. DB2 Web Query running *QRYDFN objects compared to *QRYDFN objects run through Query/400 require more memory. This is expected due to the additional server jobs used by DB2 Web Query. As expected, the plain SQL queries require the least amount of memory. DB2 Web Query reports, running at a higher throughput rate, require about the same amount of memory as the *QRYDFN objects run through Query/400.


Figure 18-32 Memory usage chart

Figure 18-33 lists the data used in the graphs in this section.

Figure 18-33 Benchmark results table

18.6.5 Conclusions

We used the results of the benchmark to derive the following conclusions:

� Comparisons of the DB2 Web Query *QRYDFN versus the Query/400 *QRYDFN show an increased response time. This result is expected when running to a client application as is the case with DB2 Web Query. The server CPU used is 9% more, and more memory is required.

� Comparisons of DB2 Web Query (using DB2 CLI adapter) reports to Query/400 *QRYDFN are positive. Even with running to a client, the DB2 Web Query reports run faster, use much less CPU, and require about the same amount of memory. This can primarily be attributed to the DB2 CLI adapter generating SQL and using the new SQL Query Engine (SQE).

� Comparisons of Web Query to SQL show that DB2 Web Query has longer response times, which again is expected when running to a client, and uses more resources. The CPU used by Web Query is two to four times the CPU used when running SQL, depending on whether the full open re-optimization was forced every time. Note that Web Query recycles the server jobs for every query.


� If you are using DB2 Web Query to modernize Query/400 queries (by creating new reports), there is little additional overhead.

� If you are creating new reports, always keep in mind that SQL is being generated. Therefore, an understanding of SQL performance basics is vital.



Chapter 19. Frequently asked questions

In this chapter, we list frequently asked questions (FAQs) regarding DB2 Web Query. We have organized the questions into the following categories:

� “General announcement or product information questions” on page 496� “Installation and setup questions” on page 500� “Security-related questions” on page 501� “Named-user question” on page 502� “Metadata questions” on page 502� “Query/400 migration questions” on page 506� “Report development questions” on page 507� “Excel spreadsheet integration questions” on page 516� “Add-on product questions” on page 518� “Save and restore questions” on page 522� “Education questions” on page 524

19


19.1 General announcement or product information questions

In this section we address general questions regarding the announcement and product information.

What was announced?IBM delivered a new Web-based query and report-writing product that offers enhanced capabilities over the IBM Query for iSeries (also commonly known as Query/400) product (5722-QU1). The new product, IBM DB2 Web Query for System i (5733-QU2), provides several easy-to-use tools for building business intelligence solutions, including reporting and graphing assistant components, a WYSIWYG report painter, and the optional Developer Workbench for creating more customized reports.

You can extend DB2 Web Query into multidimensional analysis with the optional online analytical processing (OLAP) module or provide reports for users on the go with the Active Reports option. You can easily modernize existing Query for iSeries definitions through an import function and then enhance them with the Web-based tools.

What are some of the capabilities of this product?DB2 Web Query provides capabilities to query or build reports against data that is stored in DB2 for i5/OS and SQL Server databases through the latest browser-based user interface technologies. You can build new reports with ease through the Power Painter, Report Assistant, and Graph Assistant components. You can also simplify the management of reports by leveraging parameterized reporting. In addition, you can deliver data to users in many different formats, including spreadsheets, PDF, and HTML, or through the Java-based thin client interface browser support.

DB2 Web Query offers features to import Query/400 definitions and enhance their look and functionality with Power Painter or Graph Assistant. You can add OLAP-like slicing and dicing to the reports or view reports in disconnected mode for the user who is on the go. In addition, you can interface to all data in i5/OS through either DB2 or Open Query File native adapters that automatically identify the files to be accessed and import the metadata into DB2 Web Query.

The DB2 Web Query SQL Server data adapter extends the reach of DB2 Web Query by allowing you to develop reports and graphs that access Microsoft SQL Server 2000 or 2005 databases.

Access your DB2 for i or Microsoft SQL Server data from within Microsoft Excel 2002 or later by using the DB2 Web Query Spreadsheet Client.

The DB2 Web Query Report Broker product (5733QU3) can be added to provide automated scheduling and e-mail distribution.

The DB2 Web Query Software Development Kit product (5733QU4) can be used to integrate DB2 Web Query content (reports and graphs) into other applications.


We are happy with our Query/400 reports. Is there any reason to move to this new product?There are several reasons why you might want to consider using this new technology:

� Query/400 does not leverage the latest query optimization technology in DB2 for i5/OS, which is called SQL Query Engine (SQE). DB2 Web Query offers the ability for the queries to use the query optimization features that have been added to DB2 for i5/OS over the last few years. DB2 Web Query leverages the improved performance, automation, and monitoring capabilities of SQE.

� The parameterized reporting feature of this new product can substantially reduce the number of reports that must be maintained individually, reducing the backlog of report writing requests.

� Today’s requests for information demand that the data be delivered in many different formats and on a request, scheduled, or alert basis. Information must be provided via easy-to-interpret graphical representations, dashboards, or scorecards, or dumped into spreadsheets. Query/400 is limited in its ability to meet these demands.

Why a Web-based query and report writing function? Is a Windows-based solution not more robust?The product is based on the latest Web 2.0 and AJAX Web technologies. It allows you the functionality and usability that is usually associated with a Windows environment, but is now available to browser-based applications.

The zero footprint solution reduces complexity and costs. It also allows any enterprise browser to be leveraged as the user interface. The AJAX framework allows sophisticated report-building capabilities including modeless and modal dialogs, menus, multiple coordinated windows, partial panel updates, and more.

A Web-based solution offers the following benefits:

� Lower installation costs� Lower maintenance costs� Easy, incremental upgrades to existing applications� User administration savings� Simpler and more controlled document backup and archiving� Simpler and more controlled security and compliance administration� Software updates controlled on the server, making them available to all users concurrently

What additional features are available with DB2 Web Query?The following additional capabilities are available that leverage the foundation set by DB2 Web Query:

� Active Reports

The Internet makes vital information easily accessible to large numbers of people. But what about mobile workers who are frequently disconnected from the Web, such as sales people who spend most of their time visiting clients or service professionals who travel from customer site to customer site?

With the DB2 Web Query Active Reports feature, users like these can take the power of business intelligence with them wherever they go. By combining data and interactive controls into a single, self-contained HTML file, Active Reports deliver analytic capabilities in a completely portable and disconnected environment, with absolutely no software required. Users can manipulate reports in various sort orders, filter data by different criteria, and chart information for visual impact—anytime, anywhere.

Chapter 19. Frequently asked questions 497

� OLAP module

Business analysts know that even a slight variation in the way that they look at data often uncovers previously indiscernible trends and relationships and produce remarkable insights. If each new view requires a new report request, more time is spent building and processing reports than analyzing results and taking the appropriate action. The OLAP feature solves the data analysis issues that business analysts face by adding in-depth, built-in analytical processing to the product's robust and scalable enterprise reporting and information delivery capabilities.

� Developer Workbench

The DB2 Web Query Developer Workbench feature is an open and intuitive environment that allows for rapid development of more customized Web-based reports. It includes an HTML Composer for building compound reports or dashboards, combining multiple reports onto a single view.

The Developer Workbench’s synonym editor is used for building metadata to hide complexities of the data from users, such as decomposing date fields, applying pre-calculation and post-calculation rules, or any of the hundreds of data manipulation functions. You can use the metadata interface to define relationships in the data, such as defining the hierarchy of dimensions that automates the drill-down function of the OLAP feature.

� Run Time User Enablement

This option provides an alternative way to grant DB2 Web Query access for runtime users (those who only run reports and perform no report development activities). With the base licensing model, each of these types of users must be explicitly registered to DB2 Web Query. This means that each one consumes a user license. With Run Time User Enablement, you can instead register the group profiles that secure the DB2 Web Query domains. Any runtime user that is a member of one of those group profiles can gain access to DB2 Web Query without being explicitly registered. They are simply allowed access through the group profile license (think of it as a family pass). This can greatly reduce the number of user licenses that are required and provides an attractive option for customers who must support a large community of users that run reports. This new feature provides a solution that can be more cost effective and reduce maintenance.

� DB2 Web Query Adapter for Microsoft SQL Server

With this adapter you can extend the reach of DB2 Web Query with access to Microsoft SQL Server 2000 or 2005 databases. Prior to the availability of this adapter, the only supported DB2 Web Query data source was the IBM DB2 for i database. You can access multiple instances of SQL Server with a single DB2 Web Query Adapter and standardize on a single query and reporting solution for the enterprise.

� DB2 Web Query Spreadsheet Client

Although you can create Excel spreadsheet reports with the base DB2 Web Query product, this Excel Spreadsheet plug-in provides another level of integration by allowing

Note: In order to leverage the OLAP functionality, metadata that defines data relationships is required. This metadata is created with Developer Workbench. Therefore, we recommend that either you have a license for Developer Workbench or use another mechanism such as an ISV-supplied metadata product that will provide the metadata.


you to start within the Excel framework and pull data into a spreadsheet using DB2 Web Query reports. The following features are provided with this plug-in:

– Access your DB2 for i or Microsoft SQL Server data from within Microsoft Excel 2002 or later.

– Build spreadsheet reports that are automatically refreshed with updated data.

– Combine multiple reports from various data sources in a single worksheet.

– Create new queries while working within Excel.

– Burst data into multiple worksheets within the workbook.

– Refresh data in a server-based Excel application or template.

In addition, the following products are available to extend the base product’s functionality:

� DB2 Web Query Report Broker

DB2 Web Query Report Broker (5733-QU3) adds a new level of scheduled report distribution, enabling more report consumers to automatically receive reports in the formats that they most prefer. Report Broker enhances the number of output options available when reports are run in a batch mode. The GUI-based scheduler makes it easy to automate the report execution, with many options for running recurring reports. Leveraging e-mail distribution lists, the resulting output of the scheduled report can be distributed automatically. And with intelligent bursting, Report Broker lets you run a report once but distribute portions of it to users based on the first sort field in the report.

� DB2 Web Query Software Developer Kit (SDK)

The DB2 Web Query SDK (5733QU4) provides an API-like interface to allow application developers to seamlessly integrate DB2 Web Query content into other applications.

Is there any integration with the Rational tools with this product?No, there is no IBM WebSphere or Rational® integration.

Can a model 8nn system have the product QU2 installed?Any system that has a supported release of V5R4 can have the product ordered and installed.

Do I need to download data to a PC server or install a Windows server to sit between the client and the System i server?Many enterprise reporting tools on the market force you to move your data out of DB2 or require multiple servers to support various reporting functions. The IBM product is an i5/OS and thin client implementation, which simplifies the entire reporting infrastructure for System i customers. Software upgrades are simplified, reliability can be increased, network traffic is reduced, and security and auditing can be simplified.

Is there a DB2 Web Query community where questions can be answered and ideas shared?

Yes, there is. IBM hosts a developerWorks® site for DB2 Web Query. The URL is:


This Web site has resources such as an FAQ, links to the KnowledgeBase (where many tips and techniques are documented), and links to manuals. It also has a forum where you can post questions. It is not intended to be a support site, just a place where you can go to find and share ideas.



I have several ideas about how DB2 Web Query could be improved. How do I submit a new request for product enhancement?

There a couple of ways to submit New Feature Requests:

� Go to the following Web site for IBM i design change requests:


� Post a thread on the developerWorks forum Web site mentioned previously.

19.2 Installation and setup questions

In this section we answer questions regarding the installation and setup of DB2 Web Query.

I noticed that DB2 Web Query is using port 11331 for HTTP requests. What if I am already using this port for something else? Is there any way to change it?DB2 Web Query demands the exclusive use of ports 11331 through 11339. It is possible to change the port. However, if the reason why you want to change the port is due to port number conflicts with another application, we strongly recommend that you change the other application to use a different port outside of that range. If that change is not possible, IBM can provide documentation about how to change the ports used by DB2 Web Query on a case-by-case basis. However, doing so can limit the ability of IBM to provide support for DB2 Web Query. If this is your only option, contact IBM support for more details.

When I access the DB2 Web Query Web console, I only see a limited number of options. What happened to the other options?If you sign into the DB2 Web Query Web console (http://systemname:11331/webquery_html/wfconsole.htm) and only see limited configuration options, you are probably not signed in as the user profile QWEBQRYADM. Only this profile is able to see and use all of the Web console configuration options.

Is the server-based processing performed by the WebSphere Application Server or something that requires less overhead?A lighter weight integrated application serving environment is used, one with more specific and limited functionality. The product does not require any WebSphere Application Server instances to be running.

How are the DB2 Web Query domains established?Only an administrative class user can create new domains. Such a user must be a member of the group profile MRADMIN. Domain creation is a manual process that can only be performed by members of this group profile.




Can I configure DB2 Web Query to start automatically after an IPL?Yes, you can. However, it is important that the STRWEBQRY command always be run in a job with user profile QWEBQRYADM. By default, the system startup program QSTRUP runs with user profile QPGMR. To make sure that QSTRUP can start DB2 Web Query properly:

1. Enter the following command and add user QPGMR with object authority *USE:

EDTOBJAUT OBJ(QWEBQRYADM) OBJTYPE(*USRPRF)

2. In the CL program QSTRUP, add the following line to start DB2 Web Query:

SBMJOB CMD(QWEBQRY76/STRWEBQRY) USER(QWEBQRYADM)

19.3 Security-related questions

In this section we address questions regarding security.

Given that this is browser-based access, how is security established for users?First, users must log into DB2 Web Query using their i5/OS user profiles and passwords. If a user has been registered as a named user, access is allowed to the DB2 Web Query launch page.

From the launch page, a user is allowed to work with reports within a DB2 Web Query domain. Each domain is associated with two group profiles:

� One for report developers � One for report users

User profiles are then added to the appropriate group profile. If a user profile is a member of the report developer group profile associated with the domain, that user can create, edit, and run reports within that domain. Similarly, user profiles that are members of the report user group profile can (only) run all reports within the associated domain. The developer class named users are members of a group user profile name prefixed by MD, and user class named users are members of a group user profile name that is prefixed by MU. For example, if your domain is named SALESREP, the developer group profile is named MDSALESREP, and the user-level group profile is MUSALESREP.

In addition, when the report is executing, normal i5/OS object-level security is enforced. Therefore, if the user who is running the query does not have the appropriate authority to the underlying database object, the query execution fails accordingly.

Can my DB2 Web Query reports run with adopted authority?Yes. If you need the ability to run with adopted authority, you must register an existing program (one with adopted authority) as a stored procedure. You then create a synonym against that stored procedure. In order for DB2 Web Query to receive data back and create a report against that data, the program or stored procedure (or one in the subsequent call stack) must return at least one result set.

Attention: TCP must be active before you enter the STRWEBQRY command.


My user profiles are already members of a group profile. Since this user profile parameter (GRPPRF) is already specified, how can domain authority be established?Use the Supplemental Group (SUPGRPPRF) parameter of the CRTUSRPRF/CHGUSRPRF command. This parameter accepts multiple values and can also be used to establish the association of a user with a domain.

Can a more granular level of security be established, for example, to limit a report for a specific user?From the perspective of which reports are displayed to the user on the DB2 Web Query launch page, the answer is no. The domain level is the lowest level of security and determines which reports are displayed to a particular user. However, object-level security that is implemented in the IBM i environment is honored. This means that users might see a report. However, if they are not authorized to the underlying database objects used by the report, the report execution will fail.

Is sign-on to the product available via LDAP or Kerberos?No, there is currently no support for single sign-on environments such as Lightweight Directory Access Protocol (LDAP) and Kerberos.

Is auditing available for running a DB2 Web Query report?DB2 Web Query does not have an auditing tool, but DB2 for i5/OS and i5/OS have tools such as the use of stored procedures for which specific logging can be done, the database open exit program, the SQL call-level interface (CLI) exit program, and object journaling.

19.4 Named-user question

In this section we provide answers to questions regarding named users.

How are named users managed, established, and removed?The DB2 Web Query product provides programs that are interfaces to the licensing APIs to both add and remove a user. For more details on this subject refer to 3.3, “Registering named users” on page 29.

19.5 Metadata questions

In this section we address questions regarding metadata.

If there is a known join relationship that is not defined to the database using DB2 for i5/OS referential integrity features, is there a way to define such a relationship in the metadata?Yes, you can do this by creating synonyms from the Developer Workbench toolset. Refer to 12.1.4, “Joining tables” on page 364, which provides an example of how to define this relationship.

Alternatively, to define the relationship, you can create SQL VIEWs, add the referential integrity definitions at the database level, or manually add the join specifications for the reporting.


Is there a way to automate the generation or refreshing of the metadata, for example, by using an API?No, there is neither metadata automation nor an API to build or rebuild the metadata. It must be done manually. Therefore, if you already have metadata against a table in place and that table has been altered (for example, new columns have been added), you must manually refresh the table’s metadata before the new columns can be used in your reports.

IBM and Information Builders are investigating ways that might help you keep your metadata in synch with the tables on which it is based.

The DB2 Web Query Developer Workbench tool does have an option to refresh the metadata. This updates the synonym by adding any new columns (added to the underlying table) and removing columns (deleted from the table). Any customization made to the synonym (virtual columns, OLAP dimensions, and so on) will be preserved during this process.

How do I manage my synonyms?Synonyms are stored in the integrated file system (QIBM\UserData\webquery\ibi\apps\baseapp directory) and can be managed from one of the following interfaces:

� Windows Explorer

You must first set up a mapped network drive. From this interface, you can only delete existing synonyms.

� iSeries Navigator

From this interface, you can only delete existing synonyms.

� WRKLNK command

From this interface, you can only delete existing synonyms.


� Developer Workbench

From the Developer Workbench client, you can do much more than simply deleting the synonyms. By right-clicking the selected synonym, you see the list of available options, as shown in Figure 19-1.

Figure 19-1 Manage synonyms from Developer Workbench

The following options are some of the more useful options that are available through this interface:

– Synonym Editor

The Synonym Editor provides exclusive features, such as:

• The ability to decompose date fields• An interface for defining filters, virtual fields, and business views• The ability to define appropriate dimensions for the OLAP module

– Refresh Synonyms

Refreshing a synonym enables you to update field information while preserving the original synonym title, description, usage, virtual field, and database administrator (DBA) information. The action also synchronizes the master file with the table on which the synonym is based.

– Domain-level report movement

Use the drag features to move your domains from one system to another.

Within my reports, how can I simulate a library list-like behavior when accessing the base tables and views?During the report development and testing phases, you might prefer to create your reports against tables or views in a test library, verify that the reports are correct, and then at some point change the report to point to data in a different (perhaps production) library. Typically, this is implemented easily from many System i interfaces by using and manipulating your


library list. However, by default, your synonym is based on a table or view that is selected from a specific library. Therefore, the library list behavior does not occur. Creating separate versions of the report for each data library is one approach to consider, but is likely not desirable or practical if you have many reports to create and maintain.

To obtain the library list behavior and avoid creating a separate report for each data library, you must select the One part name synonym setting, as shown in Figure 19-2.

Figure 19-2 Specifying one-part name during synonym creation

Specifying one-part name for the synonym prevents DB2 Web Query from hard coding the library name in the meta data. When the report (based on a one-part name synonym) is run, the requesting user’s library list is searched for the table or view names on which the synonym is based. This means that you must either log in as a different user profile in order to have the report access data in a different library, or use an easier technique to change the library list of the job description that is defined to the user profile.

As long as the formats of the files in the different libraries are the same, this method is possible to carry out.

For more information about this subject see the following articles:

� Making Better Use of DB2 Web Query with *LIBL

http://www.mcpressonline.com/database/db2/making-better-use-of-db2-web-query-with-libl.html

� TechTip: Simulate One-Part Names for DB2 Web Query Synonyms over Stored Procedures

http://www.mcpressonline.com/tips-techniques/database/techtip-simulate-one-part-names-for-db2-web-query-synonyms-over-stored-procedures.html

Note: From a DB2 Web Query perspective, the user’s library list is determined and controlled by the system values QSYSLIBL and QUSRLIBL as well as the job description that is defined for the user profile. Any other method of setting the library list is not recognized by DB2 Web Query. For example, if you are using the initial program (specified in the user profile) to manipulate the library list when the user signs on, this method will fail because the initial program is not executed during the DB2 Web Query session.


http://www.mcpressonline.com/database/db2/making-better-use-of-db2-web-query-with-libl.html

http://www.mcpressonline.com/tips-techniques/database/techtip-simulate-one-part-names-for-db2-web-query-synonyms-over-stored-procedures.html

Can I query DB2 for i databases, either on another partition or in another server, without requiring multiple licenses of DB2 Web Query on each of these partitions or servers?With additional adapters as add-ons to DB2 Web Query, you can build a federated query that combines data from many different back-end databases into a single DB2 Web Query report.

You can also combine data from multiple DB2 for i5/OS databases running on different servers or logical partitions (LPARs) without requiring any additional adapters since the base product ships with the DB2 for i5/OS adapter. For more information about setting up a cross-system join see 3.6.2, “Setting up a cross-system join” on page 74.

19.6 Query/400 migration questions

In this section we address questions regarding Query/500 migration.

What happens to my existing queries when I upgrade to 5733-QU2?Nothing happens to your existing queries when you upgrade to 5733-QU2. They still run and the Query/400 product is still supported.

How do I migrate Query/400 reports into DB2 Web Query?Migration of queries is accomplished via an automated facility that allows you to select the queries that you want to translate and produces the new Web Query report ready to run or to be brought into one of the new user query components for customization. For more information about migrating Query/400 reports see 17.1, “Query/400: a reliable reporting tool” on page 442.

Is there an automated way to import Query/400 objects?No. The process to import queries is a manual one.

Query/400 supported exception joins. How do I specify that type of join with DB2 Web Query?The DB2 Web Query development tools available through the Web browser interface (Report Assistant, Graph Assistant, and Power Painter) do not support the specification of left exception, right exception, or right outer join types. If you need this functionality in your report, you must take the following steps:

1. Create an SQL view with the appropriate tables and join syntax. Here is an example of creating a view with an exception join:

CREATE VIEW century/examplejoin AS ( SELECT a."StoreName", b."LineTotal" from century/stores a LEFT EXCEPTION JOIN century/orders b ON a."StoreCode" = b."StoreCode")

Attention: Do not remove the Query/400 licensed program product (LPP) 5722-QU1. This LPP is still required even after you install 5733-QU2.


Here is an example of creating a view with a right outer join:

CREATE VIEW century/examplejoin AS ( SELECT a."StoreName", b."LineTotal" from century/stores a RIGHT OUTER JOIN century/orders b ON a."StoreCode" = b."StoreCode")

2. Create a synonym against that view.

3. Base your report on the synonym of the view.

Will the imported Query/400 definition start using SQL so that the SQL Query Engine (instead of the Classic Query Engine) will be used?No. The reports based on Query Definition objects are generated from the metadata that is available from the query object itself and will continue to be run using the RUNQRY, which uses the Classic Query Engine (CQE). A new Web Query should be created to replace an existing query, to enable an SQL interface to the data. This is the only way to have the query processed by the SQE.

Will a Query/400 object that was previously imported still function as an imported report, even after the original query definition has been changed?Yes, the object will still function as an imported report as long as the definition of the original Query/400 object is not changed to remove fields or existing fields are changed to an incompatible type with those in the existing metadata.

Can an imported Query/400 query be saved with removal of reference to the existing query, effectively creating an actual Web Query report from the imported query?No. To fully detach the reference to the original query definition, a new DB2 Web Query report must be created without reference to metadata from a query definition object.

Some Query/400 definitions are scripted in a CL program so that one query produces output that will be used by the next query for input. Will that be possible with DB2 Web Query?You can accomplish the same thing, but use of the QTEMP library might be an inhibitor. The browser-initiated work runs in the QSQSRVR jobs, and there is no assurance that the QTEMP for one query will be the same as for the next query. A permanent library must be specified.

19.7 Report development questions

In this section we answer questions regarding report development.


I have my own style sheets that I want to use for my reports. How do I make them available from Report Assistant?In Report Assistant, on the Reporting options tab, you can specify a style sheet under the Apply an existing WebFocus Stylesheet field. To add your own style sheets to this list:

1. Copy your stylesheet files to the integrated file system directory \QIBM\UserData\webquery\ibi\webfocus76\basedir\import. After they are in that directory, they are available to every domain for importing.

2. To import, open the desired domain, right-click the Other Files folder, and select Import.

3. In the Select Files to Add dialog window that opens, from the list of style sheets, select the stylesheet files and click Save.

The style sheets are now available from Report Assistant.

How can I limit the number of rows that are retrieved during the report development phase?If you are developing reports that are retrieving large numbers of rows from the database, you might find it useful to restrict the number of rows that are returned and avoid waiting for all this information to be returned to the client.

To obtain this behavior:

1. Open the report.

2. Select the Report options tab.

Tip: Many sample style sheets are provided as part of the base product and can be used in your reports. They have the file extension .STY and can be found in the integrated file system directory \QIBM\UserData\webquery\ibi\webfocus76\template.

To make these style sheets available in the Report Assistant interface, copy the .STY files to the directory specified in step 1 above and follow the remaining steps.

Attention: Although custom style sheets should work in DB2 Web Query, IBM Support does not provide assistance if you should experience problems.


3. As shown in Figure 19-3, in the Content and generation pane, specify the number of records that you want retrieved.

4. Click Save.

Figure 19-3 Limiting the number of rows retrieved

Important: Do not forget to remove this setting prior to moving your report into production. Failure to do so results in a report that does not retrieve all of the rows that satisfy the selection criteria of the report.


Can DB2 Web Query handle stored procedures with input parameters?Yes, DB2 allows your stored procedures to have input parameters. However, you must specify a value for the input parameter during the synonym creation process. Although it must be specified here, this value is not stored with the synonym definition and is not passed to the procedure during execution.

When creating the report against the stored procedure, you see the input parameter listed in the list of available fields. From the Selection criteria tab, select this field, as shown in Figure 19-4.

Figure 19-4 Using a stored procedure with an input parameter

If you want the input parameter that is passed from the report to the stored procedure to be selected from a list, you must specify a different source synonym than the stored procedure.

For more information a about using stored procedures as synonyms, see the article “TechTip: Use a Stored Procedure as Your Data Source in DB2 Web Query for i” at:

http://www.mcpressonline.com/tips-techniques/database/techtip-use-a-stored-procedure-as-your-data-source-in-db2-web-query-for-i.html

How can the SQL that is produced for the report be viewed?You can view the SQL by using the Run w/SQL option. This option sends the SQL statement generated by DB2 Web Query to the browser. In addition, the i5/OS database features in iSeries Navigator, such as the SQE Plan cache and Database Monitor, can be used to determine which SQL statement was produced and submitted to the database engine.


http://www.mcpressonline.com/tips-techniques/database/techtip-use-a-stored-procedure-as-your-data-source-in-db2-web-query-for-i.html

In parameterized reports, can more than one item be selected from the list?Yes, more than one item can be selected as long as the parameter was defined to allow multiple selections. By using the standard Windows selection method, press Ctrl and click to add or remove a selected entry.

Can the currency symbol be set at the report level?Yes, you can do this. Suppose that your default currency is U.S. dollars but you want one report to show currency as Euro. In Report Assistant, go to Report Options tab, click Fonts and Settings, and select EUR from the Currency Symbol drop-down list setting. An example is shown in Figure 19-5.

Figure 19-5 Setting currency symbol in report

Is there a way to specify double-spaced printing?Yes, double-spaced printing is controlled by custom style sheets.

Can a drill-down report have further drill-downs defined?The active link for the drill-down is just another report. Many levels exist for which a report can represent another drill-down. The only limit is the existence of the report to process the link. However, if the parent report is in the output format of an Excel spreadsheet, drill down only works if the report is displayed via Excel embedded in the browser window. If you have configured your browser to launch the Excel application automatically when opening the spreadsheet report, the drill-down capability is disabled.


Can I drill down to different reports based on the value of the column? Yes, this is called conditional drill-down. For example, let us say that you have a parent report that shows the columns Country and Revenue (as a percentage of total). If the user drills down on the United States, you would like to show a detail report showing the columns Region and Revenue as US dollars. If the user drills down on Germany (or any other European country), you would like to show a detail report with Region and Revenue as Euro dollars. To set this up, you would create two separate detail reports, one that shows the currency as U.S. dollars and the other as Euros (to learn how to do this see “Can the currency symbol be set at the report level?” on page 511). In the parent report, set up Conditional Styling on the Country column, add conditions to check for Country EQ United States and Country NE United States, attach them, and define drill downs for each of these conditions. Each drill-down would execute the appropriate detail report (procedure). This overall design is shown in Figure 19-6.

Figure 19-6 Setting up conditional drill-down

Can OLAP Reports contain drill-downs to other reports?Yes, they can, but you must be careful. If you have dimension or measure columns in your OLAP report and you define an explicit drill-down to link to another report, you will override the dimension/measure column’s default behavior, which is to drill-down to the next level of the dimension/measure. The best practice is to include a column that is not defined as a dimension or measure and use that to link to other reports. This could even be a Define field with a text value such as Click here to link to Revenue by Region Report.


Can I create dashboards by using the Power Pointer tool? Power Painter enables you to specify multiple reports to appear on a single page. However, Developer Workbench provides an HTML Composer tool that is typically used to design a dashboard for an HTML interface such as a Web browser.

When building a dashboard, can graphics be included (for example, a company logo)?Yes, you can include graphics when building a dashboard by using the HTML Composer tool (part of Developer Workbench) or Power Painter. The dashboard is a Web page, which can have a large variety of elements placed on it for viewing.

Will the dashboard allow a periodic report, an effective automatic update?This can be accomplished by editing the HTML source (using the HTML Composer tool in Developer Workbench). Insert a META statement after the <head> statement. For example, the following statement refreshes the page every minute (60 seconds):

<META http-equiv="refresh" content="60">

Can I run a DB2 Web Query report from within a CL program?Yes, the RUNWEBQRY command is delivered with the product and provides support for spooled file and database output options. Figure 19-7 shows the format of the RUNWEBQRY command.

Figure 19-7 RUNWEBQRY command

In order to run a report using this command, you must specify the appropriate domain and folder HREFs of the desired report. To obtain this information:

1. Open a DB2 Web Query session using your Web browser.

2. Expand the tree until you see the report. Right-click the domain that contains the report and select Properties.

3. In the Properties window that opens, you see the Href value, which you specify in the DOMAIN parameter of the RUNWEBQRY command. For example, let us assume that you see the following value:

db2wbqry/db2wbqry.htm

In this case, you specify the value db2wbqry in the DOMAIN parameter.

4. Right-click the folder that contains the report and select Properties.

RUN JAVA BATCH IN WEBQUERY (RUNWEBQRY) Type choices, press Enter. DOMAIN NAME, OR HREF . . . . . . UNTITLED Character value FOLDER NAME, OR HREF . . . . . . Character value REPORT (FEX) NAME . . . . . . . OUTPUT FORMAT . . . . . . . . . WP DOC, WP OUTPUT QUEUE . . . . . . . . . . QPRINT Character value RUN WITH USER ID . . . . . . . . *CURRENT Character value


5. In the Properties window, you see the Href value. This is the value that you specify in the FOLDER parameter of the RUNWEBQRY command. If the Href has a leading number character (#), do not include this in the parameter value. For example, let us assume that you see the following value:

#visiblea56gb

In this case, you specify the value visiblea56gb in the FOLDER parameter.

6. Right-click the report and select Properties.

You see the file name value in the displayed Properties window, for example:

app/newReport.fex

Excluding the leading app/ and trailing .fex characters, this is the value that you specify in the REPORT (FEX) NAME parameter of the RUNWEBQRY command. Therefore, in the case of the above example, the value specified is newReport.

Putting it all together and using the example values that we provided, your command looks like the example shown in Figure 19-8.

Figure 19-8 RUNWEBQRY command with values specified

When I prompt (F4) the RUNWEBQRY command, I do not see “Database file” as an option for output format. I thought this was one of the supported output formats.The RUNWEBQRY CL command does support output to a database file. This output option must be defined in the report itself. If you have Database file specified in the DB2 Web Query report definition, this setting is always honored in the RUNWEBQRY command, even if you specify a target output queue in the command’s OUTQ parameter. Any other output format specified in the report definition results in the report output being sent to a spooled file when the CL command is invoked.

Do I have to be registered as a named user before I can use the RUNWEBQRY command? Yes, use of the RUNWEBQRY command requires the submitting user to be registered as a DB2 Web Query named user. However, if you are not a named user and you have sufficient authority to submit a job on behalf of another user profile, you can specify a valid named user in the USER parameter of the RUNWEBQRY command. When you do this, the batch jobs submitted for this request run under the user profile that you specified. If this user profile is a valid DB2 Web Query named user, the request is allowed to continue.

RUN JAVA BATCH IN WEBQUERY (RUNWEBQRY) Type choices, press Enter. DOMAIN NAME, OR HREF . . . . . . > db2wbqry Character value FOLDER NAME, OR HREF . . . . . . > visiblea56gb Character value REPORT (FEX) NAME . . . . . . . > newReport OUTPUT FORMAT . . . . . . . . . WP DOC, WP OUTPUT QUEUE . . . . . . . . . . QPRINT Character value RUN WITH USER ID . . . . . . . . *CURRENT Character value


Can report selection be defined on an expression?In many cases, report selection can be defined on an expression by using defined fields. There are limitations, such as expressions that use aggregate functions, for example, percentage of total. In these cases, you can use an SQL view or the SQL wizard to create a report with these requirements.

How is a parameterized report designed specifically to establish the inputs?

The parameterized query defines the inputs using the HTML Composer in the Developer Workbench.

When a report is generated to HTML, I am having a difficult time getting my reports to print with the proper formatting and page breaks. Are there options to control the formatting when printing an HTML report?

HTML is the suggested output format when you want to display the results interactively in a Web browser. It is not a good option when you want to print reports. The recommended output format for printing is PDF. With PDF you can control the formatting and get the page breaks you are looking for.

I am generating reports to PDF output. The columns in the PDF document are too wide (there is much unused white space) and as a result the columns are wrapped and shown on the next page. Is there any way to condense the report so that all columns are displayed on a single page?

Yes, you can squeeze the columns together and eliminate the unused white space by using a style sheet that contains the statement SQUEEZE=ON.

You may also want to include the following statement so that the report is printed in landscape mode:

ORIENTATION=LANDSCAPE

Example 19-1shows an example of using these statements at the top of a style sheet.

Example 19-1 Stylesheet with statements to improve PDF output

UNITS=IN,PAGESIZE='Letter',LEFTMARGIN=0.500000,RIGHTMARGIN=0.500000,TOPMARGIN=0.500000,BOTTOMMARGIN=0.500000,SQUEEZE=ON,ORIENTATION=LANDSCAPE,PAGECOLOR='WHITE',$TYPE=REPORT,BORDER=1,FONT='ARIAL',SIZE=9,COLOR='BLACK',BACKCOLOR='NONE',


STYLE=NORMAL,RIGHTGAP=0.125000,TOPGAP=0.013889,BOTTOMGAP=0.027778,

On the top of each page of my report, I would like to include the current page number and total number of pages in the report. How do I specify this?This can be done by specifying the system variables TABPAGENO and TABLASTPAGE in the page header or page footer sections of the report. These variables are described below:

� TABPAGENO

Displays the current page numbers in text. Overrides the default page number position of the top left corner.

� TABLASTPAGE

Displays the last page number of the report in the heading (or footing) text.

For example, you would specify this in the page header section of the report:

Page <TABPAGENO of <TABLASTPAGE

19.8 Excel spreadsheet integration questions

For the following questions, we provide answers regarding Excel spreadsheet integration.

How do I open my Excel spreadsheet reports in Microsoft Excel instead of the Web browser? By default, whenever you open a report whose output format is defined as an Excel spreadsheet, your browser attempts to open the XLS file in the same browser session (using an XLS plug-in). If you prefer to have the spreadsheet opened in Excel:

1. Open Windows Explorer.

2. Select Tools → Folder Options.

Note: Both variables must be preceded by the < character.


3. Select the File Types tab (Figure 19-9). On this tab, complete these steps:

a. In the Registered file types list, find and select XLS (Microsoft Excel Worksheet).b. Click Advanced.

Figure 19-9 Windows folder options: Advanced

c. In the Edit File Type window (Figure 19-10), make sure that the Confirm open after download and Browse in same window options are not selected. Click OK.

Figure 19-10 Edit File Type

d. In the Folder Options window, click Close.

4. Close the Windows Explorer window and try again.


I have created a report with output to an Excel spreadsheet. Does drill down (clicking an active link) access another spreadsheet?Yes, drill down accesses another spreadsheet, but only if the spreadsheet is opened in the browser window. The drill-down is active while in a browser using an Excel plug-in to place the data from the referenced report in the browser window.

One of the report output options is “Excel with formulas.” What does that really mean?Calculations and summaries are output to the Excel spreadsheet as formulas instead of literal values. This way the recipient of that spreadsheet can do row or column manipulations (for example, delete a row), and the results of cells with formulas are automatically recalculated and updated.

Does DB2 Web Query support integration with Microsoft Excel 2007?Yes, Excel 2007 is supported.

What versions of Microsoft Excel will support the DB2 Web Query Spreadsheet Client?

You can use the DB2 Web Query Spreadsheet Client within Microsoft Excel 2002 or later.

I am using Windows Vista and cannot get drill-downs to work in my Excel Spreadsheet output. It seems that Internet Explorer launches the spreadsheet outside of the browser. This worked prior to Vista. Is it no longer supported?

This happens in both Vista (OS Level Change) and Office 2007 (Office Product Change). Unfortunately, neither will allow the embedded viewing any longer. Hence, the session cookie in iexplore.exe does not work for the full msexcel.exe product.

19.9 Add-on product questions

In this section we answer questions regarding add-on products.

The OLAP feature is enabled by defining dimensions for the database. How does DB2 Web Query get those dimensions?The dimensions must be defined in advance using the Developer Workbench.

When cascading through data in an OLAP report, is the data limited based on prior selections?Yes. For example, specifying the country as United States limits the States/Provinces list to only the states in the United States so that no data associated with Canada is available to cascade in the list.

Attention: Be aware that when you configure your browser to behave this way when opening an Excel spreadsheet, you reports lose the ability to drill down to other reports.


In an OLAP report, can the columns be sorted on demand (as they can be in Active Reports?)Yes, you can re-sort the report based on any of the displayed columns.

Does a copy of the Developer Workbench come with the base product?No. The Developer Workbench is a feature of the IBM product, but is not part of the base product.

How large is an Active Report file?The size of an Active Report file depends almost entirely on the amount of data from a file. The definitional attributes to allow actively working with the data in the browser will be relatively fixed in size in comparison to the amount of actual data included in the report.

Can an Active Report be saved with the active visualizations and any other changes made by the user?Yes. The Active Report file can be saved with the current formatting and visualizations specified by the user.

I understand that Active Reports can be sent to others via e-mail. In order to run the report, do the e-mail recipients have to be named users as well?No. Only the user who originally ran the report and generated the Active HTML output must be a named user. After the Active HTML output file is created, it can be distributed to an unlimited number of recipients, none of which must be named users (or even connected to the System i environment). The recipients open the HTML file using a browser and can work with the Active Report in the same way as the original (named) user who created the HTML output.

How can I execute reports in batch and distribute them automatically in PDF form via an e-mail distribution list? The DB2 Web Query Report Broker product (5733QU3) provides this capability. With Report Broker, you can set up schedules to run your reports in a batch mode during off-shift hours (when more system resources are available). You can distribute reports via e-mail or printer or you can have the report output saved to a folder in the report’s domain. You can also specify the report output format that you want generated and distributed. For more information about DB2 Web Query Report Broker refer to Chapter 15, “Report Broker” on page 405.

Can a report developer create reports based on manually entered or imported SQL statements?Yes, the SQL wizard feature of Developer Workbench provides an interface from which report developers can manually enter or copy and paste SQL statements, as well as point to SQL script files that exist on the integrated file system. As long as these SQL statements contain valid SELECT statements, they can be used as the basis for DB2 Web Query reports.


Why am I having trouble saving my Active Reports so that I can redistribute them?First of all, you must be using a browser that supports ActiveX technology. This means that only Internet Explorer can be used if you want to save your Active Reports to your hard drive. Firefox has no native ActiveX capability and, consequently, cannot save the HTML file.

Second, you must make sure that your Internet Explorer browser settings are configured to enable ActiveX for Internet Explorer (Versions 6.x and 7.0). To set this up correctly:

1. In the browser, from the menu bar, select Tools → Internet Options.

2. In the Internet Options window, click the Security tab.

3. On the Security tab, click Custom Level.

4. In the Security Settings window, scroll through the menu and select the Enable radio button for the following menu choices:

– Run ActiveX Controls and Plugins.– Script ActiveX Controls Marked Safe for Scripting.– Initialize and Script ActiveX Controls not Marked as Safe for Scripting.

5. Click OK to exit and save.

6. Click OK again to exit the Internet Options window.

7. Close and re-open the browser.

Active X is now enabled and you can save your Active Reports.


Does Active Reports allow you to sort on more than one column?Yes, but it is a multi-step process. If you take an action to sort by a column and that column has duplicate values, Active Reports will sort those values by the previously selected sort. Each sort action will honor the previous sort specification to resolve the ordering of duplicate values. In Figure 19-11, the user first selected to sort by Revenue in descending order. The user then sorted by Model in ascending order, followed by Product Category in ascending order. Notice that the rows with the same Product Category value (such as Organizers) are sorted first in ascending order by model, and those with the same model (VO-800) are ordered in descending order by revenue.

Figure 19-11 Sorting by multiple columns in Active Reports

If I add comments to an Active Report, will they be there the next time that I run that report?

No. When you run a report that goes to AHTML (Active Report) output format, DB2 Web Query generates an HTML file. When you display that HTML file in the browser and add comments, the comments are added to that HTML file. They are not stored anywhere on the IBM i server. You can save that HTML file or even e-mail it and it will still have the comments. But when you rerun the report, a brand new HTML file is generated and the comments do not appear in this new version of the report (but they do still exist in the original HTML file that you saved/e-mailed).

I have important business information scattered about various columns in my DB2 for i database as well as PDF documents and Excel spreadsheets. I would like to be able to perform full text-searching over


these data sources for relevant information. For example, I would like to find all PDF documents and spreadsheets that contain the search string “2007 Financial Reports.” Does DB2 Web Query provide any full-text search capabilities? If so, can it search these data sources?

DB2 Web Query does not have built-in full text search capabilities, however, it can be easily integrated with the IBM OmniFind® for DB2 for i product (5733OMF) to provide the features for which you are looking. Here are some links with more information about OmniFind and DB2 Web Query integration:

� Exploring the IBM OmniFind Text Search Server

http://www.ibm.com/partnerworld/wps/servlet/ContentHandler/whitepaper/i/omnifind/search

� OmniFind, Part I: Add Sizzle to Your SQL with OmniFind Text Search Server for DB2 for i

http://www.mcpressonline.com/database/db2/omnifind-part-i-add-sizzle-to-your-sql-with-omnifind-text-search-server-for-db2-for-i.html

� OmniFind, Part II: Integrating OmniFind Text Search Server with DB2 Web Query

http://www.mcpressonline.com/database/db2/omnifind-part-ii-integrating-omnifind-text-search-server-with-db2-web-query.html

19.10 Save and restore questions

In this section we provide guidance about save and restore.

What is the recommended save and restore process for DB2 Web Query? From a save and restore perspective, you must be concerned about the following components of DB2 Web Query:

� Synonyms (also referred to as metadata)

All synonyms are stored in the integrated file system directory QIBM\UserData\webquery\ibi\apps. If you find that you are regularly creating or refreshing metadata information, we recommend that you save this directory frequently. For example, to save all metadata into a savefile named SYNONYMS created in the QGPL library, enter the following command:

SAV DEV('/QSYS.LIB/QGPL.LIB/SYNONYMS.FILE') OBJ(('\QIBM\UserData\webquery\ibi\apps' *INCLUDE))

To restore this metadata on the target system, specify the following command:

RST DEV('/QSYS.LIB/QGPL.LIB/SYNONYMS.FILE') OBJ(('QIBM\UserData\webquery\ibi\apps' *INCLUDE 'QIBM\UserData\webquery\ibi\apps')) ALWOBJDIF(*ALL)

� Reports (also referred to as Focus Execs, FOCEXECs, and FEXs)

All reports are stored in the integrated file system directory QIBM\UserData\webquery\ibi\webfocus76\basedir\domain_name (where domain_name equals the name of the domain in which the report was created). To save all reports (distributed throughout the various domains), save the directory QIBM\UserData\webquery\ibi\webfocus76\basedir.


http://www.ibm.com/partnerworld/wps/servlet/ContentHandler/whitepaper/i/omnifind/search

http://www.mcpressonline.com/database/db2/omnifind-part-i-add-sizzle-to-your-sql-with-omnifind-text-search-server-for-db2-for-i.html

http://www.mcpressonline.com/database/db2/omnifind-part-ii-integrating-omnifind-text-search-server-with-db2-web-query.html

For example, to save all reports in all domains into a save file named ALLREPORTS created in the QGPL library, enter the following command:

SAV DEV('/QSYS.LIB/QGPL.LIB/ALLREPORTS.FILE') OBJ(('\QIBM\UserData\webquery\ibi\webfocus76\basedir' *INCLUDE))

Similar to the synonyms, we recommend that you save this directory periodically or more frequently if reports are created and updated on a regular basis.

To restore all the domains, folders, and reports to the target system, n specify the following command:

RST DEV('/QSYS.LIB/QGPL.LIB/ALLREPORTS.FILE') OBJ(('\QIBM\userdata\webquery\ibi\webfocus76\basedir' *INCLUDE '\QIBM\userdata\webquery\ibi\webfocus76\basedir')) ALWOBJDIF(*ALL)

If you want to save both synonyms and reports in one step, simply save the directory QIBM\UserData\webquery\ibi, as shown in the following example:

SAV DEV('/QSYS.LIB/QGPL.LIB/ALLSTUFF.FILE') OBJ(('\QIBM\UserData\webquery\ibi' *INCLUDE))

Can I move or deploy synonyms and reports individually?Synonyms can be copied or moved individually using either Windows Explorer (and mapped network drives) or Developer Workbench (the recommended tool for this type of activity). Both the master file (.mas extension) and the access file (.acx extension) must be moved as a pair. Keep in mind that the tables, views, and stored procedures (for example, on which the synonyms are based) must exist on the target system. Otherwise, any reports that reference the synonyms will fail to execute.

Individual reports cannot be copied or moved to another system. However, domain-level movement is supported. This means that all reports within a particular domain are moved or deployed together. Use the copy and paste or dragging capabilities in Developer Workbench to perform these tasks.

In addition, you can use Windows Explorer with mapped network drives to move domains:

1. Manually create the domain on the target system (from DB2 Web Query home page or Developer Workbench). The name of the target domain must match the name of the source domain.

2. From Windows Explorer, map a network drive for both the source and the target systems.

Note: If you are looking for the report files in the Common (untitled) Domain, you can find them in the QIBM\UserData\webquery\ibi\webfocus76\basedir\untitled\app directory.

Note: When moving or copying domains to another system, problems might occur if your reports reference (via drill downs, hyperlinks, and so on) other reports or procedures that reside in another domain.

Attention: Domain movement does not work from Windows Explorer if you skip step 1.


3. From Windows Explorer, drag the source domain directory to the target directory T:\QIBM\userdata\webquery\ibi\webfocus76\basedir (where T is the target mapped network drive letter).

4. In the Confirm Folder Replace window, you see the message This folder already contains a folder named.... Click Yes to All.

19.11 Education questions

In this section we refer you to resources for education regarding DB2 Web Query on the System i platform.

Where can I find more information about the product?You can find more information about the DB2 Web Query for IBM i home page at:

http://www.ibm.com/systems/i/software/db2/webquery/

This Web site is updated with the latest information about the product, including recent APAR information, new announcements, and downloadable demonstrations. It also includes links to find more information about add-on components available from Information Builders. In addition, if you are interested in business intelligence solutions on the System i platform, you can find links that provide more information about this subject, including success stories from customers who have implemented business intelligence solutions on the System i platform.

Where can I find more training for DB2 Web Query?Refer to the DB2 Web Query Web site at the following address and click the Getting Started tab:

http://www-03.ibm.com/systems/i/software/db2/webquery/index.html

IBM provides a developerWorks Space for Web Query. This space includes a wiki containing the latest information and documentation on the Web Query product. In addition, there is a highly active forum for Web Query. Use the forum to submit your questions to a wide range of Web Query users and IBM experts. You can access the Web Query Space at:


In addition, System i eLearning training is available on the Information Builder Web site at:

http://education.informationbuilders.com/edu/Systemi.html

Registrants to training have access to the site for 30 days. Following the 30-day trial, the service is available on an annual subscription basis for a nominal fee.

I have noticed that there are many articles, white papers, best practices, and general tips/techniques published for the DB2 Web Query product. Is there a centralized Web site that contains links to all of these publications?

Yes, there is. Go to this Web site:

http://www.ibm.com/developerworks/wikis/display/webquery/DB2+Web+Query+for+i+Articles


http://www.ibm.com/systems/i/software/db2/webquery/

http://www-03.ibm.com/systems/i/software/db2/webquery/index.html

http://education.informationbuilders.com/edu/Systemi.html

http://www.ibm.com/developerworks/wikis/display/webquery/DB2+Web+Query+for+i+Articles


Part 6 Appendixes

In this part we go into more detail about topics on DB2 Web Query. This part includes frequently asked questions and the following appendixes:

� Appendix A, “Metadata in the integrated file system” on page 527� Appendix B, “Date and time functionality” on page 529� Appendix C, “Processing differences between the define and compute fields” on page 579� Appendix D, “Change Management considerations” on page 581� Appendix E, “Additional material” on page 585

Part 6



Appendix A. Metadata in the integrated file system

In this appendix we provide a more detailed explanation of what is created on the System i5 environment when DB2 Web Query metadata is created.

Every time that a synonym is created in DB2 Web Query, two files are automatically created in the integrated file system that allow DB2 Web Query to read from that object. By default (that is, unless you set up custom application folders), these files are located in the directory /qibm/UserData/webquery/ibi/apps/baseapp. The two files that are created are called a master file and an access file:

� Master file: This file identifies the fields of the table or, if the object is a QRYDFN, the fields of that query’s result set. The master file has an extension of .mas. The fields are described in terms of length and data type. This file is similar to the information in a DSPFFD file, but the information is described in a way in which DB2 Web Query understands. Example 19-2 shows a master file for table QWQCENT/ORDERS.

Example 19-2 Master file for the QWQCENT/ORDERS table

Browse : /qibm/UserData/webquery/ibi/apps/baseapp/cen_orders.mas Record : 1 of 123 by 18 Column : 1 70 by 131Control : ...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8....+.************Beginning of data************** ILENAME=CEN_ORDERS, SUFFIX=DB2 , REMARKS='Cluster MFD for table QWQCENT/ORDERS based on FK/PK data', $ SEGMENT=T1_ORDERS, SEGTYPE=S0, $ FIELDNAME=ORDERNUMBER, ALIAS=ORDERNUMBER, USAGE=A5, ACTUAL=A5, TITLE='Order,Number', $ FIELDNAME=PRODUCTNUMBER, ALIAS=PRODUCTNUMBER, USAGE=A4, ACTUAL=A4, TITLE='Product,Number', $ FIELDNAME=ORDERDATE, ALIAS=ORDERDATE, USAGE=YYMD, ACTUAL=DATE, TITLE='Order,Date', $ FIELDNAME=STORECODE, ALIAS=STORECODE, USAGE=A6, ACTUAL=A6, TITLE='Store,Code', $

A


FIELDNAME=PLANTCODE, ALIAS=PLANTCODE, USAGE=A3, ACTUAL=A3, TITLE='Plant,Code', $ FIELDNAME=SALESREP, ALIAS=SALESREP, USAGE=A50, ACTUAL=A50, TITLE='Sales Rep', $

� Access file: This file identifies the object name and type on which the metadata is created. The access file has an extension of .acx. If the object is a QRYDFN, it says QIQRY. If the object type is a table, it says TABLENAME. Example 19-3 shows an access file for table QWQCENT/ORDERS.

Example 19-3 Access file for the QWQCENT/ORDERS table

Browse : /qibm/UserData/webquery/ibi/apps/baseapp/cen_orders.acx Record : 1 of 7 by 18 Column : 1 78 by 131 Control : ...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8....+...************Beginning of data************** SEGNAME=T1_ORDERS, TABLENAME="QWQCENT"/"ORDERS", CONNECTION=*LOCAL, KEYS=0, $ SEGNAME=T2_INVENTORY, TABLENAME="QWQCENT"/"INVENTORY", CONNECTION=*LOCAL, KEYFLD=PRODUCTNUMBER, IXFLD=PRODUCTNUMBER, KEYS=1, $ SEGNAME=T3_PLANT, TABLENAME="QWQCENT"/"PLANT", CONNECTION=*LOCAL, KEYFLD=PLANTCODE, IXFLD=PLANTCODE, KEYS=1, $ SEGNAME=T4_STORES, TABLENAME="QWQCENT"/"STORES", CONNECTION=*LOCAL, KEYFLD=STORECODE, IXFLD=STORECODE, KEYS=1, $ ************End of Data********************

For QRYDFN objects, there are three additional metadata files:

� .fex� .txt� .inf

Deleting metadataUnless you have the DB2 Web Query Developer Workbench tool, there is no command or provided interface in DB2 Web Query to manage and delete metadata. If you know that there are no more reports based on this object, nor will anymore be written, you can manually delete the metadata.

1. From the System i command line, enter the following command:

WRKLNK OBJ('/qibm/UserData/webquery/ibi/apps/baseapp')

2. Select option 5 for directory baseapp.

3. Browse the baseapp directory for the metadata that you want to delete. When you find it, select option 4 and press Enter to delete.

If you change the underlying table or QRYDFN, and if you recreate the metadata with the overwrite option, the master file is correctly updated. A new master file is not created. Therefore, you do not need to manually delete any metadata if you only used the overwrite option.


Appendix B. Date and time functionality

Date support is strong in DB2 Web Query. You can find most of the details in this appendix in the help text that is provided with Developer Workbench. Because the information is not in the help text for the base product, we have reproduced it here.

B


Date and time system variables

Table B-1 lists the date and time variables that are available in DB2 Web Query.

Table B-1 Date and time variables

Date format

The various date formats enable you to define a field as a date and work with it as a date. Using the date format, you can perform the following tasks:

� Define date components, such as year, quarter, month, day, and day of week, and extract them easily from the date fields.

� Sort reports into date sequence, regardless of how the date appears. For example, January sorts before April even though, without date smarts, April alphabetically comes before January.

� Do arithmetic with dates and compare the dates without resorting to special date-handling functions.

System variable Description Format or value Example (for October 07, 2009)

&DATE Returns the current date MM/DD/YY 10/07/2009

&DMY Returns the current date DDMMYY 071009

&DMYY Returns the current (four-digit year) date DDMMCCYY 07102009

&MDY Returns the current date. Useful for numerical comparisons

MMDDYY 100709

&MDYY Returns the current (four-digit year) date MMDDCCYY 10072009

&TOD Returns the current time that the query was executed HH.MM.SS 15.50.07

&YMD Returns the current date YYMMDD 091007

&YYMD Returns the current (four-digit year) date CCYYMMDD 20091007

&DATEWtr Returns the full name of the day of the week Name of day of week

Wednesday

&DATEMtrDYY Returns the name of the month followed by the day and the four digit year

Name of month DD, YYYY

October 7, 2009

&DATEWtr, &DATEMtrDYY

Returns the full name of the day of the week, followed by the name of the month, followed by the day and the four-digit year

Name of day of week, Name of month DD, YYYY

Wednesday, October 7, 2009


Date format display options

The date format does not specify type or length. Instead, it specifies date component options (D, W, M, Q, Y, and YY) and display options. These options are shown in Table B-2.

Table B-2 Date format options

Display option Meaning Effect

D Day Displays a value from 1 to 31 for the day.

M Month Displays a value from 1 to 12 for the month.

Y Year Displays a 2-digit year.

YY Four-digit year Displays a 2-digit year.

T Translate month When used with M in a date (MT or TM), the 3-letter abbreviation for the month in uppercase is displayed.

t Translate month When used with M in a date (Mt or tM), the 3-letter abbreviation for the month is displayed, capitalizing only the first letter of the month or day.

TR Translate month or day TR is like T, but displays the full name in uppercase.

tr Translate month or day tr is like t, but displays the full name in mixed case.

Q Quarter Displays the quarter Q1–Q4.

W Day of week On its own, W displays the number of the day of the week (1–7, Mon=1). Used in combination with other date options, W displays a 3-letter abbreviation of the day of the week in uppercase.

w Day of week Functions as uppercase W (described previously), except that the first letter is uppercase and the following letters are lowercase.

WR Day of week Functions the same as uppercase W (described above), except that the entire day name is displayed instead of an abbreviation.

wr Day of week Functions the same as lowercase w (described above), except that the entire day name is displayed instead of an abbreviation.

JUL Julian format Displays date in Julian format.

YYJUL Julian format Displays a Julian format date in the format YYYYDDD. The 7-digit format displays the 4-digit year and the number of days counting from January 1. For example, January 3, 2001 in Julian format is 2001003.

Appendix B. Date and time functionality 531

Table B-3 shows samples of output for various date formatting options.

Table B-3 Sample output for date formatting options

Controlling the date separator

You can control the date separators when the date is displayed. In basic date format, such as YMD and MDYY, the date components are displayed separated by a slash character (/). The same is true for the year-month format. The year-quarter format is displayed with the year and quarter separated by a blank (for example, 94 Q3 or Q3 1994). The single component formats display just the single number or name.

The separating character can be changed to a period, a dash, or a blank, or can be eliminated entirely. Table B-4 shows the FORMAT specifications that can be used to change the separating character.

Table B-4 Date separators

Translation Display

MT JAN

Mt Jan

MTR JANUARY

Mtr January

WR MONDAY

wr Monday

Q Q1

YQ 07Q1

Format Display

YMD 93/12/24

Y.M.D 93.12.24

Y-M 93-12

YBMBD 93 12 24 (The letter B signifies blank spaces.)

Y|M|D 931224 (The concatenation symbol | eliminates the separation character.)


Using date fields

Table B-5 shows valid examples of specifying dates.

Table B-5 Examples of specifying the dates

Date fields in arithmetic expressions

The general rule for manipulating date fields in arithmetic expressions is that date fields in the same expression must specify the same date components. The date components can be specified in any order and display options are ignored. Valid date components are Y or YY, Q, M, W, and D. For example, NEWQUARTER and THISQUARTER both have FORMAT specifications of Q and the value of THISQUARTER is 2. In this case, consider the following statement:

NEWQUARTER = THISQUARTER + 3

This statement gives NEWQUARTER a value of 1 (that is, the remainder of 5 divided by 4).

The following example calculates the number of days elapsed since January 1, 1999:

YEARTODATE = ORDERDATE - 'JAN 1 1999' ;

Converting date fields

Can DB2 Web Query handle my legacy date fields?

That is a good question. Dates and times are vital business dimensions that are required in most business reports. After all, how often do you create a report against data in your database without filtering, sorting, or aggregating the data against a date-related or time-related field? For most reports, the date and time dimension is an integral piece of information.

When it comes to storing date values in their database files, many IBM i shops use legacy date data types. Legacy dates are typically defined as numeric or alphanumeric fields that contain numbers or character strings that represent the date. An example of this is a field defined as zoned decimal (8,0), which contains the value 04102008 to represent the date April 10, 2008. However, to DB2 Web Query, this field is nothing more than a decimal field. However, to DB2 Web Query, this field is nothing more than a decimal field and it is not recognized as a date data.

But getting back to the original question, the answer is that, yes, DB2 Web Query can handle your legacy date fields. This section describes how to implement two different techniques for converting legacy date formats to fields that DB2 Web Query recognizes as true date fields (also referred to as smart dates).

Situation Natural date literal

In WHERE screening WHERE MYDATE IS 'APR 25 1999'

In arithmetic expressions MYDATE - '1999 APR 25'

In computational date comparisons IF MYDATE GT '25 APR 1999'


When the tool recognizes fields as dates, it can provide additional reporting features:

� Advanced date and time manipulation, calculations, and analysis

� Report selection parameters that can be specified by invoking JavaScript calendar widgets for a more user-friendly experience

� Date decomposition to break the date into separate fields that represent the year, quarter, month, and day

All of these things enable the report developer to deliver a report that is easy to use and to provide the report formatting and information that is required.

This section focuses on date conversions. Two types of conversions are possible:

� Format conversion � Date component conversion

In format conversion, the value of a date format field can be assigned to an alphanumeric or integer field that uses date display options. The reverse conversion is also possible.

In date component conversion, a field whose format specifies one set of date components can be assigned to another field by specifying different date components. For example, the value of REPORTDATE (DMY) can be assigned to SALESDATE (Y). In this case the year is extracted from REPORTDATE. If REPORTDATE is Apr 27 99, SALESDATE is 99.

Changing the usage

Before you begin with any actual date conversion efforts, you first must determine whether date conversions in your company's DB2 Web Query environment are even necessary. You may be ahead of the curve and have already implemented true date and time fields in your DB2 for i production database. If this is indeed the case, and you simply want to display the dates in your reports differently from how they are stored in the database, all that may be necessary is changing the Usage attribute in the file's DB2 Web Query synonym. For example, perhaps you are storing the date columns in YYMD format and simply want those dates to appear in DMYY format on your reports.

In this exercise, you will convert the order date field from the YYMD format (as it is stored in the database) so that it is displayed in MDYY format on a DB2 Web Query report.

1. From your browser session, log into DB2 Web Query as a developer.

2. From your Tutorials folder, create a new report Using Report Assistant.

3. From the list of synonyms, select cen_orders as the report’s data source.

4. In the Report Assistant tool, do the following:

a. From list of available fields, drag ORDERDATE into the Sort by pane.b. Drag LINETOTAL into the Sum pane.c. Drag COSTOFGOODSSOLD into the Sum pane.

Note: YYMD is the short name used to refer to the actual YYYY/MM/DD format. Similarly, MDYY refers to the full MM/DD/YYYY format.


When you have finished the report should look like the example provided in Figure B-1.

Figure B-1 Revenue by Order Date report

5. Save the report as Revenue by Order Date.

6. Run the report. In this report (Figure B-2) you see revenue and cost of goods sold ordered and grouped by order date.

Figure B-2 Results of Revenue by Order Date report


This is a useful report, but suppose that your users really want the order date shown in MDYY format. Because the order date field in your database is defined as YYMD format, you must take additional steps to override this attribute when displaying the date field in a DB2 Web Query report. These steps involve changing the usage value of the order date field as defined in the synonym of the file this report is based on.

To update the synonym you will use DB2 Web Query Developer Workbench.

7. Open DB2 Web Query Developer Workbench and open a connection to your environment.

8. Expand Data Servers → EDASERVE → Applications → baseapp.

9. Find and right-click the cen_orders.mas synonym file and select Edit in Synonym Editor from right-click menu.

The synonym editor is opened.

10.Select the ORDERDATE field. Notice that this is a true DATE field (see the ACTUAL attribute) and its USAGE value is YYMD (which is how it is defined in the database). As shown in Figure B-3, override this attribute by selecting MDYY from the Date Order setting under USAGE.

Figure B-3 Change date order

11.The USAGE field changes to MDYY. Click the save icon to save this change.


12.Return to your DB2 Web Query browser session and click the Revenue by Order Date report again to run it.

Notice that the Order Date column is now presented in MDYY format (Figure B-4).

Figure B-4 Results of revenue by order date after changing usage

Using DB2 Web Query functions to convert to dates

Changing the usage field may be enough if your date fields are defined as true date fields in your database and all you want to do is change the month-day-year order of how the date is displayed. However, as mentioned earlier, if you are like many IBM i shops, you probably have date fields defined as a data type other than date or time stamp (because these data types were not supported by the RPG compiler until V3R1 of the operating system). Consequently, you may have date fields defined as packed decimal (8,0), which contain the value 04102008 to represent the date April 10, 2008.

In this exercise, the file used has packed decimal (8,0) date fields with this MDYY format. You use the DB2 Web Query built-in functions (BIFs) to convert these fields to virtual fields that are defined as a true date. This true date field is used as the basis for other virtual columns in other formats such as year and day of the week.

You create a report that uses these virtual fields is in a two-dimensional format:

� Sorted/grouped vertically by the year of the order � Sorted/grouped across by the name of the day of the week

The measure shown for each of these groupings will be the aggregated order amount.

Attention: You could also create these virtual fields in the synonym (rather than in the report). In fact, this is the recommended approach, but for the purpose of this exercise, the conversions are performed in the report definition.


To perform date conversions using the DB2 Web Query BIFs, follow these steps:

1. Open DB2 Web Query in a browser session and log in.

2. Create a DB2 Web Query synonym over the LEGACY_ORDER_HEADER table. Give it a prefix of cen_.

3. Create a new Report Assistant Report in the Tutorials folder.

4. From the list of displayed synonyms, select CEN_LEGACY_ORDER_HEADER as the data source, as shown in Figure B-5.

Figure B-5 Select synonym

d. In Report Assistant, create a New define field by clicking the down arrow by the calculator icon and selecting New define field, as shown in Figure B-6.

Figure B-6 Create new define field


To convert the packed decimal fields to dates, use the DATECVT function. This function converts the field value of any standard date format or legacy date format into a new date, in either the desired standard date format or the legacy date format. These are the parameters for this function:

– date is the input legacy field to be converted.

– in_format is the format of the input legacy date (for example, P8MDYY, I8MDYY, I6YMD, and A8MDYY).

– output_format is the output date format (for example, YYMD, YQ, M, DMY, and JUL).

5. From the Define Field Creator window, specify the following, then click OK:

– Field: OrderDate (This is the new virtual column name.)– Format: MDYY (This is the output date format of the new virtual column.) – Expression: DATECVT( ORDDAT, 'P8MDYY', 'MDYY' )

An example is provided in Figure B-7.

Figure B-7 Define field for ORDERDATE

6. Create another define field to display just the year of the OrderDate column. Specify the following attributes, then click OK:

– Field: OrderYear– Format: YY– Expression: OrderDate

Note: ORDDAT is a Packed Decimal (8,0) field. If you inspect the DB2 Web Query synonym for the this field, you will notice that it is defined as P9 (rather than P8). This is normal. The extra digit is used to store the decimal point. For the purposes of date conversion, always ignore extra digits when specifying the value of the input format parameter. In this case the value should be P8MDYY.



Figure B-8 Define field for ORDERYEAR

7. Create another define field to display the day of the week (MON, TUE, and so on) of the OrderDate column. Specify the following attributes, then click OK:

– Field: OrderDayOfWeek– Format: WT– Expression: OrderDate


Figure B-9 Define field for ORDERDAYOFWEEK


8. Finish the report by performing the following:

a. Drag the new OrderYear field into the Sort by pane.

b. Drag the OrderDayOfWeek field into the Sort across pane.

c. Drag the ORDAMT field into the Sum pane and select it. Click the Show field options icon for this field.

d. Add comma inclusion and floating currency formatting to the ORDAMT field by adding CM to the end of the Format in report as setting.

e. When finished, the report definition should look like the example provided in Figure B-10.

Figure B-10 Report using Define fields for date conversion

Attention: A full list of date display formats can be found in “Date format display options” on page 531.


9. Run the report. It should look like the example displayed in Figure B-11.

Figure B-11 Results of report that uses define fields for date conversion

10.Save your report as Date conversion using Web Query functions.

11.Press the Quit icon to exit Report Assistant.

Using date conversion table to convert to dates

Also referred to as a calendar table, a date conversion table is simply a DB2 for i table that contains one row for each individual day within a specified date range. Each row is made up of columns that represent the same date value in various ways (for example, the day of the week). Your reporting and business intelligence requirements will dictate how many date value representations you add to your conversion table. For example, a date conversion table could include the following columns:

� Julian date� Date (a true DB2 date field)� Fiscal year� Fiscal quarter� Day of the week (Monday, Tuesday, and so on)� Month of the year (January, February, and so on)� Season (spring, summer, autumn, winter)� Same day (of the week) last year� Week ending date� Week of the year� Super Bowl Sunday flag (Y or N)� Day before a holiday flag (Y or N)� Day after a holiday flag (Y or N)� Full moon flag (Y or N)� And so on

In order for this technique to work, the date conversion table must have a column that represents the date in the same format as the legacy file. You then define an inner join from the legacy file to the date conversion table using the legacy date fields as the join columns. This can be done with any of the following techniques:

� Implementing Referential Integrity (setting up Primary and Foreign Keys)� Creating an SQL view with syntax to join your legacy files to the date conversion table� Defining the join in the DB2 Web Query synonym� Defining the join in each DB2 Web Query reports/graphs

When the report is run, DB2 Web Query uses the chosen join definition method to generate the SQL syntax necessary to join the legacy file and the date conversion table. For each row returned in the legacy file, the matching row (for that date) of the date conversion table is also returned, providing the report with all the various columns representing that particular date.


The result is a very efficient date conversion implementation and a faster-running report. Figure B-12 illustrates how the join to the date conversion table works.

Figure B-12 Joining files to date conversion table

With this technique, each date format (column) in the date conversion table is available to the DB2 Web Query development tools and therefore easily can be included in any report. This gives the report developer the ability to effortlessly do some interesting customized analysis. For example:

� What are the profit margins on days before and after holidays?

� How many bags of corn chips are sold the week before the Super Bowl?

� What is the rate of product returns on the day after Christmas as compared to any other day of the year?

� Are more galoshes sold in the spring or the fall?

� How many boxes of diapers are sold on days when there is a full moon?

The usefulness of a date conversion table goes well beyond DB2 Web Query. It can be implemented in any application or tool that has access to DB2 for i. If you have RPG programs, you can join to this table (using either embedded SQL or native Record Level Access operations such as CHAIN) to perform quick and easy date conversions. It can even be used in your Query/400 reports.

Implementing the date conversion method is relatively simple and can be performed in the following four steps:

1. Create the date conversion table.2. Populate the date conversion table.3. Add join segment to the synonym.4. Create reports.


Creating the date conversion tableA date conversion table named DATE_CONV is included in the QWQCENT library (which can be downloaded from “Locating the Web material” on page 585.) Example B-1 provides the SQL statement to create the table.

Example: B-1 Statement to create the date conversion table

CREATE TABLE DATE_CONV ( DC_DATE DATE DEFAULT NULL , DC_JDE_JULIAN_DATE FOR COLUMN DC_JDE_JUL DECIMAL(6, 0) DEFAULT NULL , DC_MDYY_DEC FOR COLUMN DC_MDYY_P DECIMAL(8, 0) DEFAULT NULL , DC_MDYY_ZONED FOR COLUMN DC_MDYY_Z NUMERIC(8, 0) DEFAULT NULL , DC_MDYY_CHAR FOR COLUMN DC_MDYY_C CHAR(8) CCSID 37 DEFAULT NULL , DC_YYMD_DEC FOR COLUMN DC_YYMD_P DECIMAL(8, 0) DEFAULT NULL , DC_YYMD_ZONED FOR COLUMN DC_YYMD_Z NUMERIC(8, 0) DEFAULT NULL , DC_YYMD_CHAR FOR COLUMN DC_YYMD_C CHAR(8) CCSID 37 DEFAULT NULL , DC_CC_CHAR CHAR(2) CCSID 37 DEFAULT NULL , DC_YY_CHAR CHAR(2) CCSID 37 DEFAULT NULL , DC_MM_CHAR CHAR(2) CCSID 37 DEFAULT NULL , DC_DD_CHAR CHAR(2) CCSID 37 DEFAULT NULL , DC_YEAR INTEGER DEFAULT NULL , DC_DOW INTEGER DEFAULT NULL , DC_DOY INTEGER DEFAULT NULL , DC_WOY INTEGER DEFAULT NULL , DC_QOY INTEGER DEFAULT NULL , DC_CC NUMERIC(2, 0) DEFAULT NULL , DC_YY NUMERIC(2, 0) DEFAULT NULL , DC_MM NUMERIC(2, 0) DEFAULT NULL , DC_DD NUMERIC(2, 0) DEFAULT NULL , DC_DAY_NAME FOR COLUMN DC_DAY_NAM CHAR(9) CCSID 37 DEFAULT NULL , DC_QUARTER_NAME FOR COLUMN DC_QTR_NAM CHAR(6) CCSID 37 DEFAULT NULL , DC_WEEKEND CHAR(1) CCSID 37 DEFAULT NULL , DC_SEASON CHAR(6) CCSID 37 DEFAULT NULL , DC_FISCAL_YEAR FOR COLUMN DC_FIS_YR INTEGER DEFAULT NULL , DC_FISCAL_QUARTER FOR COLUMN DC_FIS_QTR INTEGER DEFAULT NULL , DC_MONTH_NAME FOR COLUMN DC_MO_NM CHAR(9) CCSID 37 DEFAULT NULL , DC_MONTH_ABRV FOR COLUMN DC_MO_ABV CHAR(3) CCSID 37 DEFAULT NULL , DC_JULIAN NUMERIC(7, 0) DEFAULT NULL , DC_CYYMMDD DECIMAL(7, 0) DEFAULT NULL , DC_EXCEL_DATE FOR COLUMN DC_EXCEL INTEGER DEFAULT NULL , DC_WEEK_STARTING_DATE FOR COLUMN DC_WKSTR DATE DEFAULT NULL,DC_WEEK_ENDING_DATE FOR COLUMN DC_WKEND DATE DEFAULT NULL,DC_SAME_DAY_LAST_YEAR FOR COLUMN DC_SDLY DATE DEFAULT NULL,DC_CURRENT_DAY FOR COLUMN DC_CDAY CHAR(1) CCSID 37 DEFAULT NULL,DC_CURRENT_WEEK FOR COLUMN DC_CWEEK CHAR(1) CCSID 37 DEFAULT NULL,DC_CURRENT_MONTH FOR COLUMN DC_CMONTH CHAR(1) CCSID 37 DEFAULT NULL,DC_CURRENT_QUARTER FOR COLUMN DC_CQTR CHAR(1) CCSID 37 DEFAULT NULL,DC_CURRENT_YEAR FOR COLUMN DC_CYEAR CHAR(1) CCSID 37 DEFAULT NULL,DC_CURRENT_DAY_LAST_YEAR FOR COLUMN DC_LDAY CHAR(1) CCSID 37 DEFAULT NULL,DC_CURRENT_WEEK_LAST_YEAR FOR COLUMN DC_LWEEK CHAR(1) CCSID 37 DEFAULT NULL,DC_CURRENT_MONTH_LAST_YEAR FOR COLUMN DC_LMONTH CHAR(1) CCSID 37 DEFAULT NULL,DC_CURRENT_QUARTER_LAST_YEAR FOR COLUMN DC_LQTR CHAR(1) CCSID 37 DEFAULT NULL,DC_CURRENT_YEAR_LAST_YEAR FOR COLUMN DC_LYEAR CHAR(1) CCSID 37 DEFAULT NULL);

LABEL ON COLUMN DATE_CONV (

DC_DATE TEXT IS 'Date (date format)' ,


DC_JDE_JULIAN_DATE TEXT IS 'JDE Julian Date (CYYDDD decimal)' , DC_MDYY_DEC TEXT IS 'Date (MMDDYYYY packed decimal)' , DC_MDYY_ZONED TEXT IS 'Date (MMDDYYYY zoned decimal)' , DC_MDYY_CHAR TEXT IS 'Date (MMDDYYYY character)' , DC_YYMD_DEC TEXT IS 'Date (YYYYMMDD packed decimal)' , DC_YYMD_ZONED TEXT IS 'Date (YYYYMMDD zoned decimal)' , DC_YYMD_CHAR TEXT IS 'Date (YYYYMMDD character)' , DC_CC_CHAR TEXT IS 'Century (2 characters)' , DC_YY_CHAR TEXT IS 'Year (2 characters)' , DC_MM_CHAR TEXT IS 'Month (2 characters)' , DC_DD_CHAR TEXT IS 'Day (2 characters)' , DC_YEAR TEXT IS 'Year (4 digits)' , DC_DOW TEXT IS 'Day of week (1-7)' , DC_DOY TEXT IS 'Day of year (1-366)' , DC_WOY TEXT IS 'Week of year (1-52)' , DC_QOY TEXT IS 'Quarter of year (1-4)' , DC_CC TEXT IS 'Century (2 digits)' , DC_YY TEXT IS 'Year (2 digits)' , DC_MM TEXT IS 'Month (2 digits)' , DC_DD TEXT IS 'Day (2 digits)' , DC_DAY_NAME TEXT IS 'Day Name (Monday,etc.)' , DC_QUARTER_NAME TEXT IS 'Quarter name (2008Q1)' , DC_WEEKEND TEXT IS 'Weekend Flag (Y or N)' , DC_SEASON TEXT IS 'Season (Spring, Summer, Autumn, Winter)' , DC_FISCAL_YEAR TEXT IS 'Fiscal year (4 digits)' , DC_FISCAL_QUARTER TEXT IS 'Fiscal quarter (1-4)' ,DC_MONTH_NAME TEXT IS 'Month name (January, etc)' , DC_MONTH_ABRV TEXT IS 'Month abbreviation (Jan, Feb, etc)' , DC_JULIAN TEXT IS 'Date in Julian format' , DC_CYYMMDD TEXT IS 'CYYMMDD packed C = 0 for 1900 & C = 1 for 2000' , DC_EXCEL_DATE TEXT IS 'Date in Excel format' , DC_WEEK_STARTING_DATE TEXT IS 'Week starting date (the prior Saturday)',DC_WEEK_ENDING_DATE TEXT IS 'Week ending date (the next Friday)',DC_SAME_DAY_LAST_YEAR TEXT IS 'Same day last year', DC_CURRENT_DAY TEXT IS 'Current Day (Y/N)',DC_CURRENT_WEEK TEXT IS 'Current Week (Y/N)',DC_CURRENT_MONTH TEXT IS 'Current Month (Y/N)',DC_CURRENT_QUARTER TEXT IS 'Current Quarter (Y/N)',DC_CURRENT_YEAR TEXT IS 'Current Year (Y/N)',DC_CURRENT_DAY_LAST_YEAR TEXT IS 'Current Day Last Year (Y/N)',DC_CURRENT_WEEK_LAST_YEAR TEXT IS 'Current Week Last Year (Y/N)',DC_CURRENT_MONTH_LAST_YEAR TEXT IS 'Current Month Last Year (Y/N)',DC_CURRENT_QUARTER_LAST_YEAR TEXT IS 'Current Quarter Last Year (Y/N)',DC_CURRENT_YEAR_LAST_YEAR TEXT IS 'Current Year Last Year (Y/N)') ;


Populating the date conversion tableAs mentioned previously, a pre-populated date conversion table is included in the QWQCENT database. Therefore, unless there are columns that you want to add or remove, you can simply use this version of the table. If you are interested in creating a customized version, the SQL stored procedure used to populate this table is provided in Example B-2. This stored procedure creates one row for each day on and between January 1, 1900 and December 31, 2030.

Example: B-2 Stored procedure to load the date conversion table

CREATE PROCEDURE LOAD_DATE_CONVERSION_TABLE ( ) LANGUAGE SQL BEGIN

DECLARE VAR_DATE DATE DEFAULT NULL ; DECLARE VAR_JDE_JULIAN_DATE DECIMAL ( 6 , 0 ) ; DECLARE VAR_JDE_JULIAN_DATE_CHAR CHAR ( 6 ) ; DECLARE VAR_DATE_MDYY_DEC DECIMAL ( 8 , 0 ) ; DECLARE VAR_DATE_MDYY_ZONED NUMERIC( 8 , 0 ) ; DECLARE VAR_DATE_MDYY_CHAR CHAR ( 8 ) ; DECLARE VAR_DATE_YYMD_DEC DECIMAL ( 8 , 0 ) ; DECLARE VAR_DATE_YYMD_ZONED NUMERIC( 8 , 0 ) ; DECLARE VAR_DATE_YYMD_CHAR CHAR ( 8 ) ; DECLARE VAR_CC_CHAR CHAR ( 2 ) ; DECLARE VAR_YY_CHAR CHAR ( 2 ) ; DECLARE VAR_MM_CHAR CHAR ( 2 ) ; DECLARE VAR_DD_CHAR CHAR ( 2 ) ; DECLARE VAR_YEAR INTEGER ; DECLARE VAR_DOW INTEGER ; DECLARE VAR_DOY INTEGER ; DECLARE VAR_WOY INTEGER ; DECLARE VAR_QOY INTEGER ; DECLARE VAR_CC NUMERIC ( 2 , 0 ) ; DECLARE VAR_YY NUMERIC ( 2 , 0 ) ; DECLARE VAR_MM NUMERIC ( 2 , 0 ) ; DECLARE VAR_DD NUMERIC ( 2 , 0 ) ; DECLARE VAR_DAY_NAME CHAR ( 9 ) ; DECLARE VAR_QUARTER_NAME CHAR ( 6 ) ; DECLARE VAR_WEEKEND CHAR ( 1 ) ; DECLARE VAR_SEASON CHAR ( 6 ) ; DECLARE VAR_FISCAL_YEAR INTEGER ; DECLARE VAR_FISCAL_QUARTER INTEGER ; DECLARE VAR_MONTH_NAME CHAR ( 9 ) ; DECLARE VAR_MONTH_ABRV CHAR ( 3 ) ; DECLARE VAR_JULIAN NUMERIC ( 7 , 0 ) ; DECLARE VAR_EXCEL_DATE INTEGER ; DECLARE VAR_CYYMMDD_DEC DECIMAL ( 7 , 0 ) ; DECLARE VAR_WEEK_ENDING_DATE DATE DEFAULT NULL ; DECLARE VAR_WEEK_STARTING_DATE DATE DEFAULT NULL ; DECLARE VAR_SAME_DAY_LAST_YEAR DATE DEFAULT NULL ; DECLARE VAR_CURRENT_DAY CHAR(1) ;DECLARE VAR_CURRENT_WEEK CHAR(1) ;DECLARE VAR_CURRENT_MONTH CHAR(1) ;DECLARE VAR_CURRENT_QUARTER CHAR(1) ;DECLARE VAR_CURRENT_YEAR CHAR(1) ;DECLARE VAR_CURRENT_DAY_LAST_YEAR CHAR(1) ;


DECLARE VAR_CURRENT_WEEK_LAST_YEAR CHAR(1) ;DECLARE VAR_CURRENT_MONTH_LAST_YEAR CHAR(1) ;DECLARE VAR_CURRENT_QUARTER_LAST_YEAR CHAR(1) ;DECLARE VAR_CURRENT_YEAR_LAST_YEAR CHAR(1) ;

SET VAR_DATE = '01/01/1900' ; SET VAR_CURRENT_DAY = 'N' ;SET VAR_CURRENT_WEEK = 'N' ;SET VAR_CURRENT_MONTH = 'N' ;SET VAR_CURRENT_QUARTER = 'N' ;SET VAR_CURRENT_YEAR = 'N' ;SET VAR_CURRENT_DAY_LAST_YEAR = 'N' ;SET VAR_CURRENT_WEEK_LAST_YEAR = 'N' ;SET VAR_CURRENT_MONTH_LAST_YEAR = 'N' ;SET VAR_CURRENT_QUARTER_LAST_YEAR = 'N' ;SET VAR_CURRENT_YEAR_LAST_YEAR = 'N' ;

REPEAT SET VAR_YEAR = YEAR ( VAR_DATE ) ; SET VAR_EXCEL_DATE = INT ( DAYS ( VAR_DATE ) - DAYS ( DATE ( '01/01/1900' ) ) ) + 1 ;

-- Excel incorrectly calculates Feb 29, 1900 as a leap day (when in fact it is not). -- The following accounts for that. SET VAR_EXCEL_DATE = ( CASE

WHEN VAR_EXCEL_DATE > 59 THEN VAR_EXCEL_DATE + 1 ELSE VAR_EXCEL_DATE

END ) ;

SET VAR_JDE_JULIAN_DATE = ( INT ( VAR_DATE - DATE ( '01/01/1900' ) ) / 10000 ) * 1000 + DAYOFYEAR ( VAR_DATE ) ;

SET VAR_DOW = DAYOFWEEK_ISO ( VAR_DATE ) ; SET VAR_DOY = DAYOFYEAR ( VAR_DATE ) ; SET VAR_WOY = WEEK ( VAR_DATE ) ; SET VAR_QOY = QUARTER ( VAR_DATE ) ; SET VAR_CC_CHAR = SUBSTRING ( CHAR ( YEAR ( VAR_DATE ) ) , 1 , 2 ) ; SET VAR_YY_CHAR = SUBSTRING ( CHAR ( YEAR ( VAR_DATE ) ) , 3 , 2 ) ; SET VAR_MM_CHAR = SUBSTRING(DIGITS(MONTH(VAR_DATE)),9,2) ; SET VAR_DD_CHAR = SUBSTRING(DIGITS(DAY(VAR_DATE)),9,2) ; SET VAR_CC = DECIMAL ( SUBSTRING ( CHAR ( YEAR ( VAR_DATE ) ) , 1 , 2 ) ) ; SET VAR_YY = DECIMAL ( SUBSTRING ( CHAR ( YEAR ( VAR_DATE ) ) , 3 , 2 ) ) ; SET VAR_MM = MONTH ( VAR_DATE ) ; SET VAR_DD = DAY ( VAR_DATE ) ; SET VAR_DATE_MDYY_CHAR = VAR_MM_CHAR|| VAR_DD_CHAR || VAR_CC_CHAR || VAR_YY_CHAR ; SET VAR_DATE_MDYY_DEC = DECIMAL ( VAR_DATE_MDYY_CHAR ) ; SET VAR_DATE_MDYY_ZONED = VAR_DATE_MDYY_DEC ; SET VAR_DATE_YYMD_CHAR = ( VAR_CC * 1000000 ) + ( VAR_YY * 10000 )

+ ( VAR_MM * 100 ) + VAR_DD ; SET VAR_DATE_YYMD_DEC = DECIMAL ( VAR_DATE_YYMD_CHAR ) ; SET VAR_DATE_YYMD_ZONED = VAR_DATE_YYMD_DEC ; SET VAR_CYYMMDD_DEC = ( CASE

WHEN VAR_CC = 19 THEN ( VAR_YY * 10000 ) + ( VAR_MM * 100 ) + VAR_DD


ELSE 1000000 + ( VAR_YY * 10000 ) + ( VAR_MM * 100 ) + VAR_DD END ) ;

SET VAR_DAY_NAME = ( CASE VAR_DOW

WHEN 1 THEN 'Monday'

WHEN 2 THEN 'Tuesday'

WHEN 3 THEN 'Wednesday'

WHEN 4 THEN 'Thursday'

WHEN 5 THEN 'Friday'

WHEN 6 THEN 'Saturday'

WHEN 7 THEN 'Sunday'

ELSE '' END ) ;

SET VAR_QUARTER_NAME = TRIM ( CHAR ( YEAR ( VAR_DATE ) ) ) CONCAT 'Q' CONCAT

TRIM ( CHAR ( QUARTER ( VAR_DATE ) ) ) ;

SET VAR_WEEKEND = ( CASE VAR_DOW

WHEN 1 THEN 'Y'

WHEN 7 THEN 'Y'

ELSE 'N' END ) ;

SET VAR_SEASON = ( CASE

WHEN VAR_MM < 3 OR ( VAR_MM = 3 AND VAR_DD < 21 ) THEN 'Winter'

WHEN VAR_MM < 6 OR ( VAR_MM = 6 AND VAR_DD < 21 ) THEN 'Spring'

WHEN VAR_MM < 9 OR ( VAR_MM = 9 AND VAR_DD < 21 ) THEN 'Summer'

WHEN VAR_MM < 12 OR ( VAR_MM = 12 AND VAR_DD < 21 ) THEN 'Autumn'

ELSE 'Winter' END ) ;

SET VAR_FISCAL_QUARTER = ( CASE

WHEN VAR_MM < 4 THEN 2




ELSE 1 END ) ;

SET VAR_FISCAL_YEAR = ( CASE

WHEN VAR_MM < 10 THEN YEAR ( VAR_DATE )

ELSE YEAR ( VAR_DATE ) + 1 END ) ;

SET VAR_MONTH_NAME = MONTHNAME ( VAR_DATE ) ; SET VAR_MONTH_ABRV = ( CASE VAR_MM

WHEN 1 THEN 'JAN'

WHEN 2 THEN 'FEB'

WHEN 3 THEN 'MAR'

WHEN 4 THEN 'APR'

WHEN 5 THEN 'MAY'

WHEN 6 THEN 'JUN'

WHEN 7 THEN 'JUL'

WHEN 8 THEN 'AUG'

WHEN 9 THEN 'SEP'

WHEN 10 THEN 'OCT'

WHEN 11 THEN 'NOV'

WHEN 12 THEN 'DEC'

ELSE '' END ) ;

SET VAR_JULIAN = DECIMAL ( SUBSTRING ( CHAR ( ( YEAR ( VAR_DATE ) * 1000 + DAYOFYEAR ( VAR_DATE ) ) ) , 1 , 7 ) ) ;

SET VAR_WEEK_ENDING_DATE = ( CASE VAR_DOW

WHEN 1 THEN VAR_DATE + 4 DAYS




WHEN 5 THEN VAR_DATE




ELSE NULL END ) ;

SET VAR_WEEK_STARTING_DATE = VAR_WEEK_ENDING_DATE - 6 DAYS;SET VAR_SAME_DAY_LAST_YEAR = VAR_DATE - 364 DAYS;

INSERT INTO DATE_CONV VALUES ( VAR_DATE , VAR_JDE_JULIAN_DATE , VAR_DATE_MDYY_DEC , VAR_DATE_MDYY_ZONED , VAR_DATE_MDYY_CHAR ,VAR_DATE_YYMD_DEC , VAR_DATE_YYMD_ZONED , VAR_DATE_YYMD_CHAR , VAR_CC_CHAR , VAR_YY_CHAR , VAR_MM_CHAR , VAR_DD_CHAR , VAR_YEAR , VAR_DOW , VAR_DOY , VAR_WOY , VAR_QOY , VAR_CC , VAR_YY , VAR_MM , VAR_DD , VAR_DAY_NAME , VAR_QUARTER_NAME , VAR_WEEKEND , VAR_SEASON , VAR_FISCAL_YEAR , VAR_FISCAL_QUARTER , VAR_MONTH_NAME , VAR_MONTH_ABRV , VAR_JULIAN , VAR_CYYMMDD_DEC , VAR_EXCEL_DATE , VAR_WEEK_STARTING_DATE,VAR_WEEK_ENDING_DATE,VAR_SAME_DAY_LAST_YEAR,VAR_CURRENT_DAY,VAR_CURRENT_WEEK,VAR_CURRENT_MONTH,VAR_CURRENT_QUARTER,VAR_CURRENT_YEAR,VAR_CURRENT_DAY_LAST_YEAR,VAR_CURRENT_WEEK_LAST_YEAR,VAR_CURRENT_MONTH_LAST_YEAR,VAR_CURRENT_QUARTER_LAST_YEAR,


VAR_CURRENT_YEAR_LAST_YEAR ) ; SET VAR_DATE = VAR_DATE + 1 DAY ;

UNTIL VAR_DATE > '12/31/2030'

END REPEAT ; END ;

Notice that several of the columns in the date conversion table are current flags that contain a value of ‘Y’ or ‘N’ depending on whether the condition for that flag is met. For example, the column DC_CURRENT_YEAR contains a ‘Y’ if that row represents a date whose year is equal to the current year. So if the current date is August 26, 2009, then the value for the DC_CURRENT_YEAR column would be ‘Y’ for all of the rows that represent dates for the year 2009. Because these are dynamic values, you must add a process to keep these columns in the date conversion table updated. The stored procedure example provided in Example B-3 does just that.

Example: B-3 Stored procedure to update the columns of current flags

CREATE PROCEDURE UPDATE_DATE_CONVERSION_TABLE ( ) LANGUAGE SQL BEGIN

UPDATE DATE_CONV SET DC_CURRENT_DAY = 'N' WHERE DC_CURRENT_DAY = 'Y';UPDATE DATE_CONV SET DC_CURRENT_WEEK = 'N' WHERE DC_CURRENT_WEEK = 'Y';UPDATE DATE_CONV SET DC_CURRENT_MONTH = 'N' WHERE DC_CURRENT_MONTH = 'Y';UPDATE DATE_CONV SET DC_CURRENT_QUARTER = 'N' WHERE DC_CURRENT_QUARTER = 'Y';UPDATE DATE_CONV SET DC_CURRENT_YEAR = 'N' WHERE DC_CURRENT_YEAR = 'Y';

UPDATE DATE_CONV SET DC_CURRENT_DAY_LAST_YEAR = 'N' WHERE DC_CURRENT_DAY_LAST_YEAR = 'Y';UPDATE DATE_CONV SET DC_CURRENT_WEEK_LAST_YEAR = 'N' WHERE DC_CURRENT_WEEK_LAST_YEAR = 'Y';UPDATE DATE_CONV SET DC_CURRENT_MONTH_LAST_YEAR = 'N' WHERE DC_CURRENT_MONTH_LAST_YEAR = 'Y';UPDATE DATE_CONV SET DC_CURRENT_QUARTER_LAST_YEAR = 'N'

WHERE DC_CURRENT_QUARTER_LAST_YEAR = 'Y';UPDATE DATE_CONV SET DC_CURRENT_YEAR_LAST_YEAR = 'N' WHERE DC_CURRENT_YEAR_LAST_YEAR = 'Y';UPDATE DATE_CONV SET DC_CURRENT_DAY = 'Y' WHERE DC_DATE = CURRENT DATE;UPDATE DATE_CONV SET DC_CURRENT_WEEK = 'Y' WHERE DC_DATE >=

(SELECT DC_WEEK_STARTING_DATE FROM DATE_CONV WHERE DC_DATE = CURRENT DATE) AND DC_DATE <= (SELECT DC_WEEK_ENDING_DATE FROM DATE_CONV WHERE DC_DATE = CURRENT DATE);

UPDATE DATE_CONV SET DC_CURRENT_MONTH = 'Y' WHERE DC_YEAR = YEAR(CURRENT DATE) AND DC_MM = MONTH(CURRENT DATE);

UPDATE DATE_CONV SET DC_CURRENT_QUARTER = 'Y' WHERE DC_YEAR = YEAR(CURRENT DATE) AND DC_QOY = QUARTER(CURRENT DATE);

UPDATE DATE_CONV SET DC_CURRENT_YEAR = 'Y' WHERE DC_YEAR = YEAR(CURRENT DATE);UPDATE DATE_CONV SET DC_CURRENT_DAY_LAST_YEAR = 'Y' WHERE DC_DATE = CURRENT DATE - 364 DAYS;UPDATE DATE_CONV SET DC_CURRENT_WEEK_LAST_YEAR = 'Y' WHERE DC_DATE >=

(SELECT DC_WEEK_STARTING_DATE FROM DATE_CONV WHERE DC_DATE = (CURRENT DATE - 364 DAYS)) AND DC_DATE <= (SELECT DC_WEEK_ENDING_DATE FROM DATE_CONV WHERE DC_DATE = (CURRENT DATE - 364 DAYS));

UPDATE DATE_CONV SET DC_CURRENT_MONTH_LAST_YEAR = 'Y' WHERE DC_YEAR = (YEAR(CURRENT DATE) - 1) AND DC_MM = MONTH(CURRENT DATE);

UPDATE DATE_CONV SET DC_CURRENT_QUARTER_LAST_YEAR = 'Y' WHERE DC_YEAR = (YEAR(CURRENT DATE) - 1) AND DC_QOY = QUARTER(CURRENT DATE);


UPDATE DATE_CONV SET DC_CURRENT_YEAR_LAST_YEAR = 'Y' WHERE DC_YEAR = (YEAR(CURRENT DATE) - 1);

END;

All you must do is make sure that this stored procedure runs everyday. To do this, create a job scheduler entry to call this stored procedure daily. This can be accomplished by taking the following steps:

1. Create a source file member to store an SQL statement script:

ADDPFM FILE(QGPL/QTXTSRC) MBR(UPDDATCONV)

2. Edit this source file member and add the following SQL statement to call the stored procedure:

CALL QWQCENT/UPDATE_DATE_CONVERSION_TABLE

3. Now add a job scheduler job to run the SQL script in the source file member:

ADDJOBJS JOB(UPDDATCONV) SCDCDE(*DAILY) TIME(0010) CMD(RUNSQLSTM SRCFILE(QGPL/QTXTSRC) SRCMBR(UPDDATCONV) COMMIT(*NONE) NAMING(*SYS))

This job scheduler job runs daily at 1 a.m. and calls the RUNSQLSTM command to run the script (in the specified source file member) through SQL.

Adding join segments to the synonymAs described earlier, there are several ways that the date conversion table can be joined to the legacy file. This section describes how to implement the join in the DB2 Web Query synonym. In general, it is advantageous to define the joins in the synonym (rather than individual reports and graphs) for the simple reason that this piece of logic is centralized in one location. Each report and graph that uses the synonym will be able to use the join segment (and not have to redefine it).

For this example, you will use the table in library QWQCENT named LEGACY_ORDER_HEADER (the 10-character system name is ORDHDR).

1. Create a DB2 Web Query synonym over the DATE_CONV table. Give it a a prefix of cen_.

2. Open DB2 Web Query Developer Workbench and open a connection to your environment.

3. Find the cen_legacy_order_header.mas file under Data Servers → EDASERVE → Applications → baseapp.

Attention: If you cannot find the table DATE_CONV or LEGACY_ORDER_HEADER in the QWQCENT library, you most likely do not have the latest version of this library. It can be downloaded from “Locating the Web material” on page 585.


4. Right-click this file and select Edit in Synonym Editor, as shown in Figure B-13.

Figure B-13 Edit cen_legacy_order_header

At this point add a join segment to the date conversion table.

5. Right-click the CEN_LEGAGY_ORDER_HEADER segment name and select Add → Segment From Existing Synonym, as shown in Figure B-14.

Figure B-14 Add join segment to legacy_orders_table

A list of synonyms in the BASEAPP folder is presented.


6. As demonstrated in Figure B-15, find and select the cen_date_conv synonym and click Select.

Figure B-15 Select cen_date_conv synonym

The new segment is added to the synonym. Next you must change the segment type from Multiple to Unique.

7. Select the new CEN_DATE_CONV join segment and locate the Type attribute under SEGTYPE.


8. This is a drop-down list. Click it to and change the type to Unique, as shown in Figure B-16. This instructs DB2 Web Query to rely on SQL syntax to create the join and when accessing the joined columns (allowing you to sort and select fields across multiple join segments).

Figure B-16 Change segment type to Unique


9. Define the fields that will be used to join the tables together. As shown in Figure B-17, right-click again the CEN_DATE_CONV segment and select Join Properties.

Figure B-17 Select Join Properties

10.In the Join Properties window, do the following:

a. From the list of columns in the CEN_LEGACY_ORDER_HEADER segment, select ORDDAT so that it is highlighted.

b. From the list of columns in the CEN_DATE_CONV segment, select DC_MDYY_DEC so that it is highlighted. The values in the ORDDAT are in this format, thus this is the column in the date conversion table to use as the join column.


c. Click the = icon located between the two segment lists. This action should bring the selected join columns down into the expression pane. An example is shown in Figure B-18.

Figure B-18 Define join columns

11.Click OK. To help the report developers identify what legacy date field this date conversion segment represents, rename the segment to the name of the field that it is converting. If you do not do this, the segment names to the date conversion table many be ambiguous (your report developers may not be certain of what legacy date field they represent). This is particularly true if you have multiple legacy date fields in your synonym because to convert them you must define a join segment to date_conv for each one.

Tip: If you are very meticulous (and ambitious), you could even completely remove the ambiguity by renaming each of the individual column names in the date conversion segments (for example, rename DC_YEAR to ORDDAT_YEAR). This can be done by highlighting the column and selecting Rename from the right-click menu. That is really going the extra mile, but your report developers would very much appreciate this.


12.Highlight the segment and select Rename from the right-click menu. This is shown in Figure B-19.

Figure B-19 Rename the segment


13.Specify ORDDAT as the segment name. When you are finished, your synonym will look like the example provided in Figure B-20.

Figure B-20 Synonym with new ORDDAT segment

14.Repeat step 5 on page 553 through step 13 for the SHPDAT legacy date field field. Be sure that you rename the segment SHPDAT.

15.Save the synonym.

16.Close the Edit synonym window.


Creating reports using the date conversion tableOnce the join has been defined in the synonym, the next step is to create a report over this updated synonym. Follow these steps:

1. Return to your DB2 Web Query browser session.

2. Create a new report in Tutorials using Report Assistant.

3. Select the CEN_LEGACY_ORDER_HEADER synonym as the report data source.

The Report Assistant tool is presented. Notice that all of the columns from the date conversion table now appear in the list of fields to choose from. The list is now long and cluttered. To organize it better, click the Tree icon, as shown in Figure B-21, so that the list is organized into a Tree view.

Figure B-21 Display Tree view

Tip: For performance reasons, now would be a good time to create indexes over your join columns. The DB2 optimizer will be able to use these indexes for statistics and implementation during query execution. Here are the two SQL statements for creating indexes over the LEGACY_ORDER_HEADER and DATE_CONV tables:

CREATE INDEX LEGACY_ORDER_HEADER_INDEX_00001 ON LEGACY_ORDER_HEADER (ORDDAT ASC);CREATE INDEX DATE_CONV_INDEX_00001 ON DATE_CONV (DC_MDYY_DEC ASC);


As shown in Figure B-22, taking this action groups the synonym columns under their respective segments and allows you to expand and collapse the list of columns under each segment.

Figure B-22 Example of Tree view

4. Finish the report by performing the following steps:

a. Drag the new DC_YEAR field into the Sort by pane.

b. Drag the DC_DOW field into the Sort across pane. Make it an invisible field. DC_DOW is the numeric value of the day of the week. You must sort by this field, but not by the name of the day of the week field (DC_DAY_NAME). Otherwise, the data for Friday would appear first (since it is the first day name alphabetically) and Wednesday would appear last. However, you probably do not want the numeric day of the week value to actually appear on the report, so hide this column in the report.

c. Drag the DC_DAY_OF_WEEK field into the Sort across pane.

d. Drag the ORDAMT field into the Sum pane and select it. Click the Show field options icon for this field.

e. Add comma inclusion and floating currency formatting to the ORDAMT field by adding CM to the end of the Format in report as setting.


When finished, the report definition should look like the example provided in Figure B-23.

Figure B-23 Report using date conversion table

5. Run the report. The results should look identical to those in Figure B-24.

Figure B-24 Results of report using date conversion table

Other than the fields and techniques used for date conversion, this is the same report that you created in “Using DB2 Web Query functions to convert to dates” on page 537. Compare the results of those two reports. They should be identical.


6. Save your report as Date conversion using date conversion table.

One of the advantages of the date conversion table method is that all of the columns in the table will be brought into the synonyms segment and subsequently will appear in the list of available fields in the development tools. This gives report developers the ability to easily and effortlessly include a wide variety of date formats in your reports.

One of the disadvantages is that all of the columns in the table will appear in the list of available fields in the development tools. Why is this a disadvantage? Because there may be many columns in the table and some of them may never actually be used in the reports. These columns can clutter up the list, particularly if the synonym contains many other columns.

Furthermore, and as mentioned previously, if you have multiple legacy date fields in your file and you want to convert them to date fields, you must create join segments to the date conversion table for each one. This adds even more columns to the list of fields in the development tools.

Here are some suggestions for keeping the list of available fields to a manageable size:

� Create the date conversion table with fewer columns (only the ones that your use regularly).

� Create DB2 Web Query business views over your synonyms. This allows you to create and organize a subset of columns to display in the report development tools. See “Defining joins in SQL views” on page 65 for more information about business views.

Tip: Now is an opportune time to create indexes over the join columns.


� Set the column’s Access Property to INTERNAL to hide the infrequently used columns in the synonym. This gives you the ability to preserve the columns in the date conversion table, while not showing them in the development tools. If they are needed for some reports you can simply unhide them by unchecking the INTERNAL setting. Figure B-25 provides an example of how to hide DC_MONTH_NAME so that it does not appear in the list of available columns in the report development tools.

Figure B-25 Defining a column that does not appear in list of available columns

Using SQL Views and functions to convert to dates

A third technique for performing date conversions is to leverage the power of SQL functions and reference them in SQL views. SQL functions such as DATE, YEAR, and DAYOFWEEK can be used in an SQL SELECT statement to efficiently perform the conversions. Depending on the legacy date data type and format, it may be necessary to use other functions such as DIGITS and SUBSTRING. In some cases, this may result in a SELECT statement that is somewhat lengthy. But you can hide this complexity from your report developers by creating an SQL view over this statement and then a DB2 Web Query synonym over the view.

Attention: Existing reports that reference hidden columns (those whose INTERNAL setting for ACCESS PROPERTY is selected) will continue to run. However, if you attempt to open such a report in the report development tools, the request will fail with a Field not found in master file error. In those cases, you must edit the synonym and remove (uncheck) the INTERNAL setting for ACCESS PROPERTY.


An example SQL view that uses multiple SQL functions for date conversions (over the LEGACY_ORDER_HEADER table) is provided in the QWQCENT library. This view, named ORDER_HEADER_VIEW, is shown in Example B-4.

Example: B-4 ORDER_HEADER_VIEW definition

CREATE VIEW ORDER_HEADER_VIEW AS WITH t1 (

order , cust , orderdate , shipdate , shpvia , ordsts , ordamt , totlin , invnum ) AS (SELECT order, cust,

DATE(SUBSTRING(DIGITS(orddat),5,4) || '-' || SUBSTRING(DIGITS(orddat),1,2)|| '-' || SUBSTRING(DIGITS(orddat),3,2)),

DATE(SUBSTRING(DIGITS(shpdat),5,4) || '-' || SUBSTRING(DIGITS(shpdat),1,2)|| '-' || SUBSTRING(DIGITS(shpdat),3,2)),

shpvia, ordsts, ordamt, totlin, invnumFROM legacy_order_header )

SELECT order, cust, orderdate, YEAR(orderdate) AS orderyear,DAYOFWEEK_ISO(orderdate) AS orderdow,CASE

WHEN DAYOFWEEK_ISO(orderdate) = 1 THEN 'MON'WHEN DAYOFWEEK_ISO(orderdate) = 2 THEN 'TUE'WHEN DAYOFWEEK_ISO(orderdate) = 3 THEN 'WED'WHEN DAYOFWEEK_ISO(orderdate) = 4 THEN 'THU'WHEN DAYOFWEEK_ISO(orderdate) = 5 THEN 'FRI'WHEN DAYOFWEEK_ISO(orderdate) = 6 THEN 'SAT'WHEN DAYOFWEEK_ISO(orderdate) = 7 THEN 'SUN'ELSE ''

END AS orderdayname,shipdate, shpvia, ordsts, ordamt, totlin, invnum FROM t1

The above example performs the following:

� Converts legacy date fields ORDDAT and SHPDAT into true dates and returns them in the derived columns named ORDERDATE AND SHIPDATE.

� Creates a second derived column named ORDERYEAR by referencing the derived column ORDERDATE in the SQL function YEAR. This column returns the year portion of the date.

� Creates a third derived column named ORDERDOW by referencing the derived column ORDERDATE in the SQL function DAYOFWEEK_ISO. This column returns the integer value of the day of the week.

� Creates a fourth derived column named ORDERDAYNAME by referencing the derived column ORDERDATE in the SQL function DAYOFWEEK_ISO and performing some logic in a CASE statement to return the name of the day of the week.

Notice the use of the WITH keyword to create SQL common table expressions. If you are not familiar with common table expressions, they can be thought of as temporary views that only


exist during the execution of the query. By using them, you can define a result table with a table-identifier (T1 above) that can be specified as the table name in any FROM clause of the SELECT statement. Because the example uses derived columns that reference other derived columns (ORDERDATE), a common table expression is used. It allows you to define ORDERDATE in one place and reduce the query's complexity by minimizing the amount of text, especially when ORDERDATE is referenced multiple times in the query.

To create the same type of report (as the previous examples) that uses this SQL view, take the following steps:

1. Create a DB2 Web Query synonym over the view. Specify cen_ for the metadata prefix.

2. Create a new report in Report Assistant, using the new view synonym.

a. Drag the ORDERYEAR field into the Sort by pane.

b. Drag the ORDERDOW field into the Sort across pane. Similar to the report in the previous section, make it an invisible field so that the columns are sorted by the numeric value of the day of the week rather than alphabetically by the name of the day of the week.

c. Drag the ORDERDAYNAME field into the Sort across pane.

d. Drag the ORDAMT field into the Sum pane and select it. Click the Show field options icon for this field.

e. Add comma inclusion and floating currency formatting to the ORDAMT field by adding CM to the end of the Format in report as setting.

3. When finished, the report definition should look like the example provided in Figure B-26.

Figure B-26 Report using SQL view for date conversions


4. Run the report. It should look like the example provided in Figure B-27.

Figure B-27 Results of report using SQL view for date conversions

5. Save your report as Date conversion using SQL view.

Comparing the date conversion techniques

At this point, you may be wondering whether it matters what date conversion technique you implement. From a functional standpoint, the answer is no. All three methods will provide reliable date conversion results. However, from a report-performance perspective, the answer is yes. Pushing the date conversion logic down to the database engine does provide significant report performance advantages, but exactly to what degree will always vary, depending on factors such as system resources, system activity, available indexes, the number of rows retrieved, and the number of columns converted. But to give you some idea of what gains can potentially be realized, a mini-benchmark was found to compare the performance results of the two techniques. The benchmark used a 600,000-row ORDERS table. The DB2 Web Query reports used were essentially identical to the two that you created in the above date conversion exercise.

Each version of the report was run 20 times and the run time (the time between when the user selected the report and when the report was displayed to the browser) was recorded and averaged. The results are displayed in Table B-6.

Table B-6 Results

The reason why the date conversion table and SQL views perform so much better (than the DB2 Web Query BIF’s) is because the conversion logic processing is pushed down to the DB2 engine. However, these are two vastly different approaches:

� Performing database joins to locate the row with the data that is already converted� Performing the conversions dynamically

If SQE processes the requests, both have the ability to cache the results so that subsequent requests perform better. As you can see in the above benchmarks results, the date dimension table performed slightly better, particularly as more conversion functions were added to the SQL view.

Date conversion technique Average run time(20 executions)

DB2 Web Query functions (BIFs) 41.6 seconds

Date conversion table 3.9 seconds

SQL functions in an SQL view 5.2 seconds


In addition, performing the conversion in SQL views and functions may require a fairly elaborate view definition and does require some degree of SQL knowledge to implement. The date conversion table, on the other hand, can be implemented by someone with limited SQL skills.

Performance notwithstanding, the best technique is purely subjective. For simplicity, most report developers would probably prefer to use the DB2 Web Query BIFs. Use of the BIFs may provide acceptable performance in your environment, particularly for smaller databases. Consequently, the suggested approach is to try using the DB2 Web Query BIFs first. If the performance is not satisfactory, then consider using one of the other two techniques.

When deciding between the date conversion table or SQL function/view method, most people would likely find the date conversion table method to be a bit more flexible and easier to implement. Because the information resides in a table that can be viewed and maintained, it is easier for many to conceptualize. Implementing customized columns like fiscal year/quarter and a Super Bowl Sunday flag is also easy because you can manually set these values in the table and view the data. And after all, there is no SUPERBOWLSUNDAY SQL function (not yet anyway, though one could add syntax to the view to join it with another table that has this information).

Converting date fields in Oracle’s JD Edwards World application

Oracle’s JD Edwards World application has a very large install base on the IBM i platform. The database for this system stores dates in a specific nonstandard format. Consequently, many JD Edwards World customers that use DB2 Web Query must know how to handle this specific type of date conversion.

Date fields in World are typically defined as ZONED (6,0) and are in the format CYYDDD broken down as follows:

� C represents the century indicator:

– 0 for any date prior to January 2000 – 1 for any date on or after January 1, 2000

� YY represents the 2-digit year. Dates for the year 2009 would be stored as 09.

� DDD represents the number of the day of the year, counting from January 1. So for August 27, 2009, these digits would contain the value 239.

For August 27, 2009, the full value for this field is 109239 and for August 27, 1999, it is 009239.

Attention: IBM and Information Builders development teams are working on ways to improve the performance of the DB2 Web Query built-in functions, particularly those used for date conversion. The goal is to pass as much of that logic to the database engine as possible. DB2 Web Query’s ability to internally translate the BIF to the appropriate SQL function would provide the best of both worlds—report developers could use the BIFs for date conversions and deliver a report that performs well.


To convert this field to a true DB2 Web Query date, use one of the following (assume that the JDE World file is F43090 and the date field is PCCEFJ):

� DB2 Web Query BIF

Use the following expression (where PCCEFJ is the World date field):

DATECVT (((GREGDT (PCCEFJ , 'I8')) + 19000000), 'I8YYMD', 'MDY')

An example is shown in Figure B-28.

Figure B-28 Converting JDE World date


� Date conversion table

To implement the date conversion table method for JDE World date fields, create a join from the World file to the date conversion table using the World date field (in this case PCCEFJ) and DC_JDE_JULIAN_DATE as the join columns. Figure B-29 shows an example of how to define this join in the DB2 Web Query synonym.

Figure B-29 Using date conversion table to convert JDE World date

� SQL functions/view

If you prefer the SQL functions and view technique, use something like the following to convert the field to a date:

SELECT DATE(DIGITS( DECIMAL(pccefj + 1900000 , 7 ,0))) AS conv_date FROM f43090


Converting other common legacy date formats

IBM i customers have represented their date fields in many different formats over the years. Some of the more common ones and how to convert them (for each of the three techniques) are provided in Table B-7.

Table B-7 Legacy date conversion table

Example legacy date field name

Legacy data type

Legacy date Format

Legacy example (August 31, 2009)

DB2 Web Query BIF Expression

Date conversion table

SQL function

CH_MDYY CHAR(8) MDYY ‘08312009’ DATECVT(CH_MDYY, 'A8MDYY', 'MDYY')

Join CH_MDYY to DC_MDYY_CHAR in DATE_CONV table

DATE(SUBSTRING(CH_MDYY,5,4) || '-' || SUBSTRING(CH_MDYY,1,2)|| '-' || SUBSTRING(CH_MDYY,3,2))

CH_YYMD CHAR(8) YYMD ‘20090831’ DATECVT( CH_YYMD, 'A8YYMD', 'MDYY' )

Join CH_YYMD to DC_YYMD_CHAR in DATE_CONV table

DATE(SUBSTRING(CH_YYMD,1,4) || '-' || SUBSTRING(CH_YYMD,5,2)|| '-' || SUBSTRING(CH_YYMD,7,2))

ZN_MDYY ZONED (8,0) MDYY 08312009 DATECVT( ZN_MDYY, 'I8MDYY', 'MDYY' )

Join ZN_MDYY to DC_MDYY_ZONED in DATE_CONV table

DATE(SUBSTRING(DIGITS(ZN_MDYY),5,4) || '-' || SUBSTRING(DIGITS(ZN_MDYY),1,2)|| '-' || SUBSTRING(DIGITS(ZN_MDYY),3,2))

ZN_YYMD ZONED (8,0) YYMD 20090831 DATECVT( ZN_YYMD, 'I8YYMD', 'MDYY' )

Join ZN_YYMD to DC_YYMD_ZONED in DATE_CONV table

DATE(SUBSTRING(DIGITS(ZN_YYMD),1,4) || '-' || SUBSTRING(DIGITS(ZN_YYMD),5,2)|| '-' || SUBSTRING(DIGITS(ZN_YYMD),7,2))

PK_MDYY PACKED (8,0) MDYY 08312009 DATECVT( PK_MDYY, 'P8MDYY', 'MDYY' )

Join PK_MDYY to DC_MDYY_DEC in DATE_CONV table

DATE(SUBSTRING(DIGITS(PK_MDYY),5,4) || '-' || SUBSTRING(DIGITS(PK_MDYY),1,2)|| '-' || SUBSTRING(DIGITS(PK_MDYY),3,2))

PK_YYMD PACKED (8,0) YYMD 20090831 DATECVT( PK_YYMD, 'P8YYMD', 'MDYY' )

Join PK_YYMD to DC_YYMD_DEC in DATE_CONV table

DATE(SUBSTRING(DIGITS(pk_yymd),1,4) || '-' || SUBSTRING(DIGITS(pk_yymd),5,2)|| '-' || SUBSTRING(DIGITS(pk_yymd),7,2))

ZN_JUL ZONED (7,0) YYDDDJulian Date

2009243 GREGDT( ZN_JUL, 'I8YYMD' )

Join ZN_JUL to DC_JULIAN in DATE_CONV table

DATE(SUBSTR(CHAR(ZN_JUL),1,7))

ZN_CENZN_YEARZN_MONTHZN_DAY

(Each component of the date is stored in a separate zoned decimal field.)

ZONED (2,0)ZONED (2,0)ZONED (2,0)ZONED (2,0)

CCYYMMDD

20090831

DATECVT( ((ZN_CEN * 1000000) + (ZN_YEAR * 10000) + (ZN_MONTH * 100) + ZN_DAY), 'I8YYMD', 'YYMD' )

Join legacy date fields to the following columns in DATE_CONV table:DC_CCDC_YYDC_MMDC_DD

DATE(DIGITS(ZN_CEN) || DIGITS(ZN_YEAR) || '-' ||DIGITS(ZN_MONTH)|| '-' || DIGITS(ZN_DAY))

CH_CENCH_YEARCH_MONTHCH_DAY

(Each component of the date is stored in a separate character field.)

CHAR(2)CHAR(2)CHAR(2)CHAR(2)

CCYYMMDD

20090831

DATECVT( (CH_CEN || CHYEAR || CH_MONTH || CH_DAY), 'A8YYMD', 'YYMD' )

Join legacy date fields to the following columns in DATE_CONV table:DC_CC_CHARDC_YY_CHARDC_MM_CHARDC_DD_CHAR

DATE(CH_CEN || CH_YEAR || ‘-’ || CH_MONTH|| ‘-’ || CH_DAY)


DB2 Web Query date built-in functions

In this section we present a few of the more common DB2 Web Query built-in functions that you can do with dates. These functions are described in more detail in the help text included with Developer Workbench.

DATEADD: adding or subtracting a date unit to or from a date

You can add or subtract years, months, days, weekdays, or business days from your date. Business days can take a holiday file as input. By default, a business day and a weekday are the same concept. In the following function, the date field must have a format like YYMD, MDY, or JUL. Increment must be an integer.

DATEADD(date, ‘Y/M/D/WD/BD’, increment)

Figure B-30 demonstrates adding 11 business days (‘BD’) to the order date to calculate the ship date.

Figure B-30 DATEADD

The DATEADD function is not required if you simply want to add months or days to a date. To add months, your result field must be in a format similar to ‘YYM’ or ‘MY’. To add days, your result field must contain days, for example, YYMD.

If we want to add 11 days to SHIPDATE in the previous example and do not need to worry about business or weekdays, we replace the DATEADD with the following values:

ORDERDATE + 11

This creates a SHIPDATE of 11 days in the future.

DATEDIFF: calculating the difference between two dates

Similar to DATEADD, the DATEDIFF function allows you to find the difference between two dates in terms of years, months, days, weekdays, and business days. If you only want to find the difference in months or days, you do not need to use DATEDIFF. You can simply code a statement like the following example:

ORDERDATE - SHIPDATE

The resulting value is based on the least significant component in the order and ship dates. For example, if one of the dates is defined as YYM, then your results are in months. If both dates are defined down to the day level, then your results are in days.


The result field from DATEDIFF should be defined as an I8 field (Figure B-31):

DATEDIFF(date1, date2, ‘Y/M/D/WD/BD’)

Date1, date2, or both can be fields or constants, for example, ‘20070101’.

Figure B-31 DATEDIFF

DATEMOV: moving the date to a significant point

DATEMOV moves your date field to a significant point such as the end of the week or the beginning or the quarter. Table B-8 lists the possible values for move-point.

DATEMOV(date, ‘move-point’)

The date field must be a full date, for example, MDYY or YYJUL.

Table B-8 Values for move-point

Move-point Meaning

EOM End of month

BOM Beginning of month

EOQ End of quarter

BOQ Beginning of quarter

EOY End of year

BOY Beginning of year

EOW End of week

BOW Beginning of week

NWD Next weekday

NBD Next business day

PWD Prior weekday

PBD Prior business day

WD- Current weekday or prior weekday (if weekend)

BD- Current business day or prior business day if current is a non-business day

WD+ Current weekday or next weekday (if weekend)

BD+ Current business day or next business day if current is a non-business day


Example: Dynamic Date Range report

In this section you create a report that gives the user the ability to select a dynamic range of rows based on two input parameters:

� An input date � A number of days

The report will calculate a date range based on the two input fields. The date range is defined as follows:

� beginRange: the specified number of days before the input date� endRange: the specified number of days after the input date

The report will then return rows in which the order date within is the specified date range. For example, if the user entered 200071212 for the date and 10 for the number of days, the report would return rows on or between December 2, 2007, and December 22, 2007.

To create this report, take the following steps:

1. Create a new report using Report Assistant and select cen_orders at the data source.

2. Create a DEFINE field named inDate2. The format is YYMD and the expression is DATECVT(&inDate, 'I8YYMD', 'YYMD'). An example is shown in Figure B-32.

Figure B-32 DEFINE field for inDate2

This define field automatically creates the prompt for an input parameter named &inDate (when the report is run). This is an example of an implicit input parameter. It then converts the input parameter to a true date field.

Attention: You do not need to create an input parameter for &inDate in the Selection criteria tab.


3. Create a DEFINE field named beginRange. The format is YYMD and the expression is DATEADD( inDate2, 'D', (0-&daysRange)), as shown in Figure B-33.

Figure B-33 DEFINE field beginRange

Similar to above, this define field will create the prompt for an input parameter named &daysRange (when the report is run). Again, you do not create an explicit input parameter for &daysRange. The DEFINE field will return a date that is the specified number of days less than the specified input date.

4. Create a DEFINE field named endRange. The format is YYMD and the expression is DATEADD( inDate2, 'D', &daysRange), as shown in Figure B-34.

Figure B-34 DEFINE field endRange


This DEFINE field will return a date that is the specified number of days greater than the specified input date.

5. Go to the Selection Criteria tab and create two screending conditions for the ORDERDATE column:

– The first condition is GREATER THAN OR EQUAL TO the beginRange DEFINE field– The second condition is LESS THAN OR EQUAL TO the endRange DEFNE field.

Select WHERE for both conditions. An example is shown in Figure B-35.

Figure B-35 Dynamic Date Range Report selection criteria

6. Return to the Field Selection tab and complete the report by selecting the following Sort by and Sum report columns:

– Sort by: ORDERDATE, PRODUCTTYPE– Sum: COSTOFGOODSSOLD, LINETOTAL

Important: The order in which you create these DEFINE fields is very important. This is because the second and third DEFINE fields contain expressions that reference the first DEFINE field. If you define them out of order, the expression will fail because it will be unable to find and resolve DEFINE field inDate2.



Figure B-36 Sort by and Sum columns

7. Save your report as Dynamic Date Range.

8. Click Quit to return to the DB2 Web Query launch page.

9. Run the new Dynamic Date Range report.

10.Specify 20071111 for the inDate parm and 5 for daysRange.


11.Click Run. The report returns rows for orders between 11/06/2007 and 11/16/2007, as shown in Figure B-37.

Figure B-37 Dynamic Date Range report results


Appendix C. Processing differences between the define and compute fields

In this appendix we describe how DB2 Web Query processes a define or compute field at different points in the reporting sequence.

Figure C-1 shows the reporting sequence to illustrate the differences between the define and the compute.

Figure C-1 DB2 Web Query processing sequence

C

Web Query Processing Sequence

DEFINE works with individual

database values

COMPUTE workswith aggregated

values

Locate the file description(s) and data files

Select records based on database values

Select records based on TOTAL tests

Format the report

Sort the Data

Prepare individual and/or aggregated values

Determine values ofDEFINEdfields

Select records basedon DEFINEdfields

Resolve COMPUTEdfields


We explain the sequence in greater detail as follows, while noting the differences between the two fields:

1. When DB2 Web Query begins to process a report request, it locates the Master File Description (MFD) and the database. DB2 Web Query then processes the WHERE test on a database value to select a valid record for the report.

2. After selecting a record, DB2 Web Query determines the value of each define field in sequence. After determining the values of the define fields, it executes any selection tests that use the value of a define field and potentially further limits the number of records per report.

3. DB2 Web Query then sorts the data (according to the BY and ACROSS phrases) and performs the action indicated in the verb phrase (PRINT, SUM, or COUNT). If the report uses SUM or COUNT, it aggregates the values in memory.

4. DB2 Web Query then takes the processed data and determines the values of any compute fields, in the sequence in which they appear in the request.

5. After evaluating the compute fields, DB2 Web Query performs the final selection test. It performs any WHERE TOTAL tests against any aggregated results and the values of the compute fields, and thereby further limits the records for the report.

6. DB2 Web Query formats the report and routes it to your Web browser.


Appendix D. Change Management considerations

Using DB2 Web Query, there are several items that we must consider for moving reports between systems, such as the metadata, the reports, and any supporting elements (for example, images). We could need to move these between a development and production system or just between multiple systems. There are two major ways to do change management in Web Query that we discuss in this appendix.

D


Developer Workbench

The simplest way to move items between multiple systems is using Developer Workbench. This requires a connection to both systems at the same time to make this work. Once both systems are added and expanded in Developer Workbench, you can simply drag and drop between systems. This works for all types of items:

� Metadata� Applications� Domains� Folders� Reports� HTML pages� Images

Without Developer Workbench

If you do not have Developer Workbench or cannot get a connection to both systems at the same time (ISV selling an application built with the SDK to a customer, for example), there is still hope. However, the process becomes a little more complex. We must think in two parts: metadata and everything else.

The metadata exists in application folders off of the /qibm/userdata/webquery/ibi/apps directory. If you are an ISV or are developing a portable application, you should consider creating your metadata in an application folder. See 3.6.1, “Metadata” on page 46, for details on metadata segregation.

Since all the metadata is stored in these folders under /qibm/userdata/webquery/ibi/apps, we can simply use a save file to save that folder and restore it on another system. As a reminder, whenever we are FTPing a save file, we must do so in binary (bin) mode. Once the folder is restored on the other system, it is set to go.

Keep in mind that most metadata entries have libraries hard coded in them. So if the data is in MYTESTDATA on the dev system and MYPRODDATA on the prod system, moving metadata is not going to be useful. Instead, the metadata should be recreated on the production system to embed the proper schema names.

We are half way there. Now we must move the reports over. We can do this using the Change Management facility built into the Web Query console. You can access the Web Query console by going to:

http://systemname:11331/webquery_html/wfconsole.htm

You must log in as QWEBQRYADM at the console home screen. From there, click Utilities → MR Change Management → Extract. Since the QWEBQRYADM profile is usually not authorized to any domains, you are now prompted to log in with a profile that has the authority to the domain containing the objects that you wish to move.

From here you will be presented with a two-panel screen. On the left are all the objects for which you are authorized. On the right an empty panel will fill to show which items you have selected. You can select either an entire domain to move or individual items. Those individual items can be reports, graphs, HTML pages, and supporting files such as images. Once all the items are selected and appear on the right-hand side, click Create Change Package and download the zip file.


http://systemname:11331/webquery_html/wfconsole.htm

Move this zip file on to the system on which you want to load the reports. Place the zip in the /qibm/userdata/webquery/ibi/webfocus76/utilities/cm/load/ directory. Here the process is almost the same. Log into the Web Query console as QWEBQRYADM. Select Utilities → MR Change Management, but now select Load instead of Extract. Log in with your normal Web Query profile. If you are importing an entire domain, you must have MRADMIN authority since that is the only level that can create a new domain, which is essentially what you are doing during the load.

Again, we have the two-panel screen, showing the available packages on the left. Select the one that you just created to move to the right side and click Load Change Package. A confirmation message appears when the load is complete. For more details on this process see IBM i Knowledge Base Document 517159487.

Appendix D. Change Management considerations 583


Appendix E. Additional material

This book refers to additional material that can be downloaded from the Internet as described below.

Locating the Web material

The Web material associated with this book is available in softcopy on the Internet from the IBM Redbooks publication Web server. Point your Web browser at:


Alternatively, you can go to the IBM Redbooks Web site at:

ibm.com/redbooks

Select the Additional materials and open the directory that corresponds with the IBM Redbooks publication form number, SG247214.

Using the Web material

The additional Web material that accompanies this book includes the following files:

File name DescriptionQWQCENT.savf iSeries Library

System requirements for downloading the Web material

The following list contains the most important requirements:

� i5/OS V5R4� 5733-QU2 - DB2 Web Query for System i

E





How to use the Web material

Create a subdirectory (folder) on your workstation, and unzip the contents of the Web material zip file into this folder and upload the i5/OS save file to your System i environment.


Related publications

The publications listed in this section are considered particularly suitable for a more detailed discussion of the topics covered in this book.

IBM Redbooks publications

For information about ordering these publications, see “How to get IBM Redbooks publications” on page 587. Note that some of the documents referenced here might be available in softcopy only.

� OnDemand SQL Performance Analysis Simplified on DB2 for i5/OS in V5R4, SG24-7326

� Preparing for and Tuning the SQL Query Engine on DB2 for i5/OS, SG24-6598

� SQL Performance Diagnosis on IBM DB2 Universal Database for iSeries, SG24-6654

Online resources

These Web sites are also relevant as further information sources:

� Information Builders Corporate

http://www.informationbuilders.com/

� DB2 for i5/OS Portal

http://www.ibm.com/systems/i/software/db2

� DB2 Web Query

http://www-03.ibm.com/systems/i/software/db2/webquery/

� DB2 Web Query for i developerWorks Community


� System i Database DB2 UDB SQL call level interface (ODBC)


� Indexing and Statistics Strategies for DB2 for i5/OS


How to get IBM Redbooks publications

You can search for, view, or download Redbooks publications, IBM Redpapers™ publications, Technotes, draft publications and Additional materials, as well as order hardcopy Redbooks publications, at this Web site:

ibm.com/redbooks


http://www.informationbuilders.com/

http://www.ibm.com/systems/i/software/db2

http://www-03.ibm.com/systems/i/software/db2/webquery/






Help from IBM

IBM Support and downloads

ibm.com/support

IBM Global Services

ibm.com/services


http://www.ibm.com/support/

http://www.ibm.com/support/

http://www.ibm.com/services/

http://www.ibm.com/services/

Index

Symbols*QRYDFN 4

Numerics3020 record 4765722-QU1 (Query/400) 4–5, 185733-QU2 (DB2 Web Query) 5–7, 17–18, 45, 231, 233, 464

Aaccess file 47, 258, 528Active Reports 8, 233, 497

active visualizations 519ActiveX controls 239cross-tab or pivot functionality 248e-mail user requirements 519file size 519filtered chart 244general use of 239highlights 234license key 235overview 234problems saving 520report creation 235tutorial 233

Active Reports Styling 236ActiveX controls 239adapter 13

optimization 452processing 452

Add Adapter Configuration 397ADDLICKEY command 396add-on products 518ADDRDBDIRE command 75ADDWQLUSR 30ADMIN 41Administration Console 12Administration console 408Administrator tasks 26administrator tasks 33

assignment of authority to users 36domains 33subfolder creation 35

Advanced 412aggregate field 128aggregation optimization 459AJAX 7, 497analysis 481application server 10, 12architecture 10auditing 502authority, assignment to users 36authorization of users 19

© Copyright IBM Corp. 2010. All rights reserved.

automatic generation or refresh of metadata 503autostart after IPL 501Available fields icons 102

Bbar chart 154, 308

dual axis 162multiple bars to one chart 158with drill-down capabilities 156

basic synonyms 352basic user 87Basic user tasks 26benchmark, DB2 Web Query 488Burst this Report 414Burst Value 420Business View 371Business Views 48

Ccalendar controls 323call-level interface (CLI) 22capabilities of DB2 Web Query 496cell formatting 392CENTURY 45Change report 36chart, revenue trend over time 170CHGUSRPRF 33child table 58Classic Query Engine (CQE) 5, 13, 95, 465, 507CLI (call-level interface) 22cluster 101cluster join 364Common Domain 33, 93Common Domain folder 33compound parameterized report 296

bar chart 308gross profit report 309HTML page options 309HTML report 302line chart 304New form element 306

compute field 192, 579computing fields 118conditional styling 121, 191, 387configuration of Developer Workbench 254Configuring Report Broker 407Connection Name 76Contains operand 243CPU resource usage 491CQE (Classic Query Engine) 5, 13, 95, 465, 507CREATE ALIAS 56Create domain 36Create report 36Create subfolder 36

589

Create Synonym 50, 399Creating Metadata 399cross-system join 74, 462cross-tab functionality 248cross-tab report 115

Ddashboard 14, 513

graphics 513periodic report 513

Dashboards in Excel 391data adapters 7, 13

DB2 CLI 7, 13DB2 Heritage File 7, 13DB2 Heritage File adapter 13Query/400 7

data download to PC server or Windows server 499data field, format conversion 534data profiling 8, 376Data Range Properties 392database

analysis and tuning 486design 465monitor 487

database joins 48Datasource 76date

component conversion 534functions 572manipulation 358separator 532

date and timefunctionality 529system variables 530

Date Decomposition 8, 356date field 533

conversion 533date component conversion 534in arithmetic expressions 533

date format 530display options 531

date formatting 112date range filter 178date range parameter 182DATEADD function 572DATEDIFF function 572DATEMOV function 573DB2 10DB2 CLI adapter 7, 13

performance 450DB2 file output 135DB2 for i5/OS

database, query without multiple licenses 506optimization 465referential integrity features 502

DB2 Heritage File adapter 7, 13, 56DB2 Web Query 5

additional features 497administrator tasks 33adopted authority for reports 501

aggregation optimization 459architecture 10attributes 12autostart after IPL 501base features 6capabilities 496conditions that prevent optimization 457data adapters 13Developer Workbench 14domain authority 502domains 33, 500exception join 506features 6functional differences with Query/400 443functional similarities with Query/400 442general announcement 388, 396, 432, 496Graph Assistant 6imported Query/400 object 507imported Query/400 query 507installation 18installation and server operations 17integration with Excel 2007 518integration with Rational tools 499introduction 5license keys 19login 30multiple licenses 506named user 502object import from Query/400 506OLAP feature dimensions 518optional features from IBM 7optional features from Information Builders 9PC and System i requirements 20performance benchmark 488performance considerations 449port 11331 for HTTP requests 500Power Painter 7product information 388, 396, 432, 496product positioning 14QRYDFN edit 448Query/400 definitions 507reasons to move from Query/400 497referential integrity 58Report Assistant 6report auditing 502report development 507report run from CL program 513Reporting Server 13

commands 21reports from Query/400 506running existing Query/400 reports 441running in an IASP environment 581RUNWEBQRY command 513save and restore 522server jobs 22server-based processing 500servlet 11sign-on via LDAP or Kerberos 502sorting optimization 459stored procedures with input parameters 510


training and education 524upgrade to 506user security 501web console 500

DB2 Web Query domain 27DB2 Web Query users 26DB2 Web Query V1R1M1 407DDS Logical files 47define field 192, 579defining fields 118detail reports 104Developer tasks 26developer tasks 44

creation of metadata 48cross-system join 74

Developer Workbench 7, 14, 99, 253, 498additional features 351Business View 371configuration 254data profiling 376Date Decomposition 356date manipulation 358default options 258filter creation 360HTML Layout Painter 295Impact Analysis 373Java 2 SDK 21not part of base DB2 Web Query product 519OLAP 261profiling 253requirements 21

hardware 21software 21

SQL Wizard 379Synonym Editor 253, 352synonym management 504

dicing 7dimensions 263Distribute report by 413Distribution 412domain 32–33, 500

authority 502create 34creation 34eight-character rule 34rename 35renaming 35

domain-level report movement 504double-spaced printing 511drill down 14, 161

adding to chart 160bar chart 156

drill downs 387drill-down report 141

further drill downs 511

EEDAPGWY 22EDAPLOG 22EDAPTH 22

Email option 413ENDWEBQRY 405ENDWEBQRY command 22Establishing a connection 396Event driven distribution 429Excel 6

output 133with formulas option 518

Excel 2000 133Excel 2007 integration with DB2 Web Query 518Excel 97 133Excel spreadsheet

access to another spreadsheet 518integration 516report 516

exception joins 506Extensible Markup Language (XML) 6

FFAQs (Frequently Asked Questions) 395, 405, 495federated DB2 7filter creation 360Foreign key option 102foreign key relationships 460foreign keys 400format conversion 534formatting 387formula support 387Frequency 412Frequently Asked Questions (FAQs) 395, 405, 495fullselect 460

Ggeneral announcement 388, 396, 432, 496generic term report 297graph

building with Power Painter 204properties and settings, Graph Assistant 168

Graph Assistant 6bar chart 154conditional styling 191date range parameter 182drill down 160dual axis bar and line chart 162graph properties 168line graph 171pie charts 185traffic lighting a graph 191

gross profit report 309group profile MDUNTITLED 92Group profiles 27GRPPRG user profile, domain authority 502

Hhierarchy 263Highlight button 243highly parameterized report 311

calendar controls 323

Index 591

Highly Parametrized reports 424HLISNK 22host table 457Href 33HTML launch page 390HTML Layout Painter 253, 295

compound parameterized report 296highly parameterized report creation 315parameter controls 320Run button 310tool 8

HTML page options 309HTML report 302HTTP clients 10

Ii5/OS system objects 18IBM DB2 Web Query for System i 5IBM Query for System i 4icons for Available fields 102IDE (Integrated Development Environment) 14Impact Analysis 8, 373imported report 507index 460, 475Index Advisor 476, 487Index Only Access 475, 487Information Builders optional features 9Inner Join 146input parameters 510Installation 388installation 17–18Installing Report Broker 407Integrated Development Environment (IDE) 14integrated file system 12

directories 18metadata 527

integration with Rational tools 499iSeries Navigator, synonym management 503

JJava 2 SDK 1.5.0_09 21JDBC driver 396join disablers 457join optimization 456join relationship 502join segments 66join types 146join, table 364joining tables 144joins in DB2 Web Query synonyms 66JSCOM3 22

KKerberos sign-on 502key constraints 60key performance indicators (KPI) 14

LLDAP sign-on 502Left Outer Join 146library list-like behavior 504license key 19, 235line chart 162, 304line graph 171

date range filter 178Log Purge Period 409Log Purge Time 409long-running report 480

MManaged Reporting drivers 12Master file 47master file 258, 527materialized query table (MQT) 51, 461, 487Materialized Query tables 47MDUNTITLED group profile 19, 92memory usage 491Metadata 46metadata 6, 48

automatic generation or refresh 503considerations for creation 51deletion of 528from Query/400 objects 444MQT 51prefix and suffix 447stored procedures 51tables 51views 51

metadata creationi5/OS object deleted 57miscellaneous considerations 51multimember files 55

model 8nn system 499MQT (materialized query table) 461, 487MRADMIN 405MRADMIN group 92MRADMIN group profile 19MRSCHEDULE 405multi-dimensional 7multimember files 55multiple bars on one chart 158multiple instance 146multiple members 13multiple result sets 55multiplicative effect 457

Nnamed user 502

licenses 8New form element 306Notification 412number of rows 508

Ooffline reporting 8


OLAPdicing 273dimension 262Dimension Builder 265dimensions for database 518drill down 262drill-down options 271enabled report 272enablement 270getting started 262grouping data 293hierarchy 262–263hyperlinks 262measure 262metadata 262modeling view 264pivot 262slicing 273Synonym menu 265terminology 262tutorial 261

OLAP (online analytical processing) 7, 261OLAP Control Panel 285OLAP dimensions 48OLAP module 498OLAP report

on demand column sort 519prior selections 518

on-demand paging 131online analytical processing (OLAP) 7, 261operational reports 14OPNQRYF command 13optimization 457

DB2 for i5/OS 465disablers 481hierarchy 455other influencers 459

Other Files folder 33output files for next query 443output options 130

Ppalettes 200parameter controls 320parameter passing 443parameterized report 137

design 515multiple item selection 511

parameters, adding 296parent report 141parent tables 58PC requirements 20PC server 499PDF (Portable Document Format) 6

distributing batch reports via e-mail 519output 132

performanceadapter processing and optimization 452basics 450benchmark for DB2 Web Query 488

case study 480DB2 CLI adapter 450DB2 Web Query 449Query/400 adapter 464remote database access 462

pie chart 185product type for each year 185

pivot functionality 248port 11331 for HTTP requests 500Portable Document Format (PDF) 6PostScript 6Power Painter 7

building a graph 204building a report 212Clustered Bar chart 205dashboard 513Data Sources palette 203launching 200PDF report 221Properties palette 203tailoring the main window 200

Predefined Server configurations 388prefix 50

and suffix 51metadata 447

primary key 58printing, double-spaced 511product information 388, 396, 432, 496projection 455

QQRYDFN

edit by DB2 Web Query 448objects 441

QSQSRVR 22Query/400 4, 441–442

5722-QU1 5adapter 7, 464adapter performance 464definitions 507functional differences with DB2 Web Query 443functional similarities with DB2 Web Query 442imported query 507metadata from Query/400 objects 444migration of reports to DB2 Web Query 506object 507object import 506product history 4reasons to move to DB2 Web Query 497report development 507running existing reports in DB2 Web Query 441

QWEBQRYADM 19QWQCENT 45

Rranking columns 129Rational tools 499RDBMS (relational database management system) 11Redbooks Web site 587

Index 593

Contact us xivreferential constraint 58referential integrity 456

benefits in DB2 Web Query 58DB2 for i5/OS 502

Refresh Synonyms 504Registered/named users 27relational database management system (RDBMS) 11remote database access 462report

adopted authority 501building with Power Painter 212creating with Active Reports 235creation 100development 507development phase 508distributing batch reports in PDF via e-mail 519execution phase 451layout 101long-running 480production phase 452Query/400 reports in DB2 Web Query 441request process flow 450sample detail 116security for specific user 502selection defined on expression 515tuning options 482types 14, 136

Report Assistant 6date formatting 112DB2 file output 135drill-down reports 141Excel output 133footings 124generating subtotals 126headings 124on-demand paging 131output options 130parameterized reports 137PDF output 132ranking columns 129report properties 144selection criteria 113sort by aggregate field 128sorting 128style sheet 508subtotal generation 126

Report Assistant mode 389Report Assistant route 390Report Broker Administrator 425Report Broker and Active Reports 428Report Broker distribution list 418Report Broker Schedule panel 412report developer, SQL statements 519Report Library 14Report Options 412Reporting Server 10, 13

commands 21Reports folder 33requirements 20

restore 522revenue trend over time chart 170Right Join 442RMVWQLUSR 30row quantity 508RSTLICPGM command 17Run button execution 310Run Interval 413Run report 36Run Time User Enablement option 29Run time users 27RUNBRSCHED 429RUNWEBQRY command 513

database file option 514registered named user 514

Ssample detail report 116save 522SCHED 41Scheduling Frequency 416scorecards 14second Y axis 165securing Metadata 81Security 76security

specific user 502user 501

segmented metadata 82Segmenting Metadata 81selection 454selection criteria 113Sent as an attachment 413server jobs 22

EDAPGWY 22EDAPLOG 22EDAPTH 22HLISNK 22JSCOM3 22QSQSRVR 22TSCOM3 22WQLWI7 22

server operations 17server-based processing 500servlet container 12servlet engines 12SET CURRENT DEGREE 52SET OPTION SRTSEQ 52single instance 146slicing 7sort by aggregate field 128sorting optimization 459Spreadsheet Client 387Spreadsheet Client Manual 393spreadsheet reports in Excel 516SQE (SQL Query Engine) 5, 507SQE Plan Cache 476, 486SQL catalog views 96SQL CREATE TABLE 95SQL fullselect 460


SQL Performance Monitor 476SQL Plan Cache snapshot 476SQL Query Engine (SQE) 5, 507SQL statements, report developer 519SQL trace 481SQL translation 455SQL view 483, 510

creation 459new report 484

SQL views 47SQL Wizard 8, 253, 379statistics 475stored procedure

input parameters 510Stored procedures 47Structured Ad-Hoc Form mode 390STRWEBQRY 405STRWEBQRY command 22style sheet 508subfolders creation 35suffix 50

and prefix 51metadata 447

sum reports 104summary report 101SUPGRPPRF parameter 502Supplemental Group (SUPGRPPRF) parameter 502Symmetric Multi Processing 52synonym 5–6, 483

individual movement 523management 503

Synonym Candidates 50Synonym Editor 253, 351–352, 504Synonyms, Refresh option 504System i

objects 95requirements 21

system objects 19

Ttable join 364Tables/physical files 47target table 457time and date functionality 529trace statements 481traffic lighting

a graph 191conditional styling 121

TRCWEBQRY command 22TSCOM3 22tutorial

Active Reports 233getting started 91OLAP 261

Uunique join 457upgrade to DB2 Web Query 506Usage 389

USER 41user authorization and verification 19user security 501user-specified date range parameter 182

Vvariables in report headings and footings 124verification of users 19view 460Viewing the Distribution log 423virtual columns 48Visual Explain 476, 487

WWAB (Web Application Bundle) file 12Web 2.0 497Web Application Bundle (WAB) file 12Web browser clients 12web console 500Web server 10, 12Web-based query and report writing function 497WebFOCUS 297WebSphere Application Server 500WHERE 114WHERETOTAL 114Windows Explorer, synonym management 503Windows server 499Work with Web Query 30WQLWI7 22WRKLICINF 30WRKLNK command, synonym management 503WRKRDBDIRE command 74WRKWEBQRY 405WSff0ad76f515651cb176dad510f7220ddaa-68e6 285

XXML (Extensible Markup Language) 6

YY axis 165

Index 595


Getting Started with DB2 W

eb Query for i


eb Query for i


eb Query for i


eb Query for i


eb Query for i


eb Query for i

®

SG24-7214-01 ISBN 0738433985

INTERNATIONAL TECHNICALSUPPORTORGANIZATION

BUILDING TECHNICAL INFORMATION BASED ON PRACTICAL EXPERIENCE

IBM Redbooks are developed by the IBM International Technical Support Organization. Experts from IBM, Customers and Partners from around the world create timely technical information based on realistic scenarios. Specific recommendations are provided to help you implement IT solutions more effectively in your environment.

For more information:ibm.com/redbooks

®


Follow the best practice guides to simplify report development

Take your reporting to the next level of Business Intelligence

Learn DB2 Web Query by using the easy-to-follow tutorials

The DB2® Web Query for i product is a Web-based query and report writing product that offers enhanced capabilities over the IBM® Query for iSeries® product (also commonly known as Query/400). IBM DB2 Web Query for i includes Query for iSeries technology to assist customers in their transition to DB2 Web Query. It offers a more modernized, Java™-based solution for a more robust, extensible, and productive reporting solution. DB2 Web Query provides three main components: Report Assistant, Graph Assistant, and Power Painter with the base product. Using these tools, customers can modernize existing Query for iSeries reports while providing a foundation for building more complex business intelligence applications, such as online analytical processing (OLAP), data mining, dash boarding, or data warehouse implementations.

DB2 Web Query provides capabilities to query or build reports against data that is stored in DB2 call-level interface (CLI) databases through the latest browser-based user interface technologies. It enables you to build new reports with ease through the Power Painter or Report Assistant and Graph Assistant components. It simplifies the management of reports by allowing you to leverage parameterized reporting. It delivers data to users in many different formats, including spreadsheets, PDF, HTML, or through browser support of the Java-based thin client interface.

DB2 Web Query offers features to import Query/400 definitions and enhance their look and functionality with Power Painter or Graph Assistant. It enables you to add OLAP-like slicing and dicing to the reports or to view reports in disconnected mode for users on the go. It provides an interface to all data in IBM i5/OS® through either DB2 or Open Query File native adapters that automatically identify the files to be accessed and import the metadata into DB2 Web Query.

This IBM Redbooks® publication provides a broad understanding of the new DB2 Web Query product. It entails a group of self-explanatory tutorials to help you get up to speed quickly. Overall, this book is designed for IT users. You can use Part 2, “Tutorials for DB2 Web Query” on page 89, and Part 3, “Tutorials for DB2 Web Query optional features” on page 231, as stand-alone tutorials for anyone who is developing their own queries. Much of Chapter 8, “Active Reports” on page 233, is appropriate for those who work disconnected from the System i® environment. In addition, you can use much of Chapter 10, “Online analytical processing” on page 261, if you will simply be running OLAP-enabled reports.

Back cover


