Developing Advanced e.Reports

Information in this document is subject to change without notice. Examples provided are fictitious. No part of this document may be reproduced or transmitted in any form, or by any means, electronic or mechanical, for any purpose, in whole or in part, without the express written permission of Actuate Corporation.

© 1995 - 2003 by Actuate Corporation. All rights reserved. Printed in the United States of America.

Contains information proprietary to:

Actuate Corporation701 Gateway BoulevardSouth San Francisco, CA 94080http://www.actuate.com

The software described in this manual is provided by Actuate Corporation under an Actuate License agreement. The software may be used only in accordance with the terms of the agreement.

Actuate Corporation trademarks and registered trademarks:Actuate, the Actuate logo, e.Analysis, e.Report, e.Reporting, e.Spreadsheet, Formula One, Internet Spreadsheet, Live Report Document, ReportCast, Report Encyclopedia, ReportingEngines, the ReportingEngines logo, Reportlet, Spreadsheets Everywhere, Tidestone Technologies, and XML reports.

Third party trademarks or registered trademarks of their respective owners, companies, or organizations:Apache Software Foundation (http://www.apache.org/): Crimson, Tomcat, Xalan, and Xerces. Apple Computer, Inc.: TrueType. BEA Systems, Inc.: BEA WebLogic Server. Bits Per Second, Ltd. and Graphics Server Technologies, L.P.: Graphics Server. Borland Software Corporation: JBuilder. Bristol Technology, Inc.: XPrinter. Bruno Lowagie and Paulo Soares: iText, licensed under the Mozilla Public License (MPL). Component One, LLC.: VSFlexGrid Pro. Fred L. Drake, Jr. (http://sourceforge.net/projects/expat): Expat XML parser, created by James Clark, licensed under the MIT License. Hewlett-Packard Company: HP-UX. IBM Corporation: 1-2-3 , AIX, DB2, Informix-ESQL/C, ICU, Lotus, and WebSphere. Indiana University Extreme! Lab (http://www.extreme.indiana.edu): XML Pull Parser and XPP. InstallShield Corporation: InstallShield. InterNetivity Inc.: Databeacon. JDBM Project (http://jdbm.sourceforge.net): JDBM. LEAD Technologies, Inc.: LEADTOOLS. Linus Torvalds: Linux. Microsoft Corporation: ActiveX, Microsoft, MS-DOS, MSN, Windows, Windows NT. Netscape Communications Corporation, Inc.: Netscape, Netscape Communications, Netscape Communicator, Netscape Enterprise Server, and Netscape Navigator. Oracle Corporation: Oracle Call Interface. Progress Software Corporation: Progress. Quadralay Corporation: WebWorks. Rogue Wave Software, Inc.: NobleNet RPC and Rogue Wave SourcePro. SAP AG: SAP. Sun Microsystems, Inc.: 100% Pure Java, iPlanet, J2EE, Java and all Java-based marks, JavaServer Pages, ONC, Solaris, SPARC, Sun, Sun Microsystems, and Sun ONE. Sybase, Inc.: CT-Library. Symantec Corporation: Visual Cafe. Unicode, Inc.: Unicode. World Wide Web Consortium (W3C): HTML Tidy and tidy.c. X/Open Company, Ltd.: UNIX. Zero G Software, Inc.: InstallAnywhere. Zope Corporation: Digital Creations and DCLC.

All other brand or product names are trademarks or registered trademarks of their respective owners, companies or organizations.Document No. 030430-2-130301 April 21, 2003

i

ContentsIntroduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviiUnderstanding Actuate 7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii

Addressing diverse customer profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviiiAddressing customer requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviiiSupporting international information delivery requirements . . . . . . . . . . . . . . . . xviiiProviding a scalable, high performance server . . . . . . . . . . . . . . . . . . . . . . . . xviiiProviding a complete information delivery solution . . . . . . . . . . . . . . . . . . . . . . xix

Introducing the Actuate 7 and ReportingEngines product suite . . . . . . . . . . . . . . . . . .xxAbout Actuate e.Report Designer Professional product . . . . . . . . . . . . . . . . . . . . . xxiiiAbout Developing Advanced e.Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxvOnline documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxvii

Using online manuals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxviiUsing online help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxvii

Using context-sensitive online help . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xxviiiUsing the Actuate online help system. . . . . . . . . . . . . . . . . . . . . . . . . . . .xxviiiUsing report-specific online help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxx

Typographical conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxxSyntax conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxxi

Part 1Getting started

Chapter 1Designing an e.report with the report wizard . . . . . . . . . . . . . . . . . 3About the sample database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4Choosing the sample configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6Creating a quick report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Starting the report wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8Choosing Quick Report for the report type . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8Choosing the data source for the Quick Report . . . . . . . . . . . . . . . . . . . . . . . . . . 9Choosing the table for the Quick Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11Designing the Quick Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12Finishing the report. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12

Creating a listing report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15About the sample listing report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15Starting the wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16Choosing a listing report for a report type . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16

ii

Choosing the data source for a listing report. . . . . . . . . . . . . . . . . . . . . . . . . . . 17Choosing the tables and fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Organizing the data by table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20Organizing the data by field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Adding summary data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Sorting the detail rows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22Designing the Listing Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23Saving the report design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24Running the report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Publishing a report object executable file to a server . . . . . . . . . . . . . . . . . . . . . . . . 27Creating a server profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27Setting publish and preview options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Logging into a volume to manage files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34Printing a report from a web browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Part 2Using the design environment

Chapter 2Understanding the design process . . . . . . . . . . . . . . . . . . . . . . . . 39About the report design process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40Understanding how Actuate builds a report . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Generating and compiling code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42Building and running the report object executable (.rox) file. . . . . . . . . . . . . . . . . . 43Developing reports with sets of parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Building a report from the command line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45About components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Component relationships in a report design . . . . . . . . . . . . . . . . . . . . . . . . . . . 48Component relationships in a report document . . . . . . . . . . . . . . . . . . . . . . . . . 50

About Actuate’s object-oriented design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51About object-oriented programming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

About classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51About objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52Understanding the relationship between classes and objects . . . . . . . . . . . . . . . . 52About inheritance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

About the Actuate Foundation Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

Chapter 3Understanding the design environment . . . . . . . . . . . . . . . . . . . . 57About the application window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58About the tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

iii

About Design Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .59About the structure pane . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .60About the layout pane . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .61Understanding the meaning of the Design Editor display . . . . . . . . . . . . . . . . . .62

About the Design Editor’s helper tools. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .63About the Project Browser and the Globals Browser . . . . . . . . . . . . . . . . . . . . .64About Component Editor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .65

About Query Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .66Using Query Editor pages and panes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .67About Database Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .68

About using Textual Query Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .69About Stored Procedure Data Source Builder . . . . . . . . . . . . . . . . . . . . . . . . . . .69About Method Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .70About Expression Builder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .71About Report Viewer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .73About Management Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .74

About the toolbars and palettes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .74The Main toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .75The Format toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .76The tool-specific toolbars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .76The component palettes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .77

About context menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .78

Chapter 4Using Design Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79Creating a new report design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .80

Choosing the default connection and data source . . . . . . . . . . . . . . . . . . . . . . . .81Setting the default page size and margins . . . . . . . . . . . . . . . . . . . . . . . . . . . . .82

Placing components in a report design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .83About sources from which you can drag components . . . . . . . . . . . . . . . . . . . . . .84Understanding how placing components determines their use . . . . . . . . . . . . . . . . .85About slots. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .85Placing components in the structure pane . . . . . . . . . . . . . . . . . . . . . . . . . . . . .88

Placing components in empty slots in the structure pane. . . . . . . . . . . . . . . . . . .88Placing components on icons in the structure pane . . . . . . . . . . . . . . . . . . . . . .89

Placing components in the layout pane . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .90Placing components in slots in the layout pane . . . . . . . . . . . . . . . . . . . . . . . .90Placing components in frames in the layout pane . . . . . . . . . . . . . . . . . . . . . . .92Using the mouse to draw components in the layout pane . . . . . . . . . . . . . . . . . .92

Copying, subclassing, and referencing components . . . . . . . . . . . . . . . . . . . . . . . . .94Copying components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .95Subclassing components in Design Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . .96Referencing components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .98

iv

Arranging components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99Selecting components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99Moving components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

Using grids in the layout pane . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102About Scratch Pad . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

Sizing components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104Aligning and centering components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105Layering components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

Setting properties of components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107Changing the class name or superclass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108Removing components from a report design . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109Managing multiple Design Editor windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

Chapter 5Customizing the design environment . . . . . . . . . . . . . . . . . . . . . 111About design environment customization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112Setting general options in the designer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

Customizing the length of the recently opened files list . . . . . . . . . . . . . . . . . . . . 114Choosing a configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115Setting the Management Console URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117Working with the Navigator menu item and toolbar . . . . . . . . . . . . . . . . . . . . . . 117Setting Basic source encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

Setting a font in the designer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118Setting the default font for labels, data, and source editor . . . . . . . . . . . . . . . . . . . 118Setting the font for the structure pane . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

Customizing a component palette . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121Customizing the palette layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121Customizing the class association of a palette . . . . . . . . . . . . . . . . . . . . . . . . . . 123Saving and reusing class associations of palettes . . . . . . . . . . . . . . . . . . . . . . . . 126

Customizing units of measurement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129Setting the default unit of measurement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129Customizing unit suffixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

Moving and closing toolbars and palettes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133Changing tool display options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137Choosing design search paths. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137Choosing a directory for new designs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141Managing server profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142Changing the item list for Create New Report . . . . . . . . . . . . . . . . . . . . . . . . . . . 143

v

Part 3Designing structured content

Chapter 6Working with libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147About libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148Creating a component library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149Publishing a component. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150

Publishing in a library file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151Publishing in a report design file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151

Including a library in a design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153Locating included libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159Placing a library component in a report design . . . . . . . . . . . . . . . . . . . . . . . . . . 160Modifying components from a library. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162About read-only libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162

Chapter 7Using a query data stream . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165Understanding how reports get data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166About data source connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167Defining a database connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167

About ODBC connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171About Progress connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172

Working with a data stream . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172About types of data streams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173About query data source components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173About data rows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175About data filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175

About organizing data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175Sorting data effectively . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176

Using database sort utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176Sorting internally . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177Setting the sorting property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177

About queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177About SQL SELECT statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179Comparison of WHERE and HAVING conditions . . . . . . . . . . . . . . . . . . . . . . . 179Comparing GROUP BY and ORDER BY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180

Writing a query. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181Opening Query Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182Selecting tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183

vi

Using the same table multiple times . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183Modifying table properties in a query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185Displaying an owner name qualifier in Database Browser . . . . . . . . . . . . . . . . . 186Specifying tables to appear in Database Browser. . . . . . . . . . . . . . . . . . . . . . . 186Customizing the FROM clause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186Working with table and view synonyms . . . . . . . . . . . . . . . . . . . . . . . . . . . 187

Selecting columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190Creating computed columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191Creating joins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193Putting conditions on row retrieval (WHERE). . . . . . . . . . . . . . . . . . . . . . . . . . 196Sorting data with Query Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197Sorting data with the OrderBy property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198Using presorted data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199Summarizing data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200Putting conditions on aggregate rows (HAVING). . . . . . . . . . . . . . . . . . . . . . . . 201Viewing the SELECT statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202Optimizing SQL queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203

Using Query by Example (QBE) syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204Synchronizing a query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205

About the query synchronization tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206Understanding changes to a report design during query synchronization . . . . . . . . . . 206About the steps of query synchronization . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207Step 1: Ensuring the connected database is correct . . . . . . . . . . . . . . . . . . . . . . . 207Step 2: Refreshing the data dictionary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209Step 3: Using Synchronize Query With Schema . . . . . . . . . . . . . . . . . . . . . . . . . 210Step 4: Analyzing tables and columns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213Step 5: Using other tools on the query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214Step 6: Changing the Actuate Basic type while checking the query . . . . . . . . . . . . . . 216Checking the consistency of a table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216Changing the column name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217

Chapter 8Working with an information object . . . . . . . . . . . . . . . . . . . . . . . 221About information objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222Using Information Object Wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223

Understanding column display in an information object. . . . . . . . . . . . . . . . . . . . 223Creating an information object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223Running an information object using Information Object Wizard. . . . . . . . . . . . . . . 226

Creating an information object from an existing report object design file . . . . . . . . . . . . 228Modifying a data row component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229

Using Data Row Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230Using Column Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230Modifying a font in an information object . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234

vii

Chapter 9Using Textual Query Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237About Textual Query Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238Writing a textual query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238

Required procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238Optional procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239

Choosing the textual query data source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239Opening Textual Query Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240Writing the SQL query. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241Preparing and describing the SQL query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242Accepting the SQL query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243Editing the SQL query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243Editing column properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245Using static parameters with a textual query . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246Using ad hoc parameters with a textual query . . . . . . . . . . . . . . . . . . . . . . . . . . . 248Sorting data with a textual query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251Converting graphical queries into textual queries . . . . . . . . . . . . . . . . . . . . . . . . . 252

Chapter 10Designing a report that uses an SAP BW data stream . . . . . . . 255About SAP BW data streams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256Configuring the report development environment . . . . . . . . . . . . . . . . . . . . . . . . 256

Installing the SAP Java Connector libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . 256Creating a report design that uses an SAP BW BEx Query data stream . . . . . . . . . . . . . 257Creating an MDX query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263

About Dimensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265Specifying an MDX query’s axes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266Report layout examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267

Example: Creating a blocked, columnar, or tabular report . . . . . . . . . . . . . . . . . 268Example: Creating a crosstab report with one column . . . . . . . . . . . . . . . . . . . 269Example: Creating a crosstab report with more than one column . . . . . . . . . . . . . 270Example: Creating a crosstab report with column grouping . . . . . . . . . . . . . . . . 270

Specifying an ORDER function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271Sorting example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273Specifying a FILTER function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274Specifying slices. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276Specifying values for SAP variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277Displaying and verifying an MDX query . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279

Creating a report design that uses an SAP BW ODS data stream. . . . . . . . . . . . . . . . . 280Changing the Java Virtual Machine’s maximum heap size . . . . . . . . . . . . . . . . . . . . 287

viii

Chapter 11Working with sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289About sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290About report sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291

Combining report sections in a report design . . . . . . . . . . . . . . . . . . . . . . . . . . 291Using nested reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291Using sequential reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291Using conditional reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291Using parallel reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292

Placing a report section in a report design . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292Placing components in a report section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293Sharing connections between report sections . . . . . . . . . . . . . . . . . . . . . . . . . . 293

About group sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293Creating groups using Component Editor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295

Specifying a group key for a group section . . . . . . . . . . . . . . . . . . . . . . . . . . . 296Sorting data with group sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296Grouping data by interval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297Placing components in a group section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298Understanding what group sections do when you run a report . . . . . . . . . . . . . . . . 301

Creating groups using Sorting and Grouping. . . . . . . . . . . . . . . . . . . . . . . . . . . . 302Adding groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303Removing groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304Setting grouping options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304Setting grouping intervals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305Sorting data inside groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306

About sequential sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307Placing a sequential section in a report design. . . . . . . . . . . . . . . . . . . . . . . . . . 308Placing components in a sequential section . . . . . . . . . . . . . . . . . . . . . . . . . . . 308Specifying the print order in a sequential section . . . . . . . . . . . . . . . . . . . . . . . . 309What sequential sections do when you run a report . . . . . . . . . . . . . . . . . . . . . . 310

About conditional sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311Placing a conditional section in a report design . . . . . . . . . . . . . . . . . . . . . . . . . 312Specifying the condition for a conditional section. . . . . . . . . . . . . . . . . . . . . . . . 312Placing components in a conditional section. . . . . . . . . . . . . . . . . . . . . . . . . . . 313Understanding what conditional sections do when you run a report . . . . . . . . . . . . . 314

About parallel sections. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315Placing a parallel section in a report design . . . . . . . . . . . . . . . . . . . . . . . . . . . 316Placing components in a parallel section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316Assigning flows to parallel subreports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317What parallel sections do when you run a report . . . . . . . . . . . . . . . . . . . . . . . . 317

About the table of contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318About table of contents properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318

ix

Developing a table of contents for grouped reports . . . . . . . . . . . . . . . . . . . . . . 318Developing a table of contents for other reports . . . . . . . . . . . . . . . . . . . . . . . . 320

Restructuring a large report. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321

Chapter 12Working with frames and controls . . . . . . . . . . . . . . . . . . . . . . . . 325About frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326About controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327

About data controls. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327About static controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328Understanding how controls affect report generation time . . . . . . . . . . . . . . . . . . 328

Placing frames in a report design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328Placing controls in a report design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330Setting display values for controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333

Using the ValueType property. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334Understanding Null values in control value expressions . . . . . . . . . . . . . . . . . . . 335Displaying data from a single column in a control . . . . . . . . . . . . . . . . . . . . . . . 335Displaying data from several columns in a control . . . . . . . . . . . . . . . . . . . . . . . 335Referencing data row variables or functions. . . . . . . . . . . . . . . . . . . . . . . . . . . 335Using methods or functions in a value expression . . . . . . . . . . . . . . . . . . . . . . . 336Displaying a value that is not from the data row . . . . . . . . . . . . . . . . . . . . . . . . 337Referencing controls in a value expression . . . . . . . . . . . . . . . . . . . . . . . . . . . 337Computing aggregates in a value expression . . . . . . . . . . . . . . . . . . . . . . . . . . 338

Comparing running and lookahead aggregates . . . . . . . . . . . . . . . . . . . . . . . 339Specifying lookahead aggregates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340Selecting specific rows to include in an aggregate . . . . . . . . . . . . . . . . . . . . . . 340Using the Distinct clause in a value expression . . . . . . . . . . . . . . . . . . . . . . . 340Using the Where clause in a value expression . . . . . . . . . . . . . . . . . . . . . . . . 346Calculating values efficiently. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347

Formatting data in a control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348Formatting frames and controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349

Moving or resizing a frame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349Placing a shadow behind a frame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350Specifying page breaks for frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350Drawing a border around a frame or control . . . . . . . . . . . . . . . . . . . . . . . . . . 350Rounding the corners of a frame or control . . . . . . . . . . . . . . . . . . . . . . . . . . . 350Truncating data in a single-line control. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351

Displaying an overflow character . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352Truncate data on the left, no ellipsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352Truncate data on the left, display ellipsis . . . . . . . . . . . . . . . . . . . . . . . . . . . 353Truncate data on the right, no ellipsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353Truncate data on the right, display ellipsis . . . . . . . . . . . . . . . . . . . . . . . . . . 354

Truncating text in a single-line control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354

x

Do not truncate text within a word . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354Truncate text within a word. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355

Truncating or wrapping text in a multiline control . . . . . . . . . . . . . . . . . . . . . . . 356Formatting a frame or control dynamically . . . . . . . . . . . . . . . . . . . . . . . . . . . 356

Providing help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357Providing context-sensitive help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357Providing balloon help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358

Hiding frames and controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359Working with image controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360

Setting the Embedded property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360Locating images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361

Locating images with Embedded property set to ImageDesignTime . . . . . . . . . . . 361Locating images with Embedded property set to ImageFactoryTime . . . . . . . . . . . 362Locating images with Embedded property set to ImageViewTime . . . . . . . . . . . . 362

Creating smaller ROX files containing images . . . . . . . . . . . . . . . . . . . . . . . . . . 363Creating images with the fewest colors needed . . . . . . . . . . . . . . . . . . . . . . . 363Referencing duplicated controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363Storing images in bitmap image controls . . . . . . . . . . . . . . . . . . . . . . . . . . . 363

Working with OLE controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364Understanding report document searching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366

About page headers and page footers in searches . . . . . . . . . . . . . . . . . . . . . . . . 367Using strategies to design searchable reports . . . . . . . . . . . . . . . . . . . . . . . . . . 368About search analysis. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368About searches in reports with parallel and sequential sections. . . . . . . . . . . . . . . . 373About SearchAlias . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375About SearchTag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375Using SearchTag. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376

Creating an index to improve search performance . . . . . . . . . . . . . . . . . . . . . . . . . 377About the LinkExp property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378

Triggering hyperlinks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378Understanding LinkExp syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378

About destination URL syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380About search expression syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381About dynamic report parameters syntax . . . . . . . . . . . . . . . . . . . . . . . . . . 383Calling JavaScript functions with LinkExp . . . . . . . . . . . . . . . . . . . . . . . . . . 386

Defining universal hyperlinks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386Designing a hyperlink URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387

Analyzing report data with e.Analysis. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388

Chapter 13Working with a dynamic text control . . . . . . . . . . . . . . . . . . . . . . 389About dynamic text controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390

Reviewing examples of dynamic text controls in reports . . . . . . . . . . . . . . . . . . . . 390

xi

Understanding supported text formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391Comparing a dynamic text control and a text control . . . . . . . . . . . . . . . . . . . . . 392

Understanding how Actuate generates content in a dynamic text control . . . . . . . . . . . 392Understanding the effects of Actuate’s generation techniques . . . . . . . . . . . . . . . . . . 394Placing a dynamic text control in a report design . . . . . . . . . . . . . . . . . . . . . . . . . 395Repositioning and resizing controls in a frame . . . . . . . . . . . . . . . . . . . . . . . . . . . 396

Understanding how Actuate resizes and repositions controls . . . . . . . . . . . . . . . . . 397Changing the default sizing and positioning of controls . . . . . . . . . . . . . . . . . . . . 399

Shrinking a dynamic text control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400Moving a control up when a dynamic text control above it shrinks . . . . . . . . . . . . 400Setting the maximum height of a dynamic text control . . . . . . . . . . . . . . . . . . . 401Resizing a control to match the size of a dynamic text control . . . . . . . . . . . . . . . 401Resizing a control relative to the size of the frame. . . . . . . . . . . . . . . . . . . . . . 402Positioning a control relative to the frame . . . . . . . . . . . . . . . . . . . . . . . . . . 403

Using dynamic text controls in nested frames . . . . . . . . . . . . . . . . . . . . . . . . . . 405Using dynamic text controls in different types of frames . . . . . . . . . . . . . . . . . . . 406

Using dynamic text controls in Content, Before, and After frames . . . . . . . . . . . . 406Using dynamic text controls in PageHeader frames . . . . . . . . . . . . . . . . . . . . . 406Using dynamic text controls in PageFooter frames . . . . . . . . . . . . . . . . . . . . . 407

Adjusting text formats for different rendering environments. . . . . . . . . . . . . . . . . . . 407Adjusting the space on the right of the text . . . . . . . . . . . . . . . . . . . . . . . . . . . 408Adjusting the space between lines of text . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408Adjusting the space between paragraphs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410Adjusting the space between tabbed text . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411

Controlling how a frame and its contents fit in multiple pages. . . . . . . . . . . . . . . . . . 413Specifying how a frame and its contents should split . . . . . . . . . . . . . . . . . . . . . 413

Splitting frames that contain dynamic text controls . . . . . . . . . . . . . . . . . . . . . 414Splitting frames that do not contain dynamic text controls . . . . . . . . . . . . . . . . . 415

Specifying an area of the frame that should not be split . . . . . . . . . . . . . . . . . . . . 417Setting margins for the segments of a split dynamic text control . . . . . . . . . . . . . . . 418Setting margins for the segments of a split frame . . . . . . . . . . . . . . . . . . . . . . . . 420Controlling how lines in a paragraph break . . . . . . . . . . . . . . . . . . . . . . . . . . . 421

Solving common output problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422

Chapter 14Understanding charting concepts . . . . . . . . . . . . . . . . . . . . . . . . 427About Actuate charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428

About the classes of charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428Recognizing the elements of a chart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429Understanding types of charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430Using a pie chart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432Using a bar, line, or tape chart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434

xii

Displaying data in a bar chart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434Displaying data in a line or tape chart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435

Using an area chart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437Using a scatter chart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437Using a high-low-close, open-high-low-close, or candlestick chart. . . . . . . . . . . . . . . . 438Working with time series in a chart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440Using a dual y-axis chart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441Understanding a hyperchart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442Accessing data for a chart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443

About the data stream for an AcDetailChart . . . . . . . . . . . . . . . . . . . . . . . . . . . 444About the data stream for an AcHLCChart . . . . . . . . . . . . . . . . . . . . . . . . . . . 444About the data stream for an AcSummaryChart . . . . . . . . . . . . . . . . . . . . . . . . 445

Chapter 15Presenting data in a chart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447About charts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448Creating a chart in a report design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448About the category axis in a chart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451About the value axis in a chart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453

Formatting the value axis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454Specifying a tick interval for the value axis . . . . . . . . . . . . . . . . . . . . . . . . . . . 455

Creating a pie chart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456Reviewing properties of a pie chart example . . . . . . . . . . . . . . . . . . . . . . . . . . 462

The query for a pie chart example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463SummaryChart properties for a pie chart example. . . . . . . . . . . . . . . . . . . . . . 463

Reviewing properties of an exploded pie chart example . . . . . . . . . . . . . . . . . . . . 465The query for an exploded pie chart example . . . . . . . . . . . . . . . . . . . . . . . . 465DetailChart properties for an exploded pie chart example . . . . . . . . . . . . . . . . . 466DetailChart methods for an exploded pie chart example . . . . . . . . . . . . . . . . . . 467

Creating a bar chart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 468Reviewing properties of a bar chart example . . . . . . . . . . . . . . . . . . . . . . . . . . 470

The query for an example bar chart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471SummaryChart properties for an example bar chart . . . . . . . . . . . . . . . . . . . . . 471SummaryChart methods for an example bar chart. . . . . . . . . . . . . . . . . . . . . . 474

Creating a line or tape chart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474Creating an area chart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 480Creating a scatter chart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 482Creating a high-low-close, open-high-low-close, or candlestick chart . . . . . . . . . . . . . . 484Creating a dual y-axis chart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 487

Setting required properties for a dual y-axis chart . . . . . . . . . . . . . . . . . . . . . . . 487Setting optional properties for a dual y-axis chart. . . . . . . . . . . . . . . . . . . . . . . . 488

xiii

Understanding limitations of a dual y-axis chart . . . . . . . . . . . . . . . . . . . . . . . . 490Creating a dual y-axis scatter chart example . . . . . . . . . . . . . . . . . . . . . . . . . . 490

The query for a dual y-axis scatter chart example . . . . . . . . . . . . . . . . . . . . . . 491Chart properties for a dual y-axis scatter chart example . . . . . . . . . . . . . . . . . . 491

Creating a dual y-axis bar chart example . . . . . . . . . . . . . . . . . . . . . . . . . . . . 494The multiple input data filter for a dual y-axis bar chart example . . . . . . . . . . . . . 495The variables for a dual y-axis bar chart example . . . . . . . . . . . . . . . . . . . . . . 496The Fetch( ) method for a dual y-axis bar chart example . . . . . . . . . . . . . . . . . . 496Chart properties for a dual y-axis bar chart example . . . . . . . . . . . . . . . . . . . . 497The Finish() method for a dual y-axis bar chart example . . . . . . . . . . . . . . . . . . 498

Creating a chart with time series . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 499Setting properties for a scatter chart using AcDetailChart class with times series . . . . . 500

Setting required properties for a scatter chart using AcDetailChart with time series . . 500Setting optional properties for a scatter chart using AcDetailChart with time series . . 502Calculating the x-axis starting and ending values . . . . . . . . . . . . . . . . . . . . . . 506

Creating scatter charts using AcDetailChart class with time series examples . . . . . . . . 507Creating a scatter chart using AcDetailChart class with a single time series example . . 508Creating a scatter chart using AcDetailChart class with multiple time series example . 510

Setting properties for a summary chart with times series . . . . . . . . . . . . . . . . . . . 513Setting required properties for a summary chart with time series . . . . . . . . . . . . . 513Setting optional properties for a summary chart with time series . . . . . . . . . . . . . 514Creating a summary chart with time series example . . . . . . . . . . . . . . . . . . . . 517

Comparing properties of detail and summary charts with time series . . . . . . . . . . . . 520Limitations of charts with time series . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 521

Creating a hyperchart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 521Rendering charts on Windows and UNIX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 524

Chapter 16Designing a page layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 527About pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 528

Understanding what pages do when you run a report . . . . . . . . . . . . . . . . . . . . . 528About types of page layouts Actuate provides . . . . . . . . . . . . . . . . . . . . . . . . . 529Page orientation and printing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 530

Setting paper size, orientation, and margins . . . . . . . . . . . . . . . . . . . . . . . . . . . . 531Setting up a page sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 534About subpages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 541Placing a subpage in a report design. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 541About flows. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 542

Placing a flow on a page or subpage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 543Setting page margins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 544Setting up multicolumn page layouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 545

Specifying headers and footers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 546

xiv

Specifying headers and footers in a page layout. . . . . . . . . . . . . . . . . . . . . . . . . 546Specifying headers and footers using slots . . . . . . . . . . . . . . . . . . . . . . . . . . . . 548Adding page numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 550Adding a date/time stamp. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 552

Designing letterheads, patterns, and other effects . . . . . . . . . . . . . . . . . . . . . . . . . 553Placing a title or logo on a page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 553Adding a background pattern to a page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 554

About Reportlets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 555Setting properties for a Reportlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 557

Setting visibility properties for a Reportlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . 558Setting the SearchValueExp property for a Reportlet . . . . . . . . . . . . . . . . . . . . . . 558

Extracting a Reportlet using a search URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 559Adding a Reportlet to a web page. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 561Working with a Reportlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 561

Printing and downloading a Reportlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . 561Enabling a hyperlink in a Reportlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 561Comparing Reportlets and DHTML reports functionality . . . . . . . . . . . . . . . . . 562

About printing and viewing a report across platforms . . . . . . . . . . . . . . . . . . . . . . 562Designing a report to print and display in multiple platforms . . . . . . . . . . . . . . . . . . 563Testing your report design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 564Understanding font issues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 565

When Actuate uses font information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 565How Actuate gets font information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 566

Font information in a report object executable file . . . . . . . . . . . . . . . . . . . . . . 566Font information in a customized font file . . . . . . . . . . . . . . . . . . . . . . . . . . 567Getting font information on Windows and UNIX servers. . . . . . . . . . . . . . . . . . 567Getting font information on desktop-only environments . . . . . . . . . . . . . . . . . . 567

Embedding font information in a report object executable file . . . . . . . . . . . . . . . . 568Defining font information in a customized font file . . . . . . . . . . . . . . . . . . . . . . . 568Using a customized font file on the server . . . . . . . . . . . . . . . . . . . . . . . . . . . . 572Using a customized font file on a desktop system. . . . . . . . . . . . . . . . . . . . . . . . 572

Chapter 17Presenting data in a crosstab report . . . . . . . . . . . . . . . . . . . . . . 575About crosstab reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 576

Comparing a crosstab report to a listing report . . . . . . . . . . . . . . . . . . . . . . . . . 576Understanding row and column keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 578About creating a crosstab report. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 578Understanding crosstab report limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . 579

Creating a crosstab report using Crosstab Builder . . . . . . . . . . . . . . . . . . . . . . . . . 580Organizing data in a crosstab report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 584

Modifying crosstab report grouping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 584Sorting rows and columns in a crosstab report . . . . . . . . . . . . . . . . . . . . . . . . . 585

xv

Modifying an aggregate function in a crosstab cell . . . . . . . . . . . . . . . . . . . . . . . 586Customizing the appearance of a crosstab report . . . . . . . . . . . . . . . . . . . . . . . . . 587

Customizing the appearance of a crosstab report . . . . . . . . . . . . . . . . . . . . . . . . 588Customizing an element in a crosstab report . . . . . . . . . . . . . . . . . . . . . . . . . . 590

Customizing borders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 590Customizing a row, a column, or a cell . . . . . . . . . . . . . . . . . . . . . . . . . . . . 592Customizing a value or a label . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 594

Understanding crosstab report sizing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 596

Chapter 18Designing a report parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . 599About report parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 600

About global and local parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 600About parameter types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 601About adding a parameter to a report design . . . . . . . . . . . . . . . . . . . . . . . . . . 601

Defining a parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 602Defining a property parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 603Defining a local parameter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 604Defining and configuring an ad hoc parameter . . . . . . . . . . . . . . . . . . . . . . . . . 605Defining a Boolean parameter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 607Defining a static parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 608

Creating a reference to a parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 611Modifying a parameter for the request page . . . . . . . . . . . . . . . . . . . . . . . . . . . . 613

Displaying a parameter using Parameter Editor . . . . . . . . . . . . . . . . . . . . . . . . 614Customizing a parameter using Parameter Properties . . . . . . . . . . . . . . . . . . . . . 614

Setting properties using Parameter Properties—General . . . . . . . . . . . . . . . . . . 615Setting options using Parameter Properties—Advanced . . . . . . . . . . . . . . . . . . 618Setting a default value for an ad hoc parameter . . . . . . . . . . . . . . . . . . . . . . . 624Sorting parameters on the request page. . . . . . . . . . . . . . . . . . . . . . . . . . . . 627

Saving parameter settings into an ROV . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 628Setting report parameter options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 632Deleting a parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 633Using parameters to manage a large report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 635

Appendix AUsing a configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 639About configuration files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 640Specifying the configuration file location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 641Creating a configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 641

Understanding XML basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 641Understanding configuration file sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . 642

Include section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 642

xvi

Design section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 642Runtime section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 642Search Path section. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 642

Reviewing a summary of configuration file syntax . . . . . . . . . . . . . . . . . . . . . . . 642Including another configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 644Including a library or Basic file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 644Specifying a template . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 645Specifying a database connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 645

The Type attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 646The Alias and Description attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 646The DefinedIn attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 646The IsDefault attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 647The Property element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 647

Setting connection properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 647Specifying a search path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 649

Working with a sample configuration file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 650Choosing a configuration file on the report wizard . . . . . . . . . . . . . . . . . . . . . . . . 651

Choosing from a list of predefined data sources. . . . . . . . . . . . . . . . . . . . . . . . . 652Choosing from a list of predefined databases . . . . . . . . . . . . . . . . . . . . . . . . . . 654

Connections defined in included libraries . . . . . . . . . . . . . . . . . . . . . . . . . . 654Connections defined with the DefinedIn attribute . . . . . . . . . . . . . . . . . . . . . . 655Connections defined in the Actuate Foundation Class . . . . . . . . . . . . . . . . . . . 656

Build a new database connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 656Using configuration files with Actuate 7 products . . . . . . . . . . . . . . . . . . . . . . . . . 657

Specifying a configuration file with e.Report Designer . . . . . . . . . . . . . . . . . . . . . 657Specifying a configuration file with an iServer . . . . . . . . . . . . . . . . . . . . . . . . . 657

Appendix BWorking with RTF and HTML tags in a dynamic text control. . . 659Working with RTF tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 660Working with HTML tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 663

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 667

I n t r o d u c t i o n xvii

I n t r o d u c t i o n

Understanding Actuate 7Actuate® is the leading provider of information application platform solutions for Global 9000 companies and packaged application software vendors. This release addresses two key needs presented by our customers:

■ Controlled empowerment of their users

■ Leveraging existing assets

In the current business climate, our customers need to reconcile reduced staffing and the ever-present IT backlog with the demand for increasingly complex and customized information.

Empowering the business user as a way to reduce IT backlog has always been an appealing solution. In this time of reduced staffing and project funding, the business user can then leverage information the IT staff develops to meet his additional, and perhaps unique, needs. At the same time, today’s information manager needs increased visibility into what his business users are doing with the information he provides because of internal requirement for greater accountability. For example, new SEC regulations add to the demand on the corporate information management infrastructure.

Actuate technology ensures that users have business agility: access to the right information in the right form to take the right action. Actuate customers also need tools that ensure IT organizations maintain the appropriate level of control over the corporate information assets. To meet these requirements, Actuate’s information application platform includes three key elements:

■ An information server

■ An information application development environment

■ User empowerment tools

xviii D e v e l o p i n g A d v a n c e d e . R e p o r t s

Addressing diverse customer profilesActuate’s customer list continues to include leaders in aerospace, commercial banking, defense, entertainment, federal government, financial services, health care, high technology, insurance, life sciences, pharmaceuticals, retail, securities, and telecommunications.

Our infrastructure software provides the foundation for applications that support business analysis, customer relationship management, customized interactive reporting, e.billing, e.procurement, executive dashboards, human resources, information portals, key performance indicators, service automation, spreadsheet reporting, supply chain management, and systems management. In the e.Business environment, our structured content technology seamlessly integrates into corporate web sites and packaged applications.

Addressing customer requirementsCustomers use Actuate 7 to retrieve business information from corporate databases. Capturing, validating, and storing information remain vitally important. In addition, customers now require an information application that takes their data and delivers it as interactive web pages and Excel spreadsheets that their customers, partners, and employees can use. Actuate customers need to:

■ Be able to combine data from multiple data sources associated with multiple transaction applications.

■ Have confidence in the consistency and maintainability of the Excel sheets on their business users’ desktops and their customers’ web pages.

Supporting international information delivery requirementsTo meet the growing international needs of our customer base, Actuate 7 continues to provide an unprecedented level of support for multilingual reporting including full Unicode support and an extensive list of locales.

Providing a scalable, high performance serverIndependent analysis confirms that Actuate iServer is a highly scalable, highly available, high-performance server that further extends our lead in implementing enterprise-class information delivery systems. Enhanced integration capabilities support personalized and customizable portal development, web services, and spreadsheet reporting.

I n t r o d u c t i o n xix

Providing a complete information delivery solutionActuate’s information application platform provides the content users need in the format in which they need it in a secure, timely, and cost-effective manner. In the following table, we summarize the three types of e.Business applications for which Actuate provides an opportunity for seamless integration through its application platform.

Actuate 7 continues to offer core solutions for fundamental enterprise reporting and information delivery challenges, as described in the following table.

Infrastructure element Function Actuate role

Databases Organize data. Actuate’s design tools support accessing, managing, and updating data.

Content management systems

Manage structured content.

Actuate iServer supports publishing structured content such as electronic catalogs.

Application servers Deploy online applications.

Actuate web applications, including Actuate Active Portal and Management Console, support conducting complex transactions, managing supply chains, and interacting with customers.

Challenge Actuate solution

Deliver high resolution information. Solve complex data access and presentation problems across a broad range of data sources.

View structured content. Support viewing DHTML and spreadsheet reports in standard browsers to eliminate plug-in installation for millions of users.

xx D e v e l o p i n g A d v a n c e d e . R e p o r t s

Introducing the Actuate 7 and ReportingEngines product suite

The following section describes the products available from Actuate Corporation.

Actuate End User Desktop

An application used by end users to request, generate, view, and print report documents. The ReportQuery™ capabilities enable seamless transfer of data from an Actuate report to any productivity or analysis tool.

Actuate e.Report Designer

An application that complements e.Report Designer Professional and supports business users in designing and distributing a variety of reports. These reports require no programming. This application supports both modifying complex reports and using sophisticated components from libraries.

Meet varied information display requirements.

Provide:■ Template-based design and

display.■ Complex formatting capabilities.■ Spreadsheet reporting.

Meet exploding requirements for web-based content delivery.

Support well over one million hits a day on a single CPU.

Deliver personalized, secure information.

Provide open security directory integration and page-level security.

Reuse existing integrated content. Provide access to content from other applications using open server technology.

Maintain data integrity between online and hard copy.

Provide high-resolution printed copy from PostScript and PDF.

Transfer information among applications.

Provide XML output to support access to data across applications.

Meet increasing requirements for server-based reporting

Support clustering and failover.

Challenge Actuate solution

I n t r o d u c t i o n xxi

Actuate e.Report Designer Professional

An object-oriented application used by professional developers of structured content to design, build, and distribute information objects and report object designs. The Actuate Basic Language and Actuate Foundation Class Library support extensive customization capabilities.

Actuate Client Integration Technology is part of Actuate e.Report Designer Professional and consists of the following products:

■ Actuate ActiveX Controls embed Actuate reporting functionality into custom applications.

■ Actuate Requester API accesses attributes and values of report parameters, changes the values of report parameters, controls how and when a report generates, displays and prints reports, and configures report print setup. Users access the Requester API using Actuate Basic, Visual Basic, C, or C++.

■ Actuate Search Extension API supports developing search extensions to transfer data to any third-party productivity or analysis tool.

■ Actuate information objects support retrieving information from data sources based on a predefined query. With the Actuate iServer Actuate Query Option, users can customize an information object's query to filter and sort the information retrieved from the data source.

Actuate e.Spreadsheet Designer

An application that supports designing, creating, and distributing custom spreadsheets over the web. Users can dynamically generate richly formatted Excel and spreadsheet-based reports from Actuate iServer. These spreadsheets can be part of an application, an applet, or a JavaBean.

Actuate iServer System

A server application that generates information objects and report documents, manages them in the Encyclopedia® volume, and makes them available to users. Actuate iServer System supports managing a cluster consisting of multiple Actuate servers. Actuate iServer System includes the following products:

■ Actuate Active Portal for JSP, Actuate Active Portal for .NET, and Actuate ReportCast™ transform the Encyclopedia volume into a dynamic, secure web site. They provide the foundation for Channels and seamless integration with other web sites.

■ Management Console, an application that system and network administrators use to manage and control one or more Actuate servers.

■ Actuate Server Integration Technology includes:

xxii D e v e l o p i n g A d v a n c e d e . R e p o r t s

■ Actuate Information Delivery API integrates Actuate web services into existing corporate applications, automates routine or time-consuming iServer integration tasks, and implements new feature groupings for custom business processes. The Actuate Information Delivery API is based on XML and supports the SOAP messaging protocol.

■ Actuate Report Server Security Extension supports the use of third-party security tools.

■ The Actuate archive driver supports the use of third-party archiving software and hardware.

■ Actuate Report Server API implements common Encyclopedia volume functionality using C++.

Actuate 7 supports the following iServer options:

■ Actuate e.Analysis Option

An application used to transform data from an Actuate report into interactive information. Users can view and analyze data to determine relationships and trends.

■ Actuate e.Report Option

A Basic and Java option that provides Encyclopedia volume functionality for e.Report Designer, e.Report Designer Professional, and Formula One e.Report Designer.

■ Actuate e.Spreadsheet Option

An open server application that generates Excel spreadsheets from e.Spreadsheet Designer files. Using this product, customers manage spreadsheet reports and analysis within the Actuate iServer and save Actuate reports as richly formatted Excel spreadsheets.

■ Actuate Query Option

A web-based tool that supports ad hoc queries based on predefined data streams.

■ Multi-Application Option

An option that supports using more than one Encyclopedia volume in the Actuate iServer System.

■ Page Level Security Option

An option that supports personalizing viewing privileges at the user level for reports and parts of reports.

■ Progress Option

A server application that supports working exclusively with Progress databases to generate Live Report Documents, manage them in the Encyclopedia volume, and make them available to users.

I n t r o d u c t i o n xxiii

Actuate Live Report Extension (LRX)

An application for end users that works with both Microsoft Internet Explorer and Netscape Navigator to support report viewing and printing on the web. Use Actuate LRX with Actuate ReportCast.

Actuate Viewer

An application end users can use to find, view, and print report documents.

Formula One e.Report Engine

A flexible Java tool for extracting, formatting, and delivering data from a variety of data sources including databases, Enterprise JavaBeans, Java objects inside applications, and text files. Users can deploy completed reports from any J2EE application, WebLogic, WebSphere, or web server in perfectly formatted, actionable DHTML, e-mail, HTML, PDF, and XML formats. The application data handler supports accessing Java objects inside applications. The reporting capabilities include extensive support for XML data sources and output.

This product includes the Formula One e.Report Designer, which is a report development application used by Java developers. The designer delivers DHTML, Excel, HTML, PDF, and XML reports in multiple viewing and printing formats.

Formula One e.Spreadsheet Engine

An application that supports creating, designing, and distributing custom spreadsheets over the web. Users can dynamically generate richly formatted Excel and spreadsheet-based reports. The application supports reading and writing fully formatted Excel files, a scalable calculation engine, standard spreadsheet formulas and functions, risk modeling, dynamic chart generation, and an embeddable spreadsheet interface.

About Actuate e.Report Designer Professional product

Actuate e.Report Designer Professional documentation includes printed manuals, installation guides, online help, user documentation as PDF and HTML files, and release notes. Information about the product that we cannot include before the book printing deadline is in the release notes.

The Actuate web site, http://www.actuate.com, contains late-breaking news about the product and its features as well as product update information. To obtain the password necessary to access the portion of the web site available

xxiv D e v e l o p i n g A d v a n c e d e . R e p o r t s

only to customers, telephone Actuate Customer Support. The engineers in Actuate Customer Support can also help you with technical questions about the product according to your service contract. The Customer Support telephone number and e-mail information can be found among the printed materials in the product box.

The Example folder in the product directory contains report examples. Each sample report folder contains a variety of files, often including a text file that discusses how the example works. In addition, Client Integration Technology includes sample applications. The samples demonstrate how to use the APIs.

The printed and online documentation includes the following manuals.

For information about this topic See the following resource

Installation Installation guide

Late-breaking information about the software and documentation

Release notes

Overview of Actuate reporting conceptsHow to build your first reportHow to design reports using the graphical user interface

Conceptual information about how to program with Actuate Foundation ClassesCustomizing e.reportsActuate Basic programming fundamentalsProgramming in the Windows environmentActuate’s C++ APIs

Accessing, viewing, running, printing and searching reports

Developing Advanced e.Reports

Developing Advanced e.Reports

Programming e.Reports

Using e.Reports

I n t r o d u c t i o n xxv

About Developing Advanced e.Reports Developing Advanced e.Reports provides information for using the e.Report Designer Professional graphical tools to design reports. This manual explains how to use and customize the design environment, and how to work with tools such as report components, report sections, and data streams.

Formatting report data for multiple localesUnderstanding report encodingDesigning reports with right to left orientation

Actuate Foundation Classes, their properties, variables, and methods

Actuate Basic statements and functions

Terminology mapGlossary

For information about this topic See the following resource

Working with Multiple Locales

Actuate Foundation Class Reference

Actuate Basic Language Reference

Actuate 7 Glossary

xxvi D e v e l o p i n g A d v a n c e d e . R e p o r t s

The Developing Advanced e.Reports guide includes the following chapters:

■ Introduction. This chapter provides an overview of this guide, the Actuate e.Report Designer Professional documentation, and the typographical conventions used.

■ Chapter 1. Designing an e.report with the report wizard. This chapter gets you started creating reports right away.

■ Chapter 2. Understanding the design process. This chapter explains the basic report-building concepts, such as object-oriented programming, and the report-building process.

■ Chapter 3. Understanding the design environment. This chapter provides a high-level overview of the e.Report Designer Professional tools and interface.

■ Chapter 4. Using Design Editor. This chapter describes how to use the Design Editor to work with components in a report design.

■ Chapter 5. Customizing the design environment. This chapter describes how to customize the e.Report Designer Professional tools.

■ Chapter 6. Working with libraries. This chapter describes how to publish reusable components in a library.

■ Chapter 7. Using a query data stream. This chapter describes how to define a graphical query data stream to select the database data the report will use.

■ Chapter 8. Working with an information object. This chapter describes how to create and modify an information object that displays data from a data source in columns and rows.

■ Chapter 9. Using Textual Query Editor. This chapter describes how to define a textual query data stream to select the database data the report will use.

■ Chapter 10. Designing a report that uses an SAP BW data stream. This chapter describes how to design reports that use SAP BW data streams to retrieve data from SAP BW BEx queries and SAP BW Operational Data Stores.

■ Chapter 11. Working with sections. This chapter describes the various section components and how to use them in a report design.

■ Chapter 12. Working with frames and controls. This chapter describes frames and controls and how to use them in a report design.

■ Chapter 13. Working with a dynamic text control. This chapter describes how to use dynamic text controls in a report design.

■ Chapter 14. Understanding charting concepts. This chapter describes the charting concepts and types of charts to use in a report design.

■ Chapter 15. Presenting data in a chart. This chapter describes the various chart controls and how to use them in a report design.

I n t r o d u c t i o n xxvii

■ Chapter 16. Designing a page layout. This chapter describes the various page components and how to use them in a report design.

■ Chapter 17. Presenting data in a crosstab report. This chapter describes how to design crosstab reports.

■ Chapter 18. Designing a report parameter. This chapter describes how to create report parameters for which users specify, at run time, values that determine the data to display in a report.

■ Appendix A. Using a configuration file.This appendix describes how to simplify administration of external files.

■ Appendix B. Working with RTF and HTML tags in a dynamic text control. This appendix lists the RTF and HTML tags supported by dynamic text controls.

Online documentationThe information in the printed manuals is also available as Adobe Acrobat PDF files and in the online help system for Actuate products. For products without a Windows interface, such as Actuate iServer System, we provide HTML help files. You can view these files using a standard web browser.

Using online manualsThe online manuals install automatically with the product in the Manuals directory. The items in the table of contents and the page numbers in the index both contain links to the appropriate topics in the text. In the index, you access the link by positioning the pointer over the page number, not the topic.

Using online helpActuate products provide both context-sensitive online help about the product and report-specific online help about the report you are viewing. Actuate 7 makes it possible for developers to create customized, report-specific online help.

xxviii D e v e l o p i n g A d v a n c e d e . R e p o r t s

Using context-sensitive online helpSections from the printed manuals link directly to the software interface to make relevant information available while you work. Dialogs that need additional explanation about how to use them have a help button. To access online help for other elements, use the Help menu on the menu bar or press F1.

Using the Actuate online help systemUse two panes to access and view information in the Actuate 7 help system. The left pane displays the table of contents or the index. The right pane displays the contents of the online help topics.

The tabs at the top of the left pane access different views. Use these tabs to switch views among Contents, Index, Search, and Favorites.

The following illustration shows an example of the index and the result of an index search.

I n t r o d u c t i o n xxix

The following illustration shows the result of a search as it appears in the left pane. To view the topic in the right pane, double-click the topic in the list. The topic appears in the right pane.

Type the keyword for which to search the index

Choose Index to view the topics

Select a topic from the list and choose Display to view its contents

Type the keyword for which to search

Select a topic from the list and choose Display to view its contents

Choose Search

xxx D e v e l o p i n g A d v a n c e d e . R e p o r t s

Using report-specific online helpDuring the design phase, report developers have the option of including report-specific online help. For example, the report developer can add comments to provide details about a specific report object or to explain a calculation.

For detailed information about report-specific online help, see Chapter 3, “Viewing an e.report,” in Using e.Reports.

Typographical conventionsThe following table describes the typographical conventions in this guide.

Report-specific online help

Item Convention Example

Code examples Sans serif Dim Text1 As String

File names Initial letter capitalized, except Formula One e.Report Designer, where file names are case sensitive

Detail.roi

Key combination A + sign between keys means to press both keys at the same time

Ctrl+Shift

Menu items Capitalized, no bold File

Submenu items Separated from the main menu item with a small arrow

File➛New

User input or user response

Sans serif M*16*

User input in XML and Java code

Italics chkjava.exe cab_name.cab

I n t r o d u c t i o n xxxi

Syntax conventionsThe following table describes the symbols used to present syntax.

Symbol Description Example

[ ] Optional item [Alias<alias name>]

Array subscript matrix[ ]

< > Argument you must supply

<expression to format>

Delimiter in XML <xsd:sequence>

{ } Groups two or more mutually exclusive options or arguments, when used with a pipe

{While | Until}

Defines array contents {0, 1, 2, 3}

Delimiter of code block public ACJDesigner( ){}

| Separates mutually exclusive options or arguments in a group

Exit {Do | For | Function | Sub}

Java OR operator int length |4

xxxii D e v e l o p i n g A d v a n c e d e . R e p o r t s

P a r t 1 , G e t t i n g s t a r t e d 1

P a r t

1Part 1Getting started

2 D e v e l o p i n g A d v a n c e d e . R e p o r t s

C h a p t e r 1 , D e s i g n i n g a n e . r e p o r t w i t h t h e r e p o r t w i z a r d 3

C h a p t e r

1Chapter 1Designing an e.reportwith the report wizard

This chapter contains the following topics:

■ About the sample database

■ Choosing the sample configuration file

■ Creating a quick report

■ Creating a listing report

■ Publishing a report object executable file to a server

■ Logging into a volume to manage files

■ Printing a report from a web browser

4 D e v e l o p i n g A d v a n c e d e . R e p o r t s

About the sample databaseIn this chapter, you learn to design:

■ A simple report, which uses a single table in a sample database.

■ A listing, or grouped, report, which uses three tables from the database.

■ An Information Object, which uses all tables from the database.

The data you work with in this chapter is drawn from a relational database called Quikdata.mdb. This database contains sales information for MultiChip Technology, a fictitious semiconductor manufacturer. Tables in the database record information about customers, sales representatives, order forecasts, line items, and so forth.

The finished Listing Report looks similar to the one in the following illustration.

C h a p t e r 1 , D e s i g n i n g a n e . r e p o r t w i t h t h e r e p o r t w i z a r d 5

The sample database, Quikdata.mdb, is already set up if you selected the installation of ODBC drivers when you installed Actuate e.Report Designer Professional. If you did not select the installation of ODBC drivers and you want to use the sample database or run the example reports, you have the following options:

■ Run the installation program again and select ODBC drivers.

■ Set up the ODBC data source manually. Choose this option if you already have ODBC drivers installed on your system that you do not want replaced by the ODBC drivers installation.

How to set up the data source manually

1 Install version 3.0 or higher of the Microsoft ODBC drivers if they are not already installed on your system.

2 From the Control Panel, select ODBC Data Sources. Or upon setup, select 32-bit ODBC Administrator in the ODBC program group.

ODBC Data Source Administrator appears.

3 Choose Add.

Create New Data Source appears.

4 In Create New Data Source, select Microsoft Access Driver from the Installed ODBC Drivers list.

5 Choose Finish.

ODBC Microsoft Access Setup appears.

6 In the Data Source Name field of the ODBC Microsoft Access Setup, type:

quikdata

7 In the Database section, choose Select.

Select Database appears.

8 Select the \Examples\Database subdirectory of the directory in which you installed Actuate e.Report Designer Professional.

9 Select Quikdata.mdb. Choose OK.

10 Choose OK to close the other dialogs.

For more information about setting up databases, see Chapter 7, “Using a query data stream.”

6 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Choosing the sample configuration fileThe configuration file provides database connections and data sources that you can use in your report designs. In the following examples, you use the sample configuration file in the \Program Files\Actuate7\Erdpro\Examples\ConfigurationFile folder.

How to choose the sample configuration file

1 From the task bar, choose Start➛Programs➛Actuate 7➛Actuate e.Report Designer Professional.

Actuate e.Report Designer Professional starts, and Welcome appears.

2 Choose Cancel.

3 Choose View➛Options.

Options—Design Editor appears.

4 Choose General.

Options—General appears.

5 In Configuration file, choose the Browse button, and navigate toC:\Program Files\Actuate7\ErdPro\Examples\ConfigurationFile.

6 Select Sample_configuration_file.xml, and choose Open.

7 In Options—General, choose Refresh.

Actuate e.Report Designer Professional reads the configuration file.

C h a p t e r 1 , D e s i g n i n g a n e . r e p o r t w i t h t h e r e p o r t w i z a r d 7

8 Choose OK to close the message.

9 Choose OK to close Options—General.

The connections and data sources in the configuration file are available to your report.

Creating a quick reportA Quick Report is a report that includes a single table or view and therefore involves no grouping or sorting. Using the Quick Report Wizard to create a report requires the following tasks.

■ Starting the report wizard.

■ Choosing Quick Report for the report type.

■ Choosing the data source for the Quick Report.

■ Choosing the table for the Quick Report.

■ Designing the Quick Report.

■ Finishing the report.

8 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Starting the report wizardTo start the report wizard in Actuate e.Report Designer Professional, choose File➛New. Create New Report appears.

Choosing Quick Report for the report typeWhen you choose to create a new report, Actuate e.Report Designer Professional offers you at least the following four options:

■ Quick Report

■ Listing Report

■ Blank Report

■ Component Library

The Quick Report and Listing Report options launch the report wizard. If you want to create a report without using the report wizard, choose Blank Report. For more information about the Blank Report option, see “Creating a new report design” in Chapter 4, “Using Design Editor.”

To create a component library, choose Component Library. For more information about creating a component library, see “Creating a component library” in Chapter 6, “Working with libraries.”

In addition, any templates included by the configuration file appear in the list. The sample configuration file provides a Sample Template.

C h a p t e r 1 , D e s i g n i n g a n e . r e p o r t w i t h t h e r e p o r t w i z a r d 9

How to create a Quick Report

1 In Create New Report, select Quick Report Wizard.

2 Choose OK.

The report wizard opens.

Choosing the data source for the Quick ReportYou can create a report from an existing data source, such as a query data stream or flat file. You also can choose an existing database connection or create a new database connection.

In the following example, you choose a database connection that comes from the configuration file.

10 D e v e l o p i n g A d v a n c e d e . R e p o r t s

How to choose a database connection

1 In Report Wizard—Data Sources, select the second option, Choose from a list of predefined databases. Then choose Next.

The wizard displays a list of database connections provided by the configuration file.

2 In Report Wizard—Choose Database, select Quikdata Sample Database. Choose Next.

C h a p t e r 1 , D e s i g n i n g a n e . r e p o r t w i t h t h e r e p o r t w i z a r d 11

Database Login appears. You do not need to enter a user name or password to access this database.

3 Choose OK.

Choosing the table for the Quick ReportNext, you choose the table to use in the report. All the fields in the table are added to the report. You can choose only one table for a Quick Report. To create a report using multiple tables or views, see “Creating a listing report,” later in this chapter.

The Table or View list shows the tables in the Quikdata database. For this example report, you use the Items table.

How to choose a database table

1 In Report Wizard—Select table, under Table or View, select Items.

2 Choose Next.

12 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Designing the Quick ReportYou can choose from three layout styles for your report. The layout page of the report wizard shows a representation of the style you choose. Choose each style in turn to see the representations.

For this example, you choose a Blocked layout style, with an 8 1/2 by 11 letter-size page and landscape orientation. In a blocked style report, fields are arranged left to right across the page with labels at the top. When no more space remains on a line, the next field is placed on the next line. Each label and field combination is outlined in a block. More data rows can fit on a page and wider columns are possible than in the aligned style.

How to choose a report layout

1 In Report Wizard—Choose Layout Style, under Available Layout Styles, select Blocked.

2 Set the paper size to 8 1/2 by 11 Letter.

3 Set orientation to Landscape.

4 Choose Next.

Finishing the reportOn the final page of the report wizard, you give the report a title and specify whether you want to display the report or modify its design. If you choose to display the report, Actuate e.Report Designer runs the report and displays the output. If you choose to modify the design, the report opens in Design Editor.

C h a p t e r 1 , D e s i g n i n g a n e . r e p o r t w i t h t h e r e p o r t w i z a r d 13

How to finish the quick report

1 In Report Wizard—Finish, type the following report title:

Item Report

2 Select Change the report design.

3 Choose Finish.

The report design appears in Design Editor. For information about modifying reports in Design Editor, see Chapter 4, “Using Design Editor.”

4 Choose File➛Save As.

14 D e v e l o p i n g A d v a n c e d e . R e p o r t s

5 Save the report design as Itemreport.rod.

6 Choose Report➛Build and Run.

7 When Requester appears, choose OK.

Status messages appear in the status line of the application window as Actuate e.Report Designer Professional prepares to run the report. Actuate e.Report Designer Professional writes and compiles the report based on the choices you made in the report wizard. The status line of the application indicates when compiling is complete. As soon as the first page is generated, the report appears in Report Viewer.

C h a p t e r 1 , D e s i g n i n g a n e . r e p o r t w i t h t h e r e p o r t w i z a r d 15

Creating a listing reportIn this section, you learn how to create a listing report using the report wizard. A listing report, also known as a grouped report, uses multiple database tables. With a listing report, you have more control over the grouping and sorting of the report than when you create a quick report.

About the sample listing reportThe following illustration shows the report you create in this section. It is a typical grouped report. The report shows orders placed by customers and the totals for each order and each customer.

16 D e v e l o p i n g A d v a n c e d e . R e p o r t s

The following are the tasks involved in creating a listing report:

■ Starting the wizard.

■ Choosing a listing report for a report type.

■ Choosing the data source for a listing report.

■ Choosing the tables and fields.

■ Organizing the data by table.

■ Organizing the data by field.

■ Adding summary data.

■ Sorting the detail rows.

■ Designing the Quick Report.

■ Saving the report design.

■ Running the report.

Starting the wizardTo start the report wizard, choose File➛New.

Choosing a listing report for a report typeWhen you choose to create a new report, Actuate e.Report Designer Professional offers you at least four options:

■ Quick Report

■ Listing Report

■ Blank Report

■ Component Library

If you want to create a report without using the report wizard, choose Blank Report. For more information about the Blank Report option, see “Creating a new report design” in Chapter 4, “Using Design Editor.” To create a component library, choose Component Library. For more information about creating a component library, see “Creating a component library” in Chapter 6, “Working with libraries.”

In addition, any templates included by the configuration file are listed. The sample configuration file provides a Sample Template. In this example, you create a Listing Report.

C h a p t e r 1 , D e s i g n i n g a n e . r e p o r t w i t h t h e r e p o r t w i z a r d 17

To choose a report type, select Listing Report Wizard. Choose OK.

Report Wizard—Data Sources appears.

Choosing the data source for a listing reportYou can create a report from an existing data source, such as a query data stream or flat file. As an alternative, you can choose an existing database connection or create a new database connection. In this example, you choose a database connection the configuration file provides.

18 D e v e l o p i n g A d v a n c e d e . R e p o r t s

How to choose a data source

1 In Report Wizard—Data Sources, select the second option, Choose from a list of predefined databases. Then choose Next.

Report Wizard—Choose Database displays a list of database connections the configuration file provides.

2 In Report Wizard—Choose Database, select Quikdata Sample Database. Then choose Next.

Database Login appears. You do not need a user name or password to access this database.

3 Choose OK.

Report Wizard—Select Fields appears.

Choosing the tables and fieldsAfter logging in to the database, you begin writing the query that specifies which data to retrieve. You start by choosing the tables or views that contain

C h a p t e r 1 , D e s i g n i n g a n e . r e p o r t w i t h t h e r e p o r t w i z a r d 19

the information you want in your report. You also choose the fields from the tables or views. The Table or View list shows the tables and views in the sample database.

For this report, you use fields from the Customers, Orders, and Items tables. The order in which you select the fields determines their display order in the report.

To add a field from a table, choose the table, choose the field from the Available Fields list, and choose Add (>). To add all the fields from a table, choose the table and choose Add All (>>). To remove a field from the Selected Fields list, select the field and choose Remove (<). To remove all fields from the list, choose Remove All (<<).

Actuate e.Report Designer Professional creates the joins between the tables on the appropriate columns. In this case, the joins are between the Customers and Orders tables on the Customer_ID custID column and between the Orders and Items tables on the Order_ID orderID column. For more information about joins, see “Creating joins” in Chapter 7, “Using a query data stream.”

How to choose tables and fields for a report

1 In Report Wizard—Select Fields, under Table or View, select the customers table. Choose Add All (>>).

All the fields from the customers table move to the Selected Fields list.

2 Repeat Step 1 for the Orders and Items tables.

3 Choose Next.

20 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Organizing the data by tableYou determine a report’s structure by grouping the data. A group is a set of data rows that have one or more field values in common. A structured group allows you to group by table rather than by field. A structured group is based on the joins between the tables you chose on the Select Fields page.

For example, in a database with two tables, customers and orders, there are two possible structures. You could design a report that lists orders, with the customers grouped by order. For this report, you would choose the orders table as a structured group. In the following example, you design a report that lists customers with the orders grouped by customer. For this report, you choose the customers table as a structured group.

How to organize data by table

1 In Report Wizard—Specify Grouping, in the left pane, select customers. Choose Add (>).

All the fields in the Customers table are added to the Before frame for the group. The Before slot contains text or data that appears at the beginning of a report or section of a report, such as a column heading.

2 Select orders and choose Add (>).

Specify Grouping looks like the one in the following illustration.

3 Choose Next.

C h a p t e r 1 , D e s i g n i n g a n e . r e p o r t w i t h t h e r e p o r t w i z a r d 21

Organizing the data by fieldAfter you create the structured groups, you can further organize the data by field.

How to organize data by field

In the second Report Wizard—Specify Grouping page, the pane on the left shows the fields you are using in the report. The pane on the right shows the groups in which the fields appear.

1 Select country from the list on the left. Choose Add (>).

2 Select creditrank from the list on the left. Choose Add (>).

3 Select status from the list on the left. Choose Add (>).

Report Wizard—Specify Grouping looks like the one in the following illustration.

Adding summary dataAfter you organize the data by field, add totals for each group.

How to add summary data

1 In Report Wizard—Specify Grouping, choose Summary Options.

Report Totals appears.

2 For the extprice field, select Sum.

22 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Extprice is equal to (pricequote * quantity), so Sum(extprice) gives the total for each group.

3 Choose OK.

4 Choose Next.

Sorting the detail rowsAs the default behavior, the groups in a report are sorted in ascending order by group key. In this report, the customer groups are sorted by customer ID and the order groups are sorted by order ID, from smallest to largest. To sort the detail rows in each group, you must select the field or fields to sort by. In this report, you sort the detail rows by itemcode.

How to sort the detail rows

1 On Report Wizard—Data Sorting, select the first drop-down arrow.

The detail data fields are listed.

2 Select the itemcode field.

C h a p t e r 1 , D e s i g n i n g a n e . r e p o r t w i t h t h e r e p o r t w i z a r d 23

3 Accept the default setting Asc. Choose Next.

Designing the Listing ReportIn this section, you design the Listing Report.

How to design the Listing Report

1 In Report Wizard—Choose Layout Style, under Available Layout Styles, select Tabular—Stepped.

2 Accept the default paper size of 8 1/2 by 11 Letter.

24 D e v e l o p i n g A d v a n c e d e . R e p o r t s

3 Accept the default orientation, Portrait.

4 Choose Next.

Report Wizard—Finish appears.

Saving the report designBefore you finish the report design, save it.

How to save the report design for the listing report

1 On Report Wizard—Finish, type the following report title:

Order Totals

2 Select Change the report design. Choose Finish.

C h a p t e r 1 , D e s i g n i n g a n e . r e p o r t w i t h t h e r e p o r t w i z a r d 25

The report design appears in Design Editor.

3 Choose File➛Save As.

Save As appears.

4 Enter a file name for the report file, such as Ordertotals.rod. This file name does not have to be the same as the report title but it must have the extension .rod.

26 D e v e l o p i n g A d v a n c e d e . R e p o r t s

In report design file names, you cannot use a semicolon (;), colon (:), question mark (?), backslash (\), or slash (/). You can use a period (.) only preceding the file extension (rod).

5 Choose a location for the report file.

6 Choose Save.

Running the reportAfter you finish the design and save it, you run the report, which compiles the report object executable (.rox) file and generates the report object instance (.roi) file.

How to run the listing report

1 In Actuate e.Report Designer Professional, choose Report➛Build and Run.

Requester appears.

2 Choose OK.

Status messages appear in the status line of the application window as Actuate e.Report Designer Professional prepares to run the report. e.Report Designer Professional writes and compiles the report based on the choices you made in the report wizard. The status line of the application indicates when compiling is complete. As soon as the first page generates, the report appears in Report Viewer.

C h a p t e r 1 , D e s i g n i n g a n e . r e p o r t w i t h t h e r e p o r t w i z a r d 27

Publishing a report object executable file to a serverUsing a server profile created in e.Report Designer Professional, you can choose Publish Report Executable to Server to quickly publish a report object executable (.rox) file or data object executable (.dox) file to an Encyclopedia volume and preview the generated DHTML report in DHTML Viewer. Previewing a report object instance (.roi) file or data object instance (.doi) file in DHTML Viewer simulates a user’s web-viewing environment to verify your report’s appearance.

To publish a report object executable (.rox) file to a server and preview the report in DHTML Viewer requires:

■ A report object design (.rod) file open in e.Report Designer Professional

■ A connection to an Actuate iServer installation and application server

■ Access to an Actuate Management Console installation

You can create a server profile for each volume and folder on a server where you publish reports. When you publish an report object executable (.rox) file or data object executable (.dox) file, you can set the publish and preview options you require for that specific report.

Creating a server profileIn Actuate e.Report Designer Professional, you can use the publish tool to select an iServer and volume on which to publish a report object executable (.rox) file or data object executable (.dox) file. Save your server and volume options using a server profile name to support quickly publishing a report executable file and previewing its report in DHTML Viewer.

The information you need to set up the server profile appears in the following table.

Profile item Description

Profile name Descriptive name for the server profile

Application server and Port

Machine name and port number for the application server

Context path Part of the Actuate Management Console URL that specifies the volume administration path, such as /acadmin

iServer and Port Machine name and port number for the iServer

Volume name Name of the Encyclopedia volume

28 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Server Profile displays sample settings for an ROX or DOX to upload to the ~/MyReports/Test folder in the Enterprise_2 volume in the following illustration.

For more information about managing server profiles, see “Managing server profiles,” in Chapter 5, “Customizing the design environment.”

User name User name to use to log into the Encyclopedia volume

Password Password to use to log into the Encyclopedia volume

Destination folder Folder into which you want to upload the report object executable (.rox) file or data object executable (.dox) file, such as ~ for the current user’s home folder or /Test/Profile1 for the Profile1 folder in the Test folder at the Encyclopedia volume’s root level. You can choose Browse to navigate to an available folder.For more information about working with folders, see Chapter 2, “Accessing an Encyclopedia volume,” in Part 2, “Using and deploying an e.report with Actuate Management Console,” in Using e.Reports.

Profile item Description

C h a p t e r 1 , D e s i g n i n g a n e . r e p o r t w i t h t h e r e p o r t w i z a r d 29

From e.Report Designer Professional, you can use a server profile with Management Console to log into an Encyclopedia to manage files. For more information about accessing Management Console from e.Report Designer Professional, see “Logging into a volume to manage files,” later in this chapter.

How to test a server profile

1 To create a server profile, provide the Profile details in Server Profile.

For more information about creating a server profile, see “Creating a server profile,” earlier in this chapter.

2 Choose Test.

e.Report Designer Professional tests the server connection using the values you provided to connect to the server and displays a confirmation message. Choosing Test does not verify the presence of the folder you provided in Destination folder.

Setting publish and preview optionsIn Publish and Preview Options, you can set a server profile name and destination folder in the Encyclopedia volume to which you publish a report object executable (.rox) file or data object executable (.dox) file.

Descriptions of the available settings in Publish and Preview Options appear in the following table.

Option group Option Description

iServer profile information

Profile name Select a server profile name from the drop-down list or choose Add to create a new server profile name to which to publish an ROX or DOX. For information about the values to provide in Server profiles, see “Creating a server profile,” earlier in this chapter

Use this profile as default

Select to use this server profile name as the default setting for the File➛Publish to Server command and Publish Report Executable to Server.

Destination folder

Type a path to a folder or choose Browse to access iServer Folder Browser in which you navigate to and select a folder in an Encyclopedia volume.

30 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Use this destination folder as default

Select to use this destination folder as the default setting for the File➛Publish to Server command and Publish Report Executable to Server.

Publish options

Publish only Select to upload the ROX or DOX to an Encyclopedia volume.Selecting this option supports publishing an ROX or DOX to the server by choosing Publish Report Executable to Server if you select the following options in iServer profile information:■ Use this profile as default■ Use this destination folder as defaultAfter you set up the server profile and options in Publish and Preview Options, choosing Publish Report Executable to Server publishes the ROX or DOX to the server and displays a confirmation.

Publish and preview

Select to upload the ROX or DOX to the volume, run it synchronously, and display it in DHTML Viewer.Selecting this option supports publishing an ROX or DOX to the server by choosing Publish Report Executable to Server if you select the following options in iServer profile information:■ Use this profile as default■ Use this destination folder as defaultYou can view multiple DHTML Viewer instances by selecting the ROD and choosing Publish Report Executable to Server to display each new instance.Publish and preview does not support reading a report object values (.rov) file to provide parameter values. For more information about ROV files, see “Setting report parameter options,” in Chapter 18, “Designing a report parameter.”

Option group Option Description

C h a p t e r 1 , D e s i g n i n g a n e . r e p o r t w i t h t h e r e p o r t w i z a r d 31

How to publish a report executable file to a server

For more information about the options and values you can use in Publish and Preview Options and Server Profile, see “Creating a server profile” and “Setting publish and preview options,” earlier in this chapter

1 With a report design (.rod) file open in Actuate e.Report Designer Professional, choose File➛Publish to Server.

Publish and Preview Options appears.

2 In iServer profile information, complete the following tasks:■ To use an existing profile, in Profile name, select a profile from the drop-

down list.■ To add a new profile, choose Add.

In Server Profile, provide the information to connect to the Encyclopedia volume on which you want to publish the report executable file then choose OK.

Publish and show folder contents.

Select to upload the ROX or DOX to the Encyclopedia volume and display the folder contents in Management Console.

Version options

Replace the latest version

Select to replace the latest ROX or DOX version in the folder. To display a warning prompt before overwriting an existing version if you select this option, select Display warning before replacing.

Create a new version

Select to create a new version of the ROX or DOX.

Copy properties from the latest existing version

Description Select to copy the description.

Permissions Select to copy the permissions.

Auto archive rules

Select to copy the auto-archive rules.

Locale From the drop-down list, select a locale format in which to display the generated report.

Option group Option Description

32 D e v e l o p i n g A d v a n c e d e . R e p o r t s

■ In Destination folder, type a path to a folder in an Encyclopedia volume.

Alternatively, choose Browse to navigate to and select an iServer folder, as shown in the following illustration. Then choose OK.

3 In Publish options, select one of the following options:■ Publish only■ Publish and preview ■ Publish and show folder contents

To remove the server profile in Profile name, choose Delete

To display the list of server profiles, choose the arrow

C h a p t e r 1 , D e s i g n i n g a n e . r e p o r t w i t h t h e r e p o r t w i z a r d 33

4 In Version options, select one of the following options:■ Replace the latest version■ Create a new version

5 To copy properties to the report object executable (.rox) file or data object executable (.dox) file from an existing version in the folder, select the following options:■ Description■ Permissions

■ Auto archive rules

6 In Locale, select a locale from the list.

Choose OK.

The ROX or DOX file uploads to the server. If you selected Publish and preview in Publish and Preview Options and the report contains parameters, a request page appears for your parameter values. For this Ordertotals.rox example, choose Submit. The report runs synchronously and appears in DHTML Viewer in e.Report Designer Professional.

For more information about creating the listing report used in this example, see “Creating a listing report,” earlier in this chapter.

34 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Logging into a volume to manage filesFrom e.Report Designer Professional, you can use Management Console with a server profile to log into an Encyclopedia volume to manage files. A server profile supports accessing a specific folder in an Encyclopedia volume. You cannot access Management Console’s system administration using a server profile name.

For more information about server profiles, see “Publishing a report object executable file to a server,” earlier in this chapter. For more information about using Management Console to manage files in an Encyclopedia volume, see Chapter 2, “Accessing an Encyclopedia volume,” in Part 2, “Using and deploying an e.report with Actuate Management Console,” in Using e.Reports.

How to log into a volume using a server profile

1 In e.Report Designer Professional, choose File➛Management Console.

Management Console appears.

2 In Specify profile name or URL do one of the following:■ Select a server profile name or Management Console URL from the list.■ Type a server profile name or Management Console URL.■ To display Server Profile to create a new server profile, choose Add.

Server Profile appears.

For more information about creating a server profile, see “How to publish a report executable file to a server,” earlier in this chapter.

Choose OK.

Management Console—Files and Folders appears in your web browser, displaying the Encyclopedia volume that the server profile or Management Console URL specifies.

C h a p t e r 1 , D e s i g n i n g a n e . r e p o r t w i t h t h e r e p o r t w i z a r d 35

Printing a report from a web browserAfter running a report object executable (.rox) file on a server and viewing the report object instance (.roi) file in DHTML format, you can print the report object instance (.roi) file from your web browser.

If you do not have a printer set up, you can download the report object instance (.roi) file as a PDF file for viewing in Adobe Acrobat Reader. For more information about downloading and viewing a report object instance (.roi) file as a PDF file, see Chapter 6, “Printing and distributing an e.report,” in Part 3, “Using an e.report with desktop applications,” in Using e.Reports.

How to print a DHTML report from a web browser

If you have a DHTML report open in your web browser, follow these steps to print the document without saving it to your system.

1 Choose Print.

The report generates in Adobe Acrobat PDF format and appears in a new web browser window.

Print appears, as shown in the following illustration.

If you use a Netscape web browser, to display Print, choose Print from the Adobe Acrobat Reader toolbar.

36 D e v e l o p i n g A d v a n c e d e . R e p o r t s

2 Select a printer and set the necessary options.

Preview displays the report layout.

Choose OK.

The printer prints the report document.

P a r t 2 , U s i n g t h e d e s i g n e n v i r o n m e n t 37

P a r t

2Part 2Using the design

environment

38 D e v e l o p i n g A d v a n c e d e . R e p o r t s

C h a p t e r 2 , U n d e r s t a n d i n g t h e d e s i g n p r o c e s s 39

C h a p t e r

2Chapter 2Understanding the

design processThis chapter contains the following topics:

■ About the report design process

■ Understanding how Actuate builds a report

■ Building a report from the command line

■ About components

■ About Actuate’s object-oriented design

40 D e v e l o p i n g A d v a n c e d e . R e p o r t s

About the report design processThe following paragraphs summarize the tasks involved in creating a report design for the web. These tasks are part of building a report using any of the three tools Actuate 7 provides: e.Report Designer, e.Report Designer Professional, and e.Report Designer Java Edition.

You do not necessarily have to perform the steps in the order in which they are presented here. You can perform most of these tasks through the visual interface provided by Design Editor, which is introduced in “About Design Editor” in Chapter 3, “Understanding the design environment.”

Setting up the report project

Start Actuate e.Report Designer Professional. Use the report wizard to choose the type of report you want to build. Start a new report design, or open an existing design. Include other designs or component libraries in the project. For more information about creating a report, see Chapter 4, “Using Design Editor.” For more information about using libraries, see Chapter 6, “Working with libraries.”

Choosing data

Choose the source of information for the report. You can use databases or flat files as data sources. Set up the database connection, and write or edit the query. For more information about specifying data, see Chapter 7, “Using a query data stream” or Chapter 9, “Using Textual Query Editor.”

Creating sections

Use sections to create the logical structure that holds and organizes the information in the report. For example, a section can group rows by company in a grouped report. For more information about sections, see Chapter 11, “Working with sections.”

Creating frames and controls

Use frames and controls to display data. For example, a frame might contain text controls to display a customer name and phone number. For more

Start

Setup

Frames Properties

Pages Methods

Running

Sections Debugging

ViewingData

Finish

Web

C h a p t e r 2 , U n d e r s t a n d i n g t h e d e s i g n p r o c e s s 41

information about frames and controls, see Chapter 12, “Working with frames and controls.”

Creating page layouts

Use one of the page layouts provided by Actuate, or design your own page layout. Create the margins, flows, and other page layout features of the report. The page design can also include text and illustrations, such as a company logo. This step is similar to creating a page template in a word processing program. For more information about page design, see Chapter 16, “Designing a page layout.”

Setting properties

Use properties to customize the appearance and other characteristics of the report. For example, you can set the font size for text control or specify the user name and password for a database connection. You also use properties to specify the display values of controls, such as text and numbers. For more information about setting properties, see “Setting properties of components” in Chapter 4, “Using Design Editor.”

Programming methods (optional)

Write Actuate Basic procedures to modify the behavior of a component. For more information about methods, see Chapter 16, “Writing and using a procedure,” in Programming e.Reports.

Building and running the report

Build code that implements your report object design (.rod) file and generates Actuate Basic code (.bas) and the report object executable (.rox) file. When you run the report object executable (.rox) file to produce the report object instance (.roi) file, you complete the report-run phase. For more information about running reports, see Using e.Reports.

Debugging the report

Fix errors in your design or in your method code. For more information about debugging, see Programming e.Reports.

Viewing the report

View the report and test your design. After viewing, you can return to the previous tasks to fix errors or make improvements. For more information about viewing reports, see “About Report Viewer” in Chapter 3, “Understanding the design environment.”

42 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Testing the report on the web

Add the report to a Encyclopedia volume that is accessible through a web server using Actuate Active Portal. View the report with a web browser. The report should look the same in your web browser as it does in Report Viewer. After viewing, you can go back to the previous steps to fix errors or make improvements. For more information about viewing reports on the web, see Chapter 3, “Viewing and printing a report,” in Using e.Reports.

Understanding how Actuate builds a reportWhen you create and save a report design, you save the design in a report object design file, or .rod. You then build, run, and view the report to see current data in a finished version of the report. This section describes what happens internally as Actuate e.Report Designer Professional takes the report from the design stage to the finished report.

The finished report object instance (.roi) file, contains data and can be viewed or printed.

The following illustration shows the report building process and the files that Actuate e.Report Designer Professional creates after each action.

Choosing Report➛Build and Run executes all the steps shown in the illustration, from Generate .bas code to view.

The following sections describe the steps in more detail.

Generating and compiling codeWhen you build the report, Actuate writes Actuate Basic code and saves it in a Basic source (.bas) file. The Basic source file contains Actuate Basic code, including class declarations, that corresponds to the information in the report object design (.rod) file.

From the Basic source file, Actuate e.Report Designer Professional builds a report object executable (.rox) file. You run the ROX file to create the finished report for viewing or printing.

You can use Basic source files to track the changes in a report design. Comparing the Basic source files for two versions of a report design shows the

Design Generate .bas code

Run View

.roi.rox.bas.rod

Build .rox

C h a p t e r 2 , U n d e r s t a n d i n g t h e d e s i g n p r o c e s s 43

differences between the versions. You can view the Basic source file in any word processor or text editor.

Looking at the generated code is a good way to learn Actuate Basic and understand how Actuate e.Report Designer Professional creates reports. You cannot, however, compile the code in an environment other than Actuate.

How to generate and compile code for a report object design file

Choose Report➛Build and Run.

Actuate e.Report Designer Professional writes new Actuate Basic code on the current version of your report object design (.rod) file, saves it in a new Basic source (.bas) file, then compiles the source file into a report object executable (.rox) file.

How to build a report object executable file without running it

You can build a report object executable (.rox) file from a report object design (.rod) file without running the executable file.

1 Open a report object design (.rod) file.

2 Choose Report➛Build.

e.Report Designer Professional builds the report object executable (.rox) file and saves it in the folder that contains the report object design (.rod) file.

Building and running the report object executable (.rox) fileWhen you build and run the report object executable(.rox) file, Actuate e.Report Designer Professional performs the following actions:

1 Builds the report object executable (.rox) file. Some of the tasks Actuate e.Report Designer Professional performs include instantiating classes and retrieving data from specified sources.

2 Creates a report object instance (.roi) file, which is made up of objects that store the finished report’s structure and data.

3 Opens the Viewer window, which displays the report object instance (.roi) file.

How to run the report object executable (.rox) file

Choose Report➛Refresh Data or Report➛Build and Run.

When you choose Report➛Refresh Data, Actuate e.Report Designer Professional runs an existing report object executable (.rox) file to create a

44 D e v e l o p i n g A d v a n c e d e . R e p o r t s

report object instance (.roi) file or viewing. If there is no existing ROX file, this process creates one for you.

You can choose Report➛Build and Run or choose the Build and Run icon whether or not you know the report object executable (.rox) file needs to be rebuilt. The process can detect whether the report needs to be rebuilt. The ROX might need to be rebuilt if parameters have changed in the report design or if a Basic file included in the report design has changed.

If the ROX needs to be rebuilt, Actuate e.Report Designer Professional goes through the entire report building process. That is, it generates the Actuate Basic code, compiles the code into an ROX, then runs the ROX to create the report for viewing.

If the ROX does not need to be rebuilt, only the run and view cycles are activated.

How to locate a report executable file from the report object instance file

When you open a report object instance (.roi) file without specifying the report object executable (.rox) file by its full path, e.Report Designer Professional searches the following directories in this order:

■ Directory that contains the report object instance (.roi) file

■ Global search path

For information about the global search path, see “How to set a global search path” in Chapter 5, “Customizing the design environment.”

■ Configuration file search path

For information about the configuration file search path, see “Specifying a search path,” in Appendix A, “Using a configuration file.”

■ Directory that contains the report object design (.rod) file

Developing reports with sets of parametersWhen you build, run, and debug reports, it can be helpful to save sets of parameters into one or more report object values (.rov) files. For information about saving parameters into different files, see “Saving parameter settings into an ROV” in Chapter 18, “Designing a report parameter.”

How to locate a report executable file from the report object values file

When you open a report object values (.rov) file without specifying the report object executable (.rox) file, Actuate e.Report Designer Professional searches the following directories in this order to locate the ROX:

C h a p t e r 2 , U n d e r s t a n d i n g t h e d e s i g n p r o c e s s 45

■ Directory that contains the report object values (.rov) file

■ Global search path

For information about the global search path, see “How to set a global search path,” in Chapter 5, “Customizing the design environment.”

■ Configuration file search path

For information about the configuration file search path, see “Specifying a search path” in Appendix A, “Using a configuration file.”

Building a report from the command lineThe erdpro command in DOS starts e.Report Designer Professional. If you specify a report object design (.rod) file, the erdpro command opens that file in Design Editor. If the name of the report object design (.rod) file contains one or more spaces, enclose the file name in quotation marks as shown in the following example:

"My Design.rod"

In a typical installation, the erdpro command is located in the \Program Files\Actuate7\Erdpro\Bin directory. One set of syntax for this command is the following:

erdpro -b File1.rod [File2.rod...Filen.rod]

The -b option opens e.Report Designer Professional to rebuild the report object executable (.rox) file and then closes the application. Without the -b option, e.Report Designer Professional simply opens the specified report object (.rod) design file.

Another set of syntax for this command includes the -f option:

erdpro -b File1.rod [File2.rod...Filen.rod] -f Filename.log

The -f option works only in conjunction with the -b option. If you use -f, you must follow it with Filename.log. The -b and -f combination in the erdpro command syntax does the following:

■ Opens e.Report Designer Professional.

■ Builds the files you specify.

■ Closes e.Report Designer Professional.

■ Writes information about the factory processes into the log file you specify. You can read the log file with your text editor.

For more in-depth information about factory processes, see Chapter 5, “Understanding document generation,” in Programming e.Reports.

46 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Another set of syntax for this command is the following:

erdpro -r File1.rod [File2.rod...Filen.rod]

The -r option:

■ Opens e.Report Designer Professional.

■ Builds and runs the report object executable (.rox) file.

■ Saves the report design.

■ Closes e.Report Designer Professional.

Use the -u option to update a report object design (.rod) file or component library, report object library (.rol) file, to use relative file paths.

erdpro -u File1.rod [File2.rod...Filen.rod] File1.rol [File2.rol...Filen.rol]

The -u option rebuilds the report object executable (.rox) file. The -u option can be used with other command line options.

You can use these commands to convert report designs to the current Actuate release.

Examples

To open the designer to display Detail.rod, type the following at the prompt:

C:\Program Files\Actuate7\Erdpro\Bin>

erdpro “C:\Program Files\Actuate7\Erdpro\Examples\Detail\Detail.rod”

To open e.Report Designer Professional, build Detail.rox, and close e.Report Designer Professional, add -b to your syntax:

C:\Program Files\Actuate7\Erdpro\Bin>

erdpro -b “C:\Program Files\Actuate7\Erdpro\Examples\Detail\Detail.rod”

To open e.Report Designer Professional, build Detail.rox, place information about updating the report design in a file named Updated.log, and close e.Report Designer Professional, type the following at the DOS prompt:

C:\Program Files\Actuate7\Erdpro\Bin>

erdpro -b “C:\Program Files\Actuate7\Erdpro\Examples\Detail\Detail.rod” -f Updated.log

In this example, the command rebuilds Detail.rox and creates the file Detail.bas.

C h a p t e r 2 , U n d e r s t a n d i n g t h e d e s i g n p r o c e s s 47

To open e.Report Designer Professional, build and run Detail.rox, save Detail.rod, and close e.Report Designer Professional, add -r to your syntax:

C:\Program Files\Actuate7\Erdpro\Bin>

erdpro -r “C:\Program Files\Actuate7\Erdpro\Examples\Detail\Detail.rod”

To update a release 4 report design to use relative file paths, type the following at the prompt:

C:\Program Files\Actuate7\Erdpro\Bin>

erdpro -u “C:\Program Files\Actuate7\My Reports\Mydesign.rod”

About componentsComponents are the building blocks of a report design. Some of the components Actuate e.Report Designer Professional provides include numeric controls, page layouts, and graphic components such as lines and rectangles. Icons represent components in Design Editor’s component palettes. You can also see components in the structure and layout panes of Design Editor. Libraries can organize components for reuse.

The components you see in Design Editor are onscreen representations of classes. A component is any class that is derived from the Actuate Foundation Class AcComponent. For more information about classes, see “About object-oriented programming,” later in this chapter.

Components in thestructure pane

Components in thelayout pane

48 D e v e l o p i n g A d v a n c e d e . R e p o r t s

You assemble components in a report design to perform a wide variety of reporting tasks. Design Editor’s structure pane shows a diagram of the relationships among all the components in your report design. For more information about the structure pane, see “About the structure pane” in Chapter 3, “Understanding the design environment.”

Component relationships in a report designThe following illustration shows the relationships among components in a typical grouped report. In this report, order items are grouped by order number, and orders are grouped by customer name. For more information about grouped reports, see “About group sections” in Chapter 11, “Working with sections.”

C h a p t e r 2 , U n d e r s t a n d i n g t h e d e s i g n p r o c e s s 49

This illustration shows Design Editor’s structure pane.

The component relationships determine how each component is used. For example, this illustration has several frame components, but each is used in a different way because of its relationship to other components.

RootMain reportDatabase connectionQuery data stream

Frame with components to print at beginning of report

Frame to print at top of each continuation page (2-n)Group section to sort rows by customer

Frame to print at top of sectionGroup section to sort rows by order

Frame to print at top of section

Frame to print at top of section for pages 2-n

Frame to print for each order item

Controls to display data for the items in each order

Frame to print at end of section (end of each order)

Container for page layoutsPage to specify print stylePrintable area of page

Page layout for just one section.

50 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Component relationships in a report documentThe following illustration shows how the pages of this report look when you run the report and view it. Compare this illustration with the structure pane diagram in the previous illustration to find the components that correspond to each part of the report.

1

A Breeze Green swtr 1 29.00 29.00A Solo Bike short 2 15.00 30.00

Order 101

Type Name Description Qty Price Extension

Customer A100 Main St.Anytown, MD 20902

(301) 555-0941

XYZ Corp. Sales Order Report XYZ

Order 122

Type Name Description Qty Price Extension

Report page headerXYZ Corp. Sales Order Report

Customer B200 Elm St.Anytown, MD 20901

(301) 555-6371

Cust. A, Order 101 continued

Type Name Description Qty Price Extension A Wind Blue swtr 1 30.00 30.00B Duo Khaki pant 3 15.00 45.00

2

Customer group title

Order group title

Order items, with three text controls and three integer controls for each item

Total: $1,060.00

A Wind Blue swtr 1 30.00 30.00B Duo Khaki pant 3 15.00 45.00

Total: $ 75.00

(etc.) . . .

Order page header

More order items

Order total

Order group title (next)

Customer group title (next)

(Items in Order 101 continue)

First page

Second page

Page number, which is part of the page style

Report title with label, image, and line controls

C h a p t e r 2 , U n d e r s t a n d i n g t h e d e s i g n p r o c e s s 51

About Actuate’s object-oriented designActuate 7 is based on object-oriented programming, which is a programming technique that uses objects, not algorithms, as its fundamental building blocks. Whenever you build a report design with Actuate e.Report Designer Professional, you are writing an object-oriented program, whether or not you type the code yourself.

When you use Design Editor in e.Report Designer Professional to drag components and drop them into your report, Actuate creates the corresponding object-oriented code based on your choices. For many reports, you can develop a full, working design without writing any code.

You can also customize the behavior of report components and design new report components by using the Actuate Basic programming language. The amount of code you write depends on your needs. You might need to add code to a few components to change their behavior in specific ways. If you want to go further, you can define entirely new classes based on the Actuate Foundation Class hierarchy. For more information about the Actuate Foundation Classes, see “About the Actuate Foundation Classes,” later in this chapter.

About object-oriented programmingTo understand object orientation in Actuate e.Report Designer Professional, you must understand three key concepts of object-oriented programming:

■ Object-oriented programming uses objects, not algorithms, as fundamental building blocks. In Actuate, objects make up a report.

■ Each object is an instance of a class. Classes define the characteristics of objects.

■ Classes are related through inheritance. Each new class inherits the characteristics of the class on which it was based.

The rest of this section explains these concepts.

About classesA class is a specification, or template, for creating objects. This specification is written in programming code and stored in a class library. In Actuate e.Report Designer Professional, classes are written in Actuate Basic.

A class contains a set of descriptions that define the characteristics of an object. These descriptions are variables and methods. A variable is a named storage location for data. A method is a function or procedure that defines the behavior of an object.

52 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Actuate e.Report Designer Professional provides many classes that you can use in reports, such as pages, group sections, text controls, integer controls, and graphs. These classes reside in the Actuate Foundation Class library, and some of them are represented by icons in the component palettes of Design Editor. For more information about this library, see “About the Actuate Foundation Classes,” later in this chapter.

About objectsAn object is an instance of a class. When you run your report design, the classes in the report design are instantiated. When you view the finished report, what you see are objects.

For example, a design for a sales report could contain a class called OrderTotal designed to display the total value for each order. When you run the report, an OrderTotal object is instantiated as each order is processed, and the object’s value is set to the total for that order. When you view the report, you see a set of objects that make up the order (objects that display the customer name, item codes, prices, and so on), and one of these objects is the OrderTotal object. All the totals are instances of the OrderTotal class.

Understanding the relationship between classes and objectsTo make the relationship between classes and objects clearer, let’s compare it to a more familiar programming relationship, the relationship between data types and variables.

A data type specifies the characteristics that all variables of that type have. The numeric data type, for example, specifies rules for what numeric data is and how you can manipulate it. You can declare as many numeric variables as you like, each with a different name, but all numeric variables share the same rules and characteristics.

Similarly, a class specifies the characteristics that all objects instantiated from that class have. A text control class, for example, can specify a border style, a

Sales Report

VisiBoard, Inc.

Total: $3440.60

Indoor Pools USA

Total: $ 890.00

Johns & Co.

Total: $1972.00 Instances of the OrderTotal class

C h a p t e r 2 , U n d e r s t a n d i n g t h e d e s i g n p r o c e s s 53

font, and an expression that determines the control’s value. When you run the report, many text control objects can be instantiated from that one class. Each text control object can have a different value, but all follow the class specification regarding where that value comes from and how it is formatted.

The following illustration shows the relationship between two text control classes that are part of a report design and the objects that are instantiated when you run the report.

About inheritanceClasses are related through inheritance. Each new class is derived from, or based on, another. The derived class is a subclass of the other class, which is called the superclass. The subclass inherits, or automatically includes, all the variables and methods of the superclass. The subclass can modify the inherited variables and methods or define new ones.

The following illustration shows inheritance.

Instantiated Objects

Aaron, Michael

(201) 498-7662

Adams, Mary

(406) 399-2156

Adler, J. R.

(310) 658-0991

Class Phone ...

...

...

End Class

Class Declaration

Class Declaration

Class ContactName ...

...

...

End Class

Variable A

Method X

Variable B

Class B

= Declared in this class

= InheritedVariable A

Method X

Class A

Variable A

Method X

Method Y

Class C

(Base)

(Derived)(Derived)

54 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Subclassing occurs automatically when you use Design Editor. When you drag a component from a component palette and drop it in the structure pane or layout pane, Actuate e.Report Designer Professional derives a subclass of the Actuate Foundation Class that corresponds to the component in the palette. For example, when you drag a text control and drop it into a report, Actuate e.Report Designer Professional derives a subclass from the AcTextControl class.

Understanding the benefits of inheritance

Inheritance provides two of the major benefits of object-oriented programming:

■ Easy maintenance

■ Reusable code

When you change a superclass, the changes are reflected in all the subclasses. You do not have to manually make changes in each of the subclasses. This is easier than maintaining code in multiple locations.

If you need to adapt a class for a slightly different use, you can reuse the code from the existing class. You do not edit the class definition itself or define a totally new class. Instead, you derive a subclass from the existing class, then override, or modify, only those variables or methods that you want to change. Any other class that inherits from the same superclass is not affected by the changes you make in your new class.

For example, the following illustration shows the same classes introduced earlier. If you change Method X in Class B, you do not affect Method X in Class C. Your changes are reflected in Class D, however, because Class D is a subclass of Class B.

C h a p t e r 2 , U n d e r s t a n d i n g t h e d e s i g n p r o c e s s 55

About the Actuate Foundation ClassesActuate provides a set of report-related classes called the Actuate Foundation Class library. You can use the classes in this library to build a wide range of reports. Many of these classes are represented by icons in Design Editor’s component palettes.

Most of the time, you can create reports without understanding the Actuate Foundation Classes in detail. You must understand these details only if you create custom components that require programming or if you want to change or extend the class architecture.

If you want to go further with Actuate e.Report Designer Professional, you can declare your own classes to extend the Actuate Foundation Class architecture or to customize the report-building process. For example, you can define a new type of page flow that prints data from right to left.

There is no limit to how much you can extend or replace Actuate’s architecture, but to do so, you need an understanding of object-oriented principles and the details of the data structures and code in the Actuate Foundation Classes.

Override here

Changes from override reflected here

Variable A

Method X

Class A

Changes from override not reflected here

= Declared in this class

= Inherited

Variable A

Method X

Method Y

Class C

Variable A

Method X

Variable B

Class B

Variable A

Method X

Variable B

Class D

Method Z

(Base)

(Base and Derived)

(Derived)

56 D e v e l o p i n g A d v a n c e d e . R e p o r t s

For specification-level information about each class, see the Actuate Foundation Class Reference. For information about how to implement classes in Actuate Basic, see Programming e.Reports.

C h a p t e r 3 , U n d e r s t a n d i n g t h e d e s i g n e n v i r o n m e n t 57

C h a p t e r

3Chapter 3Understanding thedesign environment

This chapter contains the following topics:

■ About the application window

■ About the tools:■ About Design Editor■ About the Design Editor’s helper tools■ About Query Editor■ About using Textual Query Editor■ About Stored Procedure Data Source Builder■ About Method Editor■ About Expression Builder■ About Report Viewer■ About Management Console

■ About the toolbars and palettes

■ About context menus

58 D e v e l o p i n g A d v a n c e d e . R e p o r t s

About the application windowWhen you start e.Report Designer Professional, the application window opens. This window contains the menu bar, toolbars, and palettes. The following illustration shows the application window as it appears when you start e.Report Designer Professional for the first time. If your application window has been customized, it might not look exactly like the following illustration.

About the toolsIn e.Report Designer Professional, the windows you work with are tools that you use to build a particular part of the report design. The following table lists the main tools and the tasks you can accomplish with them.

Title bar Menu bar Tool bars

Status bar

Palette toolbar

Tool Task

Design Editor Choose the overall structure, location, and appearance of a report and its components.

Query Editor Write or modify a query graphically to provide data for the report.

Textual Query Editor

Write or modify a text-based query to provide data for the report.

Stored Procedure Data Source Builder

Identify parameters and path names of stored procedures.

Method Editor Write Actuate Basic code by overriding methods.

C h a p t e r 3 , U n d e r s t a n d i n g t h e d e s i g n e n v i r o n m e n t 59

About Design EditorThe following illustration shows Design Editor, one of the main tools in e.Report Designer Professional. You use Design Editor to specify the structure and appearance of a report or a report component. Most of the later chapters in this manual discuss specific tasks you perform using Design Editor. For example, Chapter 16, “Designing a page layout,” explains how to use Design Editor to modify page layouts.

Design Editor window is split into two panes. The left pane shows the structure of the report design, and the right pane shows the layout. You can

Expression Builder Point and click to construct mathematical and conditional expressions.

Report Viewer View the finished report after you run it to see the results of your report design.

Management Console

Place the report object instance (.roi) file and report object executable (.rox) file in an Encyclopedia volume so that other users can access your report.

Tool Task

Slot provides target for placing components

Structure pane showsrelationships between components

Layout pane shows appearance of report design

Drag splitter to resize panes or to hide one pane

60 D e v e l o p i n g A d v a n c e d e . R e p o r t s

drag the splitter bar to show or hide either pane. Alternatively, you can choose View➛Report Structure to show or hide the structure pane.

About the structure paneThe following illustration shows the structure pane, which displays components used in the report design and shows the relationships between them.

C h a p t e r 3 , U n d e r s t a n d i n g t h e d e s i g n e n v i r o n m e n t 61

Use the structure pane to work with the organization of the report design. You can drag a component and drop it into the structure pane to add it to the report, or drag components from place to place within the structure pane to move, copy, or reuse them. For more information about moving, copying, and reusing components, see Chapter 4, “Using Design Editor.”

Some of the components in the structure pane do not appear in the finished report. For example, the report uses the database connection component to get data, but the component itself is not visible in the pages of the report. In contrast, the layout pane shows only components that are visible in the report.

Using components from included modules

When a component name appears in gray in the structure pane, it indicates that the component is defined in another module, and your design is using the component by referring to that module. Components with names that appear in black are declared in the current report design module, which is the main report object design (.rod) file of your project. For more information about referring to components in included modules, see “Referencing components” in Chapter 4, “Using Design Editor.”

About the layout paneThe following illustration shows the layout pane, which provides a way to work with the appearance of components. Only those components that are visible in the finished report, such as frames and controls, appear in the layout pane.

62 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Use the layout pane to work with the appearance of the report. For example, you use the layout pane to determine the colors, fonts, and alignment of text, data, and images.

Understanding the meaning of the Design Editor displayIt is important to understand that each icon or component you see in Design Editor does not necessarily represent a separate component. Some items in Design Editor represent true components, which are subclass definitions that are saved in the current design file. Other items represent only references to components. You create a reference to a component when you want to use the component in several places in the design without actually making multiple component definitions. For more information about referencing components, see “Copying, subclassing, and referencing components” in Chapter 4, “Using Design Editor.”

You can reference a single component more than once in the same design, and when you do, the component appears more than once in Design Editor. Therefore, your report design might actually be made up of fewer components than you would think if you merely counted the icons in the structure pane.

For example, you might use the same label control to display the name of your company in a report title and a page header. When you reference a component more than once, Actuate e.Report Designer Professional does not make multiple copies of the component. Instead, it simply records the various ways you want to use the component. The structure and layout panes reflect this reference information.

The following illustration shows a report that uses the same frame in two ways, as a title and a page header.

Definition of frameReference to frame

C h a p t e r 3 , U n d e r s t a n d i n g t h e d e s i g n e n v i r o n m e n t 63

About the Design Editor’s helper toolsDesign Editor provides auxiliary tools, or helpers, which you use along with the main tool. The following illustration shows Design Editor and its helpers. The table following the illustration summarizes the purpose of each helper.

1

2

5

6

3

4

With this Helper... You can....

1 Field List Place components that display data in a report design. Field List shows variables in the data row available for use in a particular part of the report.

2 Scratch Pad Temporarily store components as you move them from place to place.

64 D e v e l o p i n g A d v a n c e d e . R e p o r t s

About the Project Browser and the Globals BrowserTo adjust the settings of the Project Browser or the Globals Browser, do the following:

1 Right-click over a blank area of the Project Browser or the Globals Browser. Choose Options.

Browser Options appears.

2 Select the appropriate settings.

Choose OK.

3 Library Browser View components in a library, publish components, or drag a component and drop it into Design Editor. This view can display any library file included in your project.

4 Project Browser View the files included in your report design, move components from file to file, or drag a component and drop it into Design Editor. This view shows the same components shown in the Globals Browser (5), organized by file.

5 Globals Browser View the components from all files included in your report application, or drag a component and drop it into Design Editor. This view shows the same components as the Project Browser (4), organized alphabetically, without showing which file contains each component.

6 Component Editor View and modify a component’s properties, methods, variables, and class information.

With this Helper... You can....

C h a p t e r 3 , U n d e r s t a n d i n g t h e d e s i g n e n v i r o n m e n t 65

The following table shows where you can get more information about many of the Design Editor’s helper tools.

About Component EditorThe following illustration shows Component Editor, one of the Design Editor’s helper tools. Use Component Editor to view and manipulate the properties, methods, class information, and variables of a component in the report design. The information in Component Editor changes whenever you select a different component. The title bar shows the name of the component for which information currently appears.

Helper More information

Field List “Placing controls in a report design” in Chapter 12, “Working with frames and controls.”

Scratch Pad “About Scratch Pad” in Chapter 4, “Using Design Editor.”

Library Browser For an overview, see Chapter 6, “Working with libraries.”

Component Editor “About Component Editor,” later in this chapter.

66 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Using Component Editor pages

Component Editor is made up of four pages, each of which you use for a particular task. To display a page, choose the appropriate tab.

About Query EditorUse Query Editor to specify a query, which is a statement that specifies which data from the database to include in the report. When you open Query Editor, Database Browser accompanies it, as shown in the following illustration. Query Editor, which is a graphical editor, is a central tool in e.Report Designer Professional. For more information about Query Editor, see Chapter 7, “Using a query data stream.” For more information about Database Browser, see “About Database Browser,” later in this chapter.

Click to see list of related properties

Page Task For more information

Properties View or set properties, such as font size or background color. Also lets you access Expression Builder.

“Setting properties of components” in Chapter 4, “Using Design Editor.”

Methods View, override, or add methods using Method Editor.

“About Method Editor,” later in this chapter. Also, Programming e.Reports.

Variables Add new variables or make a variable a property or parameter.

Programming e.Reports.

Class View or modify class information, such as class name, superclass, and scope.

Programming e.Reports.

C h a p t e r 3 , U n d e r s t a n d i n g t h e d e s i g n e n v i r o n m e n t 67

For more details about using Query Editor, see Chapter 7, “Using a query data stream.”

Using Query Editor pages and panesQuery Editor consists of an upper pane that displays the tables and joins, and a lower pane. The lower pane contains six pages, each of which manages a particular task. To display a page, choose the appropriate tab.

Database browser showsavailable data

Tabs in lower pane display pages

Drag splitter to resize panes

Upper pane displays tables and joins

Page Task For more information

Upper pane

Select tables, and specify the joins between the tables (in the upper pane only).

“Selecting tables” and “Creating joins” in Chapter 7, “Using a query data stream.”

Columns Select columns or define computed columns.

“Selecting columns” in Chapter 7, “Using a query data stream.”

Conditions Specify criteria for which rows the query retrieves from the database.

“Putting conditions on row retrieval (WHERE)” in Chapter 7, “Using a query data stream.”

Order By Specify how rows are sorted. “Sorting data with Query Editor” in Chapter 7, “Using a query data stream.”

68 D e v e l o p i n g A d v a n c e d e . R e p o r t s

About Database BrowserThe following illustration shows Database Browser, Query Editor’s helper window. Database Browser displays a diagram of the available databases, tables, and columns managed by the Database Management System to which Actuate e.Report Designer Professional is connected. To specify a table you want in the query, drag the table from Database Browser and drop it into Query Editor. The following illustration shows how Database Browser appears when connected to a Microsoft Access database. The display might appear different when connected to other types of databases.

Group By Specify aggregate rows, which total data from a group of rows.

“Summarizing data” in Chapter 7, “Using a query data stream.”

Having Specify criteria for selecting specific aggregate rows.

“Putting conditions on aggregate rows (HAVING)” in Chapter 7, “Using a query data stream.”

SQL View the SQL SELECT statement.

“Viewing the SELECT statement” in Chapter 7, “Using a query data stream.”

Page Task For more information

Server

Database or schema

Tables

Click and to open and close display

Columns

C h a p t e r 3 , U n d e r s t a n d i n g t h e d e s i g n e n v i r o n m e n t 69

About using Textual Query EditorUse Textual Query Editor to enter a text-based query into your reports. To use Textual Query Editor, specify the SQL Query Data Source (Textual) as the data source in your report. When you choose View➛Data Source, Textual Query Editor appears.

Type the complete text of your query in the upper pane. You manipulate columns, static parameters, and ad hoc parameters in the lower pane.

When you use Textual Query Editor, you cannot specify queries using Query Editor, which is a graphical editor. For more information about Textual Query Editor, see Chapter 9, “Using Textual Query Editor.”

About Stored Procedure Data Source BuilderThe following illustration shows Stored Procedure Data Source Builder. After you set up your database and place the stored procedure component in the DataStream slot, you can access Stored Procedure Data Source Builder. Stored Procedure Data Source Builder lets you view the set of stored procedures available with a database and specify whether you want the full path name of a stored procedure or just the procedure name.

You can also type parameters into Sample Parameter Values if the stored procedures and the database that you are accessing allow parameters. If you use parameters, the request page prompts users for more information when they run the report.

70 D e v e l o p i n g A d v a n c e d e . R e p o r t s

For more information about stored procedures, see Chapter 10, “Using and customizing a stored procedure,” in Programming e.Reports.

About Method EditorThe following illustration shows Method Editor, one of the main tools in e.Report Designer Professional. Access Method Editor from the View menu or from Component Editor. Use Method Editor to write Actuate Basic code in methods. A method is a function or procedure that is associated with a component.

Using the default setting, the list of methods that appears in Method Editor is a list of the most frequently used methods. To see all methods, you must select the Filter button and choose among the selections in the dialog that appears.

Type code

Choose New to add method or Override to modify inherited code

Select method from drop-down box

C h a p t e r 3 , U n d e r s t a n d i n g t h e d e s i g n e n v i r o n m e n t 71

The list of methods that appears in Method Editor changes when you select a different component. The title bar gives the name of the component for which information currently appears.

The Pin checkbox lets you pin the specific method in Method Editor. This allows you to open and close other methods that are not pinned. You can override or update these methods while Method Editor remains focused on the pinned method.

For more information about how to program methods, see Chapter 16, “Writing and using a procedure,” in Programming e.Reports.

About Expression BuilderThe following illustration shows Expression Builder, which you use to construct Actuate Basic value expressions for properties. For example, the expression "Order " & [orders.orderID] is an Actuate Basic expression that displays the order number for each order.

72 D e v e l o p i n g A d v a n c e d e . R e p o r t s

How to write an expression using Expression Builder

1 To open Expression Builder, do one of the following:

■ Select a control’s ValueExp property in the Properties page of Component Editor, and choose Builder.

■ Choose Insert➛Computed Field, and drop the control in Design Editor.■ Drag <Computed> from Field List and drop it on Design Editor.

2 In Expression Builder, you can do the following:■ Type the expression.■ Choose an element from below the Expression box. Choose Insert.

3 When you finish the expression, choose OK.

Expression box

Select expression elements here

Choose Insert to add selection to expression

Use buttons as shortcuts to select elements

C h a p t e r 3 , U n d e r s t a n d i n g t h e d e s i g n e n v i r o n m e n t 73

For more information about this syntax, see “Using Query by Example (QBE) syntax,” in Chapter 7, “Using a query data stream,” and Chapter 4, “Running a report,” in Using e.Reports.

About Report ViewerThe following illustration shows Report Viewer. You use the viewer to look at the results when you run a report. The viewer provides active viewing features, such as hyperlinks and saved searching. For more information about how to use the viewer, see Part 3, “Using an e.report with desktop applications,” in Using e.Reports.

74 D e v e l o p i n g A d v a n c e d e . R e p o r t s

If you have access to an Encyclopedia volume through a web server, you can also view the report with a web browser. For more information about viewing reports with a web browser, see Part 1, “Using an e.report with Actuate Active Portal,” in Using e.Reports or Part 2, “Using e.reports with Actuate ReportCast,” in Using and Customizing Actuate ReportCast.

About Management ConsoleManagement Console is a tool for distributing and accessing report files in an Encyclopedia volume. The Encyclopedia is a file management system that provides access to files on a server.

If you have access to the Encyclopedia volume through a web server using Actuate Active Portal, you can view the Encyclopedia volume with a web browser. For more information about using the Encyclopedia volume on the web, see Part 1, “Using an e.report with Actuate Active Portal,” in Using e.Reports or Part 2, “Using e.reports with Actuate ReportCast,” in Using and Customizing Actuate ReportCast.

About the toolbars and palettesThe main application window contains a main toolbar, a format toolbar, several tool-specific toolbars, and the palette toolbar, which contains the component palettes. You can choose to display all, none, or any combination of

C h a p t e r 3 , U n d e r s t a n d i n g t h e d e s i g n e n v i r o n m e n t 75

these items through the menu options in View➛Toolbars. The following illustration shows the application window with the Main toolbar, Format toolbar, and Palette toolbar open.

For information about how to reconfigure the toolbars and palettes, see “Moving and closing toolbars and palettes” in Chapter 5, “Customizing the design environment.”

The Main toolbarThe main toolbar provides quick access to common tasks, such as creating a new file, opening a file, and saving a file. The buttons on the Main toolbar are enabled or disabled depending on what is open and whether the cursor focus is in the structure pane, Query Editor, the report object instance (.roi) file, or other parts of the Actuate e.Report Designer Professional.

To discover the purpose of each button on the toolbar, position the mouse cursor over the button and wait for the tool tip to appear. If the Main toolbar is not visible, look at View➛Toolbars➛Main, and select Main.

Main toolbar Format toolbar

Palette toolbar

Main toolbar

76 D e v e l o p i n g A d v a n c e d e . R e p o r t s

The Format toolbarThe Format toolbar provides quick access to common formatting options you apply to components or groups of components in the report design.

To see the purpose of each item on the toolbar, position the mouse cursor over the item and wait for the tool tip to appear.

The tool-specific toolbarsThe following tools have their own toolbars: Viewer, Query Editor, Debug, and Stored Procedure Builder.

To see the purpose of each item on each toolbar, position the mouse cursor over the item and wait for the tool tip to appear.

Format toolbar

Viewer toolbar

Query Editor toolbar

Debug toolbar

Stored Procedure Builder toolbar

Navigator toolbar

C h a p t e r 3 , U n d e r s t a n d i n g t h e d e s i g n e n v i r o n m e n t 77

The Navigator toolbar is not enabled as the default behavior. To enable the Navigator toolbar, see “Working with the Navigator menu item and toolbar,” in Chapter 5, “Customizing the design environment.”

The component palettesAll the components you need to build a report are represented by buttons in the component palettes. The components are grouped in palettes, each of which contains components that you use for similar tasks, such as drawing illustrations.

You access each palette through a button on the Palette toolbar, as shown in the following illustration.

The Palette toolbar contains one button for each of the component palettes. The Palette toolbar also contains two buttons that represent the selection methods, single selection and rubberband selection.

You can make the Palette toolbar visible and invisible by choosing View➛Toolbars➛Component Palette. The Palette toolbar is visible when Component Palette is selected.

After you display a palette by choosing the appropriate button in the Palette toolbar, you can use the pushpin button to keep the palette open while you work. Otherwise, when you choose a button in another palette, the first palette closes. You can move or dock a palette just as you can a toolbar. For

Component palettes

Data palette

Drawing/Graphics palette

Pages palette

Structure palette

Controls palette

Palette toolbar

78 D e v e l o p i n g A d v a n c e d e . R e p o r t s

information about moving toolbars and palettes, see “Moving and closing toolbars and palettes” in Chapter 5, “Customizing the design environment.”

An HTML palette, hidden by default, is also available. To make it visible on the Palette toolbar, or to make other changes to palettes, you can customize the palette buttons and layout. For information about customizing palettes, see “Customizing a component palette” in Chapter 5, “Customizing the design environment.”

About context menusMany tools in e.Report Designer Professional provide context menus. A context menu is a menu that contains commonly used commands associated with a particular item, such as a component or dialog.

How to display a context menu

1 Position the mouse pointer over a component or in the background of a window.

2 Click the right mouse button.

Following is an illustration of one of many context menus.

Context menu

C h a p t e r 4 , U s i n g D e s i g n E d i t o r 79

C h a p t e r

4Chapter 4Using Design Editor

This chapter contains the following topics:

■ Creating a new report design

■ Placing components in a report design

■ Copying, subclassing, and referencing components

■ Arranging components

■ Setting properties of components

■ Changing the class name or superclass

■ Removing components from a report design

■ Managing multiple Design Editor windows

80 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Creating a new report designTo create a new report design, do one of the following:

■ Use one of the report wizards.

■ Choose a report template in Create New Report.

■ Choose Blank Report in Create New Report.

For more information about the report wizards, see Chapter 1, “Designing an e.report with the report wizard,” and “Using Information Object Wizard,” in Chapter 8, “Working with an information object.” For more information about creating a report template, see “Specifying a template” in Appendix A, “Using a configuration file.” For more information about changing the items listed in Create New Report, see “Changing the item list for Create New Report,” in Chapter 5, “Customizing the design environment.”

How to create a blank report design

1 In e.Report Designer Professional, choose File➛New.

2 In Create New Report, select Blank Report. Choose OK.

A blank report design appears.

C h a p t e r 4 , U s i n g D e s i g n E d i t o r 81

Choosing the default connection and data sourceYou can specify the default database connection for a new report with the Connection registry setting. If the default connection is an AcODBCConnection, you can specify the default data source with the AcODBCConnection::DataSource registry setting.

You can also specify these default values with the configuration file. The configuration file settings take precedence over the registry settings. For more information about specifying a default database connection with the configuration file, see “Specifying a database connection” in Appendix A, “Using a configuration file.”

How to specify the default database connection for a new report

1 On the task bar, choose Start➛Run.

Run appears.

2 In Run, type:

regedit.exe

3 Choose OK.

4 In the Registry Editor, navigate to HKEY_CURRENT_USER\Software\Actuate\e.Report Designer Professional 7.0\New Report Wizard.

5 Select Connection. Choose Edit➛Modify.

6 In Edit String, type the name of the connection class in Value data.

The connection class can be an AFC connection class or a connection class in an included library.

7 Choose OK.

8 Choose Registry➛Exit.

82 D e v e l o p i n g A d v a n c e d e . R e p o r t s

How to choose the default ODBC data source for a new report

1 On the task bar, choose Start➛Run.

2 In Run, type:

regedit.exe

3 Choose OK.

4 In the Registry Editor, navigate to HKEY_CURRENT_USER\Software\Actuate\e.Report Designer Professional 7.0\New Report Wizard.

5 Select AcODBCConnection::DataSource in the right pane of the Registry Editor window. Choose Edit➛Modify.

6 In Edit String, type the name of the data source in Value data.

7 Choose OK.

8 Choose Registry➛Exit.

Setting the default page size and marginsYou can specify the default page size and margins for a new report with the Page Size and Page Margins registry settings. You must specify the default page size and margins in twips. One inch contains 1,440 twips.

How to set the default page size for a new report

1 On the task bar, choose Start➛Run.

2 In Run, type:

regedit.exe

3 Choose OK.

4 In the Registry Editor, navigate to HKEY_CURRENT_USER\Software\Actuate\e.Report Designer Professional 7.0\New Report Wizard.

5 Choose Edit➛New➛String Value.

6 Type:

Page Size

7 Press Enter.

8 Choose Edit➛Modify.

9 In Edit String, enter the height and width of the page in twips. Use a space character to separate values.

For example, for a legal size page, type:

12240 20160

C h a p t e r 4 , U s i n g D e s i g n E d i t o r 83

10 Choose OK.

11 Choose Registry➛Exit.

How to set the default page margins for a new report

1 On the task bar, choose Start➛Run.

2 In Run, type:

regedit.exe

3 Choose OK.

4 In the Registry Editor, navigate to HKEY_CURRENT_USER\Software\Actuate\e.Report Designer Professional 7.0\New Report Wizard.

5 Choose Edit➛New➛String Value.

6 Type:

Page Margins

7 Press Enter.

8 Choose Edit➛Modify.

9 In Edit String, enter the top/bottom margin followed by the left/right margin in twips.

For example, for a page with 1.5 inch margins on all sides, type:

2160 2160

10 Choose OK.

11 Choose Registry➛Exit.

Placing components in a report designTo place a component in a report design, use the Insert menu or drag the component from a component palette, a library, Field List, or Scratch Pad and drop it into the structure pane or layout pane of Design Editor.

You can also draw a component in the layout pane. Drawing gives you more control over the size and shape of the component. For more information about how to draw a component, see “Using the mouse to draw components in the layout pane,” later in this chapter.

For more information about dragging and dropping into the structure or layout pane, see “Placing components in the structure pane,” and “Placing components in the layout pane,” later in this chapter. For more information about using Field List, see “Placing controls in a report design” in Chapter 12, “Working with frames and controls.”

84 D e v e l o p i n g A d v a n c e d e . R e p o r t s

About sources from which you can drag componentsActuate e.Report Designer Professional provides several sources from which you can drag-and-drop components, as summarized in the following table.

The following table shows where you can find more information about each of these methods.

Component source Available components

Insert menu Frequently used frames and controls.

Component palettes Components that correspond to Actuate Foundation Classes.

Project Browser Components in all report object library (.rol) and report object design (.rod) files included in the report object design, listed by file.

Globals Browser Components in all files included in the report design, listed alphabetically.

Library Browser Reusable components that have been published in library files.

Field List Column names in the data row retrieved by the data stream for the currently selected frame. Field List is the only source from which you can place more than one component at a time.

Scratch Pad Components you previously placed in Scratch Pad for temporary storage.

Component source More information

Component palettes “The component palettes” in Chapter 3, “Understanding the design environment.”

Project Browser “About the Design Editor’s helper tools” in Chapter 3, “Understanding the design environment.”

Globals Browser “About the Design Editor’s helper tools” in Chapter 3, “Understanding the design environment.”

Library Browser Chapter 6, “Working with libraries.”

Field List “Placing controls in a report design” in Chapter 12, “Working with frames and controls.”

Scratch Pad “About Scratch Pad,” later in this chapter.

C h a p t e r 4 , U s i n g D e s i g n E d i t o r 85

Understanding how placing components determines their useWhen you place a component in your report design, the location where you place the component determines how it is used:

■ When you drop a component in a particular slot in the structure pane or layout pane, the name of the slot determines the use. For more information about slots, see “About slots,” later in this chapter.

■ When you drop a component on another component’s icon in the structure pane, Actuate e.Report Designer Professional assigns a default use to the component. If Actuate e.Report Designer Professional cannot determine the most logical use for a component, a dialog appears in which you choose a location and use for the component.

■ When you drop a component in the layout pane, the name appearing on the divider bar determines the use.

Some components are designed for a specific use. For example, when you add a page list component to your report design, the only possible location for it is in a report component’s PageList slot.

Other components can fit into several slots. For example, you can place a frame in a Before, After, PageHeader, PageFooter, or Content slot.

About slotsThe structure and layout panes of Design Editor can optionally display slots, which are visual targets that indicate where you can place a component. The slots are visual representations of certain properties, called component reference properties. A component reference property stores the name of a component that is to be used in the manner indicated by the name of the property. For example, a report section’s PageHeader property stores the name of a component (usually a frame) that is to be used as a page header for the report.

86 D e v e l o p i n g A d v a n c e d e . R e p o r t s

You place a component in a particular slot to determine how the component is used. The following illustration shows how slots appear in the structure pane.

You do not have to place components in all the slots; the six empty slots shown in the illustration are all optional. If you do not place a visual component in at least one of these six slots, however, your report will be empty.

A label for each slot indicates how to use the component dropped in that slot. For example, the report section component has a Before slot. When you drop a frame in that slot, it prints or appears at the beginning of the report.

Empty slots for Report component

C h a p t e r 4 , U s i n g D e s i g n E d i t o r 87

The following table describes the slots that contain visual components. This table does not include the Connection slot or the DataStream slot. The Connection slot is further discussed in “Placing components in a report section” in Chapter 11, “Working with sections.” The DataStream slot is further discussed in Chapter 7, “Using a query data stream.”

For details about how these slots relate to each other in a grouped report, see “Placing components in a group section” in Chapter 11, “Working with sections.”

Slot name Description

Before Text or data that appears at the beginning of a report section or group section. A component in the Before slot can also present summary data.

PageHeader Text or data that appears at the top of every page or set of columns except the first in which a report section’s or group section’s data prints or appears. To display the PageHeader component on the first page of the report section or group section, set the report section’s or group section’s Pagination➛ShowHeaderOnFirst property to AsPageHeader or AsColumnHeader. If ShowHeaderOnFirst is set to AsPageHeader, the page header appears before the Before frame. If ShowHeaderOnFirst is set to AsColumnHeader, the column headers appear after the Before frame and just before the first set of columns.The component in this slot is often a continuation of the component in the Before slot. For example, a page header could display a customer name at the top of every page of a multi-page customer group section.

Content Text or data that appears for every data row processed by the component, such as every item in a customer order.

PageFooter Text or data, such as page numbers, that appear at the bottom of every page except the last on which a component prints or appears. To display the PageFooter component on the last page, set the report section’s or group section’s Pagination➛ShowFooterOnLast property to True.

After Text or data that appears at the end of a report section or group section, such as summary data.

Subpage A page layout that is specific to one section of the report and defines the layout of just that section. For example, you can place a parallel section inside a subpage to produce a two-column section.

88 D e v e l o p i n g A d v a n c e d e . R e p o r t s

There are other slots, such as the PageList slot, that you work with less often. A report section component, for example, has a PageList slot for the component that defines the set of page layouts in the report.

All the slots are described in later chapters, where their corresponding tasks are documented in detail. For example, the PageList slot is described in “Setting up a page sequence” in Chapter 16, “Designing a page layout.”

How to display or hide slots in Design Editor

1 In e.Report Designer Professional, choose View➛Options.

Options—Design Editor appears.

2 To display empty slots, select Show Empty Slots.

3 To hide empty slots, deselect Show Empty Slots.

4 Choose OK.

Placing components in the structure paneWhen you place components, you might prefer to place them in the structure pane rather than the layout pane. If the structure pane is not visible, choose View➛Report Structure. The advantage of using the structure pane is that it provides a compact view of the report design. It shows a logical view of all components used in the design. The layout pane, in contrast, shows only visual components such as frames and controls.

The structure pane also provides a clear picture of the relationships between the components. The layout pane provides relational information in the captions above each frame, but you might prefer the structure pane presentation.

You can place components in the structure pane in two ways:

■ Place components in empty slots.

■ Place components on icons.

Placing components in empty slots in the structure paneIf empty slots appear, place a component in the appropriate slot. For example, to nest a group section in another group section, use the Content slot as shown in the following illustration.

C h a p t e r 4 , U s i n g D e s i g n E d i t o r 89

For more information about hiding and displaying slots, see “How to display or hide slots in Design Editor,” earlier in this chapter.

Placing components on icons in the structure paneIn addition to using empty slots, you can place components directly on component icons in the structure pane.

1 Drag a component such as a frame and drop it on an icon such as the group section in the structure pane.

90 D e v e l o p i n g A d v a n c e d e . R e p o r t s

In Use As, specify how you want the frame to be used in the section. These choices are the same as the names of the slots.

2 Select the slot you want to use. Choose OK.

Placing components in the layout paneWhen you want to add components to a frame, you might prefer to place them in the layout pane rather than the structure pane. The advantage of using the layout pane is that you can work with the location and appearance of the components.

For example, in the layout pane you can move, resize, and align components. For more information about working with components in the layout pane, see “Arranging components,” later in this chapter.

You can place components in the layout pane in three ways:

■ Drag components and drop them into slots.

■ Drag components and drop them into frames.

■ Draw components using the mouse. Using this method, you can control the position and size of the component as you place it.

For information about how to draw components using the mouse, see “How to draw components in the layout pane,” later in this chapter.

Placing components in slots in the layout paneYou can use slots in the layout pane just as you can in the structure pane. The following illustration shows how Design Editor looks when slots appear in the two panes of a simple report design.

Keep in mind that these are two views of the same slots, not two different sets of slots.

C h a p t e r 4 , U s i n g D e s i g n E d i t o r 91

The following illustration shows the same report design after a frame is placed in the group section’s Content slot. The frame appears as an icon in the structure pane, and as a rectangular area in the layout pane. Keep in mind that these are two views of the same frame, not two different frames.

You can place structure components in the structure pane or the layout pane by dragging and dropping them into the appropriate slot.

92 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Placing components in frames in the layout paneWhen you place a frame in your report design, an empty rectangular area appears in the layout pane. You can drag a component and drop it directly into this rectangular area.

When you drag-and-drop a component, you are subclassing the component. For more information about subclassing, see “Subclassing components in Design Editor,” later in this chapter.

You can use components from component palettes, Field List, and other sources, as described in “About sources from which you can drag components,” earlier in this chapter. Field List is the easiest source from which to place several controls at once. For details about how to use Field List, see “Placing controls in a report design” in Chapter 12, “Working with frames and controls.”

Using the mouse to draw components in the layout paneInstead of dragging and dropping to place a component in your report design, you can click and draw in the layout pane. This method works for any component that you can place in a frame, such as a text control, rectangle, or nested frame.

For example, to add a rectangle, you simply drag a rectangle component and drop it in the structure or layout pane. A rectangle with a default size appears, as shown in the following illustration.

C h a p t e r 4 , U s i n g D e s i g n E d i t o r 93

If the default size and location do not meet your needs, you can move and resize the rectangle. However, you might prefer to use the mouse to draw a component with the size and location you want.

How to draw components in the layout pane

1 In the Drawing/Graphics palette, choose the component you want to use.

2 Move the crosshair cursor to the layout pane, and draw a rectangle of the size you want by holding down the mouse button and dragging from one corner to another.

This rectangle shows the boundaries of the component you are adding, not its actual shape.

3 Release the mouse button.

The component appears in the layout pane in the area you outlined.

94 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Copying, subclassing, and referencing componentsWhen you drag-and-drop components in Design Editor or its helper windows, you are either moving the component or creating a copy, subclass, or reference. Moving a component simply changes its location in the report design and is not a form of reuse. Copying, subclassing, and referencing are the three ways to reuse components in Actuate e.Report Designer Professional. The following table summarizes these operations.

Actuate e.Report Designer Professional provides default behavior that makes sure the most logical operation is performed each time you drag-and-drop. When Actuate e.Report Designer Professional cannot determine the most logical operation, a dialog appears so that you can choose the operation you want.

The mouse pointer changes to indicate whether you are moving, copying, subclassing, or referencing.

Operation Description When and how to use

Copy Duplicate a component.

To locally change some characteristics of the original component. When you create a copy of a component, changes to the original do not affect the new component.

Subclass Derive a component from another component.

To locally change some characteristics of the original component. The new component inherits its other characteristics from the original.Future changes to the original will be reflected in the new component.When you drag-and-drop a frame or a control from a palette, you are subclassing that frame or control.

Reference Refer to a component rather than creating a new component.

To use a component, such as a frame or connection, from a library. If you change the component in your report design, it becomes a local subclass of the library component.

C h a p t e r 4 , U s i n g D e s i g n E d i t o r 95

For more information about copying components, see “Copying components,” later in this chapter.

For more information about subclassing components, see “Subclassing components in Design Editor,” later in this chapter.

For more information about referencing components, see “Referencing components,” later in this chapter.

Copying componentsYou can copy a component, such as a frame, from one part of a report design to another. You can also copy a control from one frame to another.

To copy a component, see “How to copy components,” later in this chapter.

A component and a copy of the component are useful in these cases:

■ You created one component, and you want to work with that component as a basis, or template, for creating a new component.

■ You want to resume work on the original component and not affect the second, new component.

The new component inherits from the same class that the original inherits from. That is, the original and copy are both at the same level in the class hierarchy.

For more information about inheritance, see “About inheritance” in Chapter 2, “Understanding the design process.”

When you make a copy, all the property settings are also copied. When you copy a component that contains other components, the contained components are copied, as well. If you copy a frame, for example, the controls it contains are copied. You can then work with each version of the frame separately to create the combination of components you want.

Move

Copy

Subclass or reference

Superclass

Copied componentComponent

96 D e v e l o p i n g A d v a n c e d e . R e p o r t s

A copied frame within a frame, however, operates slightly differently:

■ A frame within a frame, and any controls within that internal frame, are shared by the original larger frame and the copied larger frame. Because labels and controls in an internal frame are shared, the changes you make in an internal frame are made in the original and the copy.

■ Controls copied from the external frame are not shared.

How to copy components

To copy one or more components, select the components and Ctrl + drag the components to the location where you want to place the copy, or choose Edit➛Copy and Edit➛Paste. You cannot copy multiple components if the selection set contains controls in different frames. To copy a frame, Ctrl + drag the gray bar just above the frame in the layout pane.

Subclassing components in Design EditorSubclassing means creating a new component that inherits characteristics from the original component. Make a subclass when you want to locally change some characteristics of the original component and use inheritance to obtain other characteristics. The inherited characteristics will reflect future changes to the original component.

C h a p t e r 4 , U s i n g D e s i g n E d i t o r 97

When you locally change, or override, characteristics in the new subclass, the component stops inheriting those characteristics from the original component. For example, if you set a new background color for the subclass, it stops using the inherited color. Now the background color of the subclass does not change when you modify the original component.

The most common example of subclassing is when you drag a component from a component palette and drop it into Design Editor. You create a subclass of the Actuate Foundation Class that is represented on the palette.

For more information about subclassing and inheritance, see “About Actuate’s object-oriented design” in Chapter 2, “Understanding the design process.”

How to subclass in Design Editor

Drag the component from the source and drop it into your report design.

If subclassing is the only logical operation for the source and destination, the new component appears in Design Editor. Otherwise, a dialog appears, prompting you to create a reference to or a subclass of the source component.

The following table summarizes the cases in which subclassing is the default operation for a simple drag-and-drop.

How to subclass a connection component in Design Editor

A developer might wish to subclass a connection component to give users choices of databases to which they can connect when they run the report. This process involves these steps:

1 In a library, create all possible connections from which a user can choose.

2 Override the correct method of the report section to instantiate the correct connection, which is based on a parameter.

In the example that follows, a Sybase and Oracle connection class are defined.

Component source Component destination

Component palette Any destination

Field List Design Editor

Flow or top-level control in a library Design Editor

98 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Override the NewConnection() method of the report section to instantiate the proper connection, according to the parameter:

Function NewConnection( ) As AcConnectionSelect Case MyConnParamCase "Oracle"Set NewConnection = New MyOracleConnection...End SelectEnd Function

For more information about overriding methods, see Programming e.Reports.

Referencing componentsReferencing means to refer to an existing component rather than create a new component. If you wish to minimize the time spent on updating components, it is easiest to create a boilerplate, or template component, publish it in a library, and reference it elsewhere in Design Editor.

The most common example of referencing is when you use a component from a library. A frame containing a company logo is an example of a component that is often referenced. The library designer creates the component and publishes it in a library. Then, many report developers can refer to the component in their report designs. If a report developer modifies the component’s properties in a report design, Actuate e.Report Designer Professional creates a local subclass of the library component.

How to reference an existing component

Drag the component from the source and drop it into your report design.

If the source is a library, Actuate e.Report Designer Professional creates a reference to the component in the library, unless the component is a flow or a control. When you drag-and-drop a flow or a control at the top level from a library, Actuate e.Report Designer Professional creates a subclass of the original component. When you drag-and-drop a control in a frame from a library, Actuate e.Report Designer Professional moves the control.

In some cases, Actuate e.Report Designer Professional cannot determine the best default operation, and it must prompt you for a choice. The following table summarizes these cases. The term top level in the table indicates the level shown in the illustration.

C h a p t e r 4 , U s i n g D e s i g n E d i t o r 99

Arranging componentsOnce you have placed components in the report design, you can rearrange them. This section gives detailed instructions for arranging components in the following ways:

■ Selecting components.

■ Moving components.

■ Sizing components.

■ Aligning and centering components.

■ Layering components.

Selecting componentsSelecting means choosing one or more items to be affected by the next command you perform. When you select a component in the structure pane, the same component is selected in the layout pane, which scrolls, if necessary, to display the component.

How to select a component

1 Position the mouse pointer on the component.

2 Click once.

You can use Tab or Shift+Tab to select the next or previous component in a frame.

Top level

Below top level

Component source Component destination

Globals Browser, Project Browser, or top level of Library Browser

Design Editor, Scratch Pad (below top level), or Library Browser (below top level)

100 D e v e l o p i n g A d v a n c e d e . R e p o r t s

How to select multiple components

You can select multiple components in the layout pane only, not in the structure pane. The selection set can contain controls in different frames, but the selection set cannot contain both a control and the frame in which the control resides.

Method 1: Using the rubberband

Move the mouse pointer to the layout pane and draw a rectangle around the components you want by holding down the mouse button and dragging from one corner of the rectangle to another.

All the components inside the rubberband, including components that are only partially inside, are selected.

Method 2: Using the Shift key

1 Position the mouse pointer on the first component, and click once.

2 Position the mouse pointer on another component, and Shift-click.

3 Repeat step 2 to select additional components.

Method 3: Using Select All

1 Select a frame in the structure pane or the layout pane.

2 Choose Edit➛Select All or press Ctrl+A.

All the controls in the frame are selected.

How to deselect a component

■ To deselect one component in the selection set, position the mouse pointer on it and Ctrl+click.

■ To deselect all currently selected components, click the background of the layout pane.

Moving componentsMoving a component can mean either of the following operations, depending on the source and destination of the component:

■ Change the display location of the component.

■ Change the location of the component in the design.

To change the display location of a component, move it from one part of the layout pane to another. For example, you can move a control to the right in a frame. For information about how to move the display positions of

C h a p t e r 4 , U s i n g D e s i g n E d i t o r 101

components in relation to one another, see “Aligning and centering components,” later in this chapter.

To change the location of a component in the design, move it from one place to another in the structure pane or layout pane. For example, you can move a control from one frame to another. The appearance of the control is not changed, but its place in the design changes.

You can move a second-level component, such as a control, from a library into a report design. When you work with a top-level component such as a frame from a library, however, the component is referenced. You can see that the component is referenced, rather than moved or copied, because the name of the component in the structure pane is gray.

Scratch Pad is useful for moving components from one part of a report design to another. For more information about Scratch Pad, see “About Scratch Pad,” later in this chapter.

How to move a component using the mouse

Drag the component and drop it in a new location. If the component is a frame, drag the gray bar above the frame in the layout pane, not the frame itself.

If the mouse pointer changes to the copy or reference/subclass mouse pointer while you are dragging, start again and hold down Shift while you drag-and-drop. For more information about the mouse pointers, see “Copying, subclassing, and referencing components,” earlier in this chapter.

How to move multiple components using the mouse

You can move multiple components in the layout pane only, not in the structure pane:

1 Select the components using the steps in “How to select multiple components,” earlier in this chapter.

2 Drag the components to the new location.

How to move components using the arrow keys

You can move components using the arrow keys in the layout pane only, not in the structure pane. You can move components within a frame, but you cannot move them from one frame to another using this method:

1 Select the component or components you want to move.

2 Press the left, right, up, or down arrow key.

The components move by one square as defined by the snap to grid. If the snap to grid is not enabled, the components move by one pixel.

102 D e v e l o p i n g A d v a n c e d e . R e p o r t s

To move by one pixel when the snap to grid is enabled, hold the Ctrl key and the arrow key down at the same time. For more information about the snap to grid, see “Using grids in the layout pane,” later in this chapter.

To move a set of components quickly, hold the arrow key down. To move a set of components even more quickly, hold the Ctrl and Shift keys and the arrow key down at the same time.

Using grids in the layout paneThe layout pane of Design Editor provides two grids to help you align components, the snap to grid and the visible grid.

The snap to grid is a matrix of invisible horizontal and vertical lines that aligns components automatically. When you place a component in the layout pane, Design Editor adjusts the position of the component so that the upper left corner is on the nearest gridline intersection.

The visible grid is a matrix of horizontal and vertical lines that appear in the background of the layout pane. These lines need not be the same distance apart as those in the snap to grid. The visible grid has no effect on where you can place components. It is simply a visual cue that helps you arrange components.

How to enable the snap to grid and visible grid

1 In e.Report Designer Professional, choose View➛Options

Options—Design Editor appears.

2 Select Snap To Grid, Display Gridlines, or both.

3 Optionally, specify a new size for each square in the grid by typing values in Horizontal and Vertical.

You can choose a different size for each grid.

About Scratch PadScratch Pad is a helper window that you use along with Design Editor. Scratch Pad temporarily stores components while you are working on a report design. Use Scratch Pad to help you move components from one part of a report design to another, or let components rest in Scratch Pad as you move them between Design Editor and its other helper windows.

For example, in the following illustration, several slots are full. If you want to place a new frame in the PageHeader slot, you can delete the frame from that slot. However, you might not want to throw away the work you did to create that frame. By moving the frame to Scratch Pad, you create room for a new frame in the PageHeader slot and save the old frame in case you want to use it again later.

C h a p t e r 4 , U s i n g D e s i g n E d i t o r 103

How to use Scratch Pad

1 In e.Report Designer Professional, choose View➛Scratch Pad.

104 D e v e l o p i n g A d v a n c e d e . R e p o r t s

2 Drag a component from Design Editor and drop it on the folder icon in Scratch Pad.

Sizing componentsWhen you place a frame or control in a report by dragging and dropping, e.Report Designer Professional gives it a default size. You can also use the mouse to size a component at the same time you place it in the report. In either case, you can easily change the size later. In general, you must select a component before you can resize it. You can resize a frame without selecting it, however.

How to resize a frame

1 Place the mouse pointer at the bottom edge of the frame.

The pointer changes shape.

2 Drag the bottom edge of the frame to the desired position.

C h a p t e r 4 , U s i n g D e s i g n E d i t o r 105

How to resize a component

1 Select the component in the layout pane.

2 Use the handles to drag the component edges with the mouse until the component is the desired size.

To set an exact size, set the component’s Size properties in Component Editor. You can access the Size properties from the layout or structure pane.

For more information about how to set a property, see “Setting properties of components,” later in this chapter.

Aligning and centering componentsYou can align components in several ways:

■ Align components in relation to each other using their right, left, top, or bottom edges or using their vertical or horizontal centers.

■ Center components in relation to the frame.

■ Use the snap to grid option to align components as you drop them in the layout pane. For more information about grids, see “Using grids in the layout pane,” earlier in this chapter.

To support exporting values that appear in a column in the report object instance (.roi) file to a column in Microsoft Excel, align the controls in a column and set their sizes to the same width. For example, set the alignment and width the same for a label control for a column heading and the data controls under it. If the alignment and size of controls differ, the contents of a column heading label might export to a different column from the column’s data controls.

How to align components with each other

1 Select the components in the layout pane using the steps in “How to select multiple components,” earlier in this chapter.

2 Choose Format➛Align.

3 From the menu that appears, choose one of the following commands.

Drag handles to resize control

Left Middle Right Top Center Bottom

106 D e v e l o p i n g A d v a n c e d e . R e p o r t s

The components align to the last component you selected.

How to center components in a frame

1 Select the component or components you want to center.

2 Choose Format➛Center.

3 From the menu that appears, choose one of the following commands.

Layering componentsWhen you add a component to a frame, Actuate e.Report Designer Professional places it on top of the other components. If the component contains a background fill, it obscures the components behind it. You can control the Z-order, or how objects overlap, by moving them forward and backward in relation to each other.

How to change the layering depth of a component

1 In the layout pane, select the component you want to bring forward or send backward.

2 Choose Format➛Layers.

3 From the cascading menu, choose one of the following commands.

■ To move the component one step closer to the top of the stack, choose Move Forward.

■ To stop other components from overlapping the selected component, choose Move to Front.

■ To move the component one step toward the bottom of the stack, choose Send Backward.

■ To let all other components overlap the selected component, choose Send to Back.

Horizontally BothVertically

Move Forward

Move to Front

Send Backward

Send to Back

C h a p t e r 4 , U s i n g D e s i g n E d i t o r 107

Setting properties of componentsProperties are characteristics of a component for which you can specify a value. A property controls the appearance or behavior of an object, such as the font size for a label control or the server name for a database connection.

You can set properties for a single component or a set of components using Component Properties or the Format toolbar. Many of the properties in the Properties page have default values listed in gray. These are inherited properties. If you change these values, you can always go back to the inherited values by using the Default button. For more information about inherited properties, see “About inheritance” in Chapter 2, “Understanding the design process.”

Property groups contain related properties. Some property groups contain subgroups. For example, the Properties page for a summary chart displays the Legend properties group that specifies the chart’s legend appearance. In the Legend properties group, the LegendFont properties group contains the properties that specify the font’s appearance in the chart’s legend.

You can use the SampleValue property to make the layout pane look more similar to how the report appears after it is run. Set a value for the SampleValue property of each data control. For example, use the value XYZ Corporation for the text control that displays company names.

How to set a property

1 Select one or more components in the layout pane of Design Editor.

2 Choose View➛Component Properties.

108 D e v e l o p i n g A d v a n c e d e . R e p o r t s

The Properties page of Component Editor appears, showing the properties of the selected component, or the common properties of the set of components.

3 Click in the field to the right of the property name.

4 Specify a new value using one of the following techniques:■ Type a value in the field.■ If the field changes to a drop-down list when you click it, choose a value

from the list.

■ If Builder appears when you click in the field, choose the button to display the tool you can use to construct a value. The tool that appears depends on which property you are modifying.

5 Choose Apply.

6 Choose Close.

To revert to the inherited value, choose Default in Component Properties.

Changing the class name or superclassYou can change a component’s class name or superclass on the Class page of Component Editor.

How to change the class name or superclass

1 Double-click the component in the structure or layout pane of Design Editor.

2 In Component Editor, choose the Class page.

Inherited default values appear in gray

Select or type new values

Choose the minus icon to hide related values

C h a p t e r 4 , U s i n g D e s i g n E d i t o r 109

3 To change the class name, edit the text in the Class Name text box.

4 To change the superclass, edit the text in the Super Class text box or choose a value from the drop-down list.

5 Choose Close.

Removing components from a report designYou can remove any component from a report design except the AcReport component.

When you remove a component from a report design, remember it might contain other components that will also be removed. For example, if you delete a frame, all the components contained in that frame are also deleted.

Some of the components that appear in the structure and layout panes are only references to other components. When you delete a reference, the original component and its contents are not deleted. You do not lose much work if you delete a reference. If you delete the original component, however, it is removed from the report design and you might lose more work. For more information about component references, see “Referencing components,” earlier in this chapter.

If you want to temporarily remove a component from the design but save it to use a few minutes later, move it to Scratch Pad. For more information about Scratch Pad, see “About Scratch Pad,” earlier in this chapter.

Type new value

Type or choose new value

110 D e v e l o p i n g A d v a n c e d e . R e p o r t s

How to remove a component from a report design

1 Select the component in the structure or layout pane.

2 Choose Edit➛Delete.

The component and any components it contains are deleted.

Managing multiple Design Editor windowsYou can have only one report design open at one time. You can, however, open several Design Editor windows at the same time. For example, you can use one Design Editor to work with the whole report and another to focus on the page layout.

Reasons you might want to focus Design Editor on one component include the following:

■ You are working on a complex report design, and you want to focus on one component.

■ You are creating or modifying a reusable component from a library.

To manage multiple Design Editor windows, use the following techniques:

■ To open a Design Editor window focused on a single component from a report design, such as a page layout, follow the steps in “How to focus Design Editor on a single component,” later in this chapter.

■ To change focus to a Design Editor window that is already open, use the Window menu.

How to focus Design Editor on a single component

You can open a Design Editor window on any type of component except a single control or one of the connection, data stream, or page list components.

1 Open the report design or library.

2 If the structure pane is not visible, choose View➛Report Structure.

3 Right-click the component in the structure pane of Design Editor, Project Browser, Globals Browser, or Library Browser and choose Edit Layout from the context menu.

An additional Design Editor window appears.

For more information about Project Browser and Globals Browser, see “About the Design Editor’s helper tools” in Chapter 3, “Understanding the design environment.”

C h a p t e r 5 , C u s t o m i z i n g t h e d e s i g n e n v i r o n m e n t 111

C h a p t e r

5Chapter 5Customizing the

design environmentThis chapter contains the following topics:

■ About design environment customization

■ Setting general options in the designer

■ Setting a font in the designer

■ Customizing a component palette

■ Customizing units of measurement

■ Moving and closing toolbars and palettes

■ Changing tool display options

■ Choosing design search paths

■ Choosing a directory for new designs

■ Managing server profiles

■ Changing the item list for Create New Report

112 D e v e l o p i n g A d v a n c e d e . R e p o r t s

About design environment customizationActuate e.Report Designer Professional is highly customizable. You can change display characteristics, such as default fonts, units of measurement, and tool placement. You can choose the configuration file that provides libraries and data source connections for your report design. Also, you can customize search paths, component palettes, and other aspects of the report design environment. To customize the environment, use Design Editor, Options, configuration files, and registry key settings.

Setting general options in the designerOn Options—General in e.Report Designer Professional, you can:

■ Set the number of recently opened files that appear in the File menu. For more information about setting the number of recently opened files, see “Customizing the length of the recently opened files list,” later in this chapter.

■ Set the configuration file that the Designer uses. For more information about the configuration file, see “Choosing a configuration file,” later in this chapter.

■ Set the default locale that the Designer uses. For information about locales, see Chapter 1, “Introduction to working with multiple locales,” in Working with Multiple Locales.

■ Set Management Console’s URL that the Designer uses to access an Encyclopedia volume. For more information, see “Setting the Management Console URL,” later in this chapter.

■ Enable the Navigator menu item and toolbar. For more information, see “Working with the Navigator menu item and toolbar,” later in this chapter.

■ Set Basic source encoding. For more information, see “Setting Basic source encoding,” later in this chapter.

How to change settings on Options—General

1 In e.Report Designer Professional, choose View➛Options.

Options—Design Editor appears.

2 Choose General.

Options—General appears, as shown in the following illustration.

C h a p t e r 5 , C u s t o m i z i n g t h e d e s i g n e n v i r o n m e n t 113

3 Provide new information or change the existing information.

For information about the available options, see:■ “Customizing the length of the recently opened files list,” later in this

chapter■ “Choosing a configuration file,” later in this chapter■ “About design environment customization,” earlier in this chapter■ Chapter 1, “Introduction to working with multiple locales,” in Working

with Multiple Locales

■ “Setting the Management Console URL,” later in this chapter■ “Working with the Navigator menu item and toolbar,” later in this

chapter■ “Setting Basic source encoding,” later in this chapter■ “Setting general options in the designer,” earlier in this chapter

Choose OK.

114 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Customizing the length of the recently opened files listYou can specify the length of the recently opened files list on Options—General. The recently opened files list appears at the bottom of the File menu.

For example, in Show the <number> most recently opened files, if you type 4, the recently opened files list displays four files, as shown in the following illustration.

C h a p t e r 5 , C u s t o m i z i n g t h e d e s i g n e n v i r o n m e n t 115

You can open any file on the recently used files list by selecting it from the File menu.

Choosing a configuration fileThe Actuate e.Report Designer Professional configuration file accomplishes the following tasks:

■ Identifies the component libraries and Actuate Basic source (.bas) files listed in Library Organizer. For more information about Library Organizer, see “Including a library in a design” in Chapter 6, “Working with libraries.”

■ Defines a set of libraries and Actuate Basic source files that every new report design includes.

■ Contains site-specific information about databases.

When you build a report object executable (.rox) file, Actuate e.Report Designer Professional makes available all the database connections, libraries, and Actuate Basic source files in the configuration file. When you choose a database connection, e.Report Designer Professional locates the connection properties for that connection in the configuration file.

How to choose the configuration file

1 In e.Report Designer Professional, choose View➛Options.

Options—Design Editor appears.

2 Choose General.

The four most recently opened files

116 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Options—General appears.

3 In Configuration file, provide a URL by completing one of the following actions:■ Type the URL.

■ Choose the URL from the drop-down list.

■ Choose Browser and navigate to the URL.■ Copy the URL from a source such as a web browser or an e-mail

message and paste it in the text box.

If the path name is relative, Actuate e.Report Designer Professional searches for the file relative to the location of the e.Report Designer Professional executable file, erdpro.exe. The default location is C:\Program Files\Actuate7\Erdpro\Bin.

Choose Refresh.

Actuate e.Report Designer Professional reads the configuration file, makes the resources in it available to your report design, and displays a confirmation message.

4 Choose OK.

C h a p t e r 5 , C u s t o m i z i n g t h e d e s i g n e n v i r o n m e n t 117

5 To close Options—General, choose OK.

Setting the Management Console URLYou can set up e.Report Designer Professional to support accessing an Encyclopedia volume without providing a URL in Management Console URL on Options—General. To set up the Management Console URL, type the URL in Management Console URL and deselect Prompt for URL. For information about the URL to use to access your Encyclopedia volume, see your Actuate iServer system administrator.

For example, if the web server and Actuate iServer reside on a machine named siamese using the default settings for the installations, the Management Console URL for siamese is:

http://siamese:8700/acadmin/login.jsp?serverURL=http://siamese:9000&daemonURL=http://siamese:9100

Working with the Navigator menu item and toolbarTo use the Navigator menu item and toolbar, you must first make them available.

How to enable the Navigator menu item and toolbar

To enable the Navigator menu item and toolbar, on Options—General, select Enable the Navigator menu item and toolbar. Selecting this option makes the Navigator available.

For more information about setting options on Options—General, see “Setting general options in the designer,” earlier in this chapter.

How to access the Navigator and the Navigator toolbar

To access the Navigator, choose File➛Navigator.

To display the Navigator toolbar, choose View➛Toolbars➛Navigator.

Setting Basic source encodingThe setting for Basic source encoding specifies encoding in the Actuate Basic .bas file used to create the report object executable (.rox) file. e.Report Designer Professional uses the selection in Internal Basic source encoding to create the Basic source (.bas) file from the report design file. On Options—General, for internal Basic source encoding, select one of the following options:

■ Text

■ Unicode (UCS-2LE)

The Unicode option is not available on Windows NT or Windows 98.

118 D e v e l o p i n g A d v a n c e d e . R e p o r t s

If your data source contains Unicode, you must select Unicode (UCS-2LE). If you select Text, you can edit the BAS file using a text editor. If you select Unicode (UCS-2LE), you cannot edit the BAS file using e.Report Designer Professional on Windows NT or Windows 98. If you use a custom external BAS file, you must specify the encoding used in that file.

Setting a font in the designerTo customize fonts, Actuate e.Report Designer Professional supports the following tasks:

■ Setting the default font for labels, data, and source editor

■ Setting the font for the structure pane

Setting the default font for labels, data, and source editorYou can specify the default font used in the following features:

■ Label control

■ Data control

■ Source editor

The default font for labels and data controls appears only for controls that are direct subclasses of the Actuate Foundation Classes. The default font does not appear for controls that are subclasses of a user-defined class. Specifying a TrueType font embeds font width information in the report object executable (.rox) file. If you use a Type 1 font, a generated Adobe PDF file or a dynamic text control’s HTML content can display inaccurate positioning for right-aligned and center-aligned text. The inaccurate positioning does not affect left-aligned text in generated PDF files or non-HTML text in Dynamic Text controls.

If you change the source editor font and you have a source editor open, you must close and reopen the source editor for the font change to apply.

How to set the default font for labels, data, and source editor

1 In e.Report Designer Professional, choose View➛Options.

Options—Design Editor appears.

2 Choose Fonts.

Options—Fonts appears, as shown in the following illustration.

C h a p t e r 5 , C u s t o m i z i n g t h e d e s i g n e n v i r o n m e n t 119

3 To change the default font, choose Change.

Font appears.

4 Select a Font, Font style, Size, Color, and other properties.

In some cases, a color has a different name in Font from its name in Component Editor or the Format toolbar. For example, fully saturated green is called Green in Component Editor and Lime in Font, and half-intensity green is called Forest in Component Editor and Green in Font.

120 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Choose OK.

5 To reset a font to its default value, choose Use Defaults.

6 Choose OK.

Setting the font for the structure paneYou can change the font face and font size that appear in the Actuate e.Report Designer Professional structure pane using Windows registry key settings. Use caution when you edit Windows registry keys. Changes to registry key entries and values can affect the Windows operating system. Before you begin, back up your system’s registry file.

You can change the default font and size for the structure pane by setting the following Windows registry keys:

■ HKEY_CURRENT_USER/Software/Actuate/e.Report Designer Professional 7.0/Settings/TreeViewFontName

■ HKEY_CURRENT_USER/Software/Actuate/e.Report Designer Professional 7.0/Settings/TreeViewFontSize

If you do not set these registry keys, Actuate e.Report Designer Professional uses as the default value the font and size shown in the following table.

Locale Font name Font size

Japanese MS Gothic 12

Korean Gulim 12

Chinese (Traditional) MingLiU 12

C h a p t e r 5 , C u s t o m i z i n g t h e d e s i g n e n v i r o n m e n t 121

If your machine uses Arial Unicode MS font, Actuate e.Report Designer Professional uses it with the font size 8 as the default settings for other languages.

Customizing a component paletteYou can modify the component palettes that e.Report Designer Professional supplies by making the following changes to the Palette toolbar and to each component palette:

■ Add buttons.

■ Change the location of buttons.

■ Change the class with which a button associates.

■ Save a palette representation.

■ Read a previously saved palette representation.

You can, for example, combine the various palettes into one palette that contains only the Actuate Foundation Classes you frequently use or alternatively, you can replace some of the Actuate Foundation Classes with custom classes.

At any time after you modify settings, you can restore the palettes and the classes associated with the buttons to their default values.

Customizing the palette layoutYou can customize the layout of component palettes in the following ways:

■ Change the position of a button in a palette.

■ Add one or more buttons to a palette.

How to change the position of a button

You can reposition a button on a palette by pressing Shift while dragging the button and dropping it in a new location.

Chinese (Simplified) MS Song 12

Other languages MS Sans Serif 8

Locale Font name Font size

122 D e v e l o p i n g A d v a n c e d e . R e p o r t s

How to add a button to a palette

1 Right-click the palette you want to modify. Choose Customize Button Layout.

Customize Toolbar appears.

2 From Available toolbar buttons, drag a button you want to add and drop it into Current toolbar buttons. You can also select a button in Available toolbar buttons and choose Add.

3 To add separators between buttons, drag Separator from Available toolbar buttons and drop it into Current toolbar buttons. You can also select a Separator in Available toolbar buttons and choose Add.

4 Repeat steps 2 and 3 until Current toolbar buttons shows all the buttons and separators you want on the palette.

5 To save your changes, choose Close.

You can undo changes before you close Customize Toolbar. To restore all previous settings of the palette, choose Reset.

How to restore the default palette layout

Right-click the palette you want to modify. Choose Default Button Layout.

C h a p t e r 5 , C u s t o m i z i n g t h e d e s i g n e n v i r o n m e n t 123

To restore the default button layout for all palettes at once, right-click the Palette toolbar. Choose Default Button Layout.

Customizing the class association of a paletteYou can change the class associated with each button on a palette and use a custom class that suits your work environment. The custom class you choose must be a subclass of the default class for the component.

You can also add custom classes to your palettes by adding buttons and associating these newly created buttons with your own frequently used classes. Choosing custom classes directly from the Palette toolbar saves time when designing reports because you do not have to choose these classes from a library.

For example, you can add your own currency control and set that control as the base control for currency columns in a database. When you create a currency control from the palette or drag a currency column from Field List, e.Report Designer Professional uses the custom currency control instead of the default Actuate Foundation Class currency control.

How to change the class associated with a button on a palette

1 Right-click a palette. Choose Options.

124 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Options—Palette appears.

2 Modify the component settings:■ From the Palette Button Identifier drop-down list, select the component

to modify or select a custom class. ■ To change the default image associated with this component, select an

image from the image list. You can select only images supplied with the application.

■ Under Full Class Name, type the class name you want to associate with this component. - The class associated with the component must derive from the

default class for the component. - When you add your own class name and this class name does not

have a global scope, you must specify the qualified class name, for example, ReportApp::OrderFrame::OrderIDControl.

- To reuse the component in other report designs, you must place the class in a library.

Select button image

Specify associated class name

Select button component

C h a p t e r 5 , C u s t o m i z i n g t h e d e s i g n e n v i r o n m e n t 125

You can also choose Browse to display a list of global classes from which you can select a class.

When you finish modifying the class or classes, choose OK.

How to restore the default class association of a button on a palette

1 Right-click a button in a component palette. Choose Options.

Options—Palette appears.

2 Choose Default All.

Choose OK.

Restore default class associations for all palette buttons

126 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Saving and reusing class associations of palettesAfter associating classes with buttons on the component palettes, you can save the configuration to an Actuate Palette Representation (.apr) file. Others in your work group can use this APR file to duplicate the palette representation. You can create different representations for a variety of recurring tasks. By saving each of the representations to an APR file, you can restore them later by reading the appropriate APR file.

How to save a palette representation to a file

1 Right-click a palette. Choose Options.

Options—Palette appears.

Save palette class representationto a file

Read palette class representation from a file

Restore default class associations for all palette buttons

C h a p t e r 5 , C u s t o m i z i n g t h e d e s i g n e n v i r o n m e n t 127

2 Choose To File.

Save Palette Class Representation appears.

3 In File name, type the name of the file in which to save your class associations.

In Save as type, select Palette Representation (*.apr). Choose Save.

4 On Options—Palette, choose OK.

How to apply a previously defined palette class representation

1 Right-click a palette. Choose Options.

Options—Palette appears.

128 D e v e l o p i n g A d v a n c e d e . R e p o r t s

2 Choose From File.

Read Palette Class Representation appears.

3 Select an Actuate Palette Representation (.apr) file or type a file name. Choose Open.

4 In Options—Palette, choose OK.

Read palette class representation from a file

C h a p t e r 5 , C u s t o m i z i n g t h e d e s i g n e n v i r o n m e n t 129

Customizing units of measurementYou can choose the unit of measurement to work with when resizing and positioning components. these units apply to properties such as size and position. This option supports working with the units with which you are most familiar.

When specifying the units of measurement, you can also specify some of the display options. You can, for example, choose to add a unit suffix, such as cm, after the numeric value. You can also specify the number of digits the application displays after the decimal point.

Setting the default unit of measurementBy default, Actuate e. Report Designer Professional uses and displays twips as the unit of measurement when you type values for properties such as size and position. You can, however, assign a different unit as the default unit of measurement for data entry and display. For internal use, Actuate e.Report Designer Professional converts the new default unit to twips.

You can assign one of the following units of measurement that Actuate e.Report Designer Professional recognizes:

■ Twips is the unit Actuate Basic uses internally, where 1 twip equals 1/20 point.

■ Points, where 1 point equals 1/72 inch.

■ Inches.

■ Millimeters, where 1mm equals 0.1 cm.

■ Centimeters, where 1 inch equals 2.54 cm.

How to set units of measurement

1 In e.Report Designer Professional, choose View➛Options.

Options—Design Editor appears.

2 Choose Units.

130 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Options—Units appears.

3 From the Display Unit list, select a unit of measurement.

To display a unit suffix after the value, such as in for inches or cm for centimeters, type the suffix in Display Suffix.

For example, if you select inches as the display unit and you want to display the abbreviation in for inches after the unit value, type:

in

e.Report Designer Professional displays 2.23in for the value 2.23. To display a space between the value and the suffix, type a space before the suffix.

4 Under Decimals, set the number of digits to display after the decimal point.

This option is for display only and does not affect the mathematical precision Actuate e.Report Designer Professional uses in its calculations.

Specify the number of digits to display after the decimal point

Specify the display of the unit suffix

Specify the unit of measurement

C h a p t e r 5 , C u s t o m i z i n g t h e d e s i g n e n v i r o n m e n t 131

Customizing unit suffixesThe default unit of measurement you set on Options—Units is the unit e.Report Designer Professional displays by default when you type numeric values for properties such as size and position. You can, however, explicitly choose a different unit for Actuate e.Report Designer Professional to display when you type a value. For example, even if the default unit of measurement is inches, Actuate e.Report Designer Professional accepts data in centimeters if you add the suffix cm after the value.

By default, Actuate e.Report Designer Professional recognizes certain suffix strings, as the following table shows.

You can, however, specify other strings for Actuate e.Report Designer Professional to recognize, such as c and m for centimeters and millimeters, respectively. Keep in mind that the application searches for the first match. Specifying m for meter and millimeter can produce unpredictable results.

How to specify the custom unit suffixes

1 In e.Report Designer Professional, choose View➛Options.

Options—Design Editor appears.

2 Choose Units.

Unit Default recognition string

Twips tw

Points pt, pts

Inches in, "

Millimeters mm

Centimeters cm

132 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Options—Units appears.

3 In Unit Recognition:

1 In the Recognize list, select the unit you want the application to recognize.

2 In by, type the string for Actuate e.Report Designer Professional to use to recognize the unit. Specify a recognition string only if it differs from Actuate e.Report Designer Professional’s default strings.

3 Repeat substeps 1 and 2 until you specify unique strings for all units you want Actuate e.Report Designer Professional to recognize.

4 Choose OK.

Specify the unit recognition string

Specify the unit for Actuate to recognize

C h a p t e r 5 , C u s t o m i z i n g t h e d e s i g n e n v i r o n m e n t 133

Moving and closing toolbars and palettesTo customize e.Report Designer Professional, you can:

■ Change the position of toolbars or palettes by dragging them from one part of the application window to another.

■ Close one, several, or all toolbars and palettes.

■ Display a toolbar or palette floating in the active area of the application window or you can attach it to an edge of the application window. If you attach a toolbar or palette to an edge of the application window, it stays with that edge as you move, resize, close, and reopen the window.

■ Open, close, and move a floating palette or toolbar independent of the application window. When you close the application window, however, the toolbar or palette also closes.

The following illustrations show two ways you can arrange toolbars and palettes. The first illustration shows toolbars attached at the top and bottom edges of the window and the Palette toolbar attached at the left edge.

Toolbars

Palettes

134 D e v e l o p i n g A d v a n c e d e . R e p o r t s

In the following illustration, some toolbars are closed. One of the component palettes floats to simplify adding components to the report design.

How to move a toolbar or palette

1 Position the mouse pointer in the background or on the edge of a toolbar or palette.

2 Drag the toolbar or palette to a new location.

Choose Lock Palette to lock the floating Structure palette

C h a p t e r 5 , C u s t o m i z i n g t h e d e s i g n e n v i r o n m e n t 135

A guide line appears to show the path of the toolbar or palette. When you move from a horizontal to a vertical window edge or from vertical to horizontal, the guide line changes orientation. When you attach a toolbar on a vertical window edge, the drop-down lists in the toolbar do not appear.

3 To attach the toolbar or palette to a window edge, release the mouse button when the guideline is partly outside and partly inside the blank area of the window.

136 D e v e l o p i n g A d v a n c e d e . R e p o r t s

4 To create a floating toolbar or palette, release the mouse button when the guideline is entirely inside or outside the blank area of the window or when the guideline is at a right angle to the edge of the window.

How to display a toolbar

In e.Report Designer Professional, choose View➛Toolbars. Choose a toolbar name to select it.

How to close a toolbar

In e.Report Designer Professional, choose View➛Toolbars. Choose a toolbar name to deselect it.

How to close a palette

Palettes do not appear in the Toolbars menu. To close a palette, complete one of the following actions:

■ Deselect the icon on the Palette toolbar.

■ Choose the close button on the palette.

Drag toolbar or palette and release

Deselect icon on Palette toolbar

Choose close button on specific palette

C h a p t e r 5 , C u s t o m i z i n g t h e d e s i g n e n v i r o n m e n t 137

Changing tool display optionsYou can modify the way information appears. For example, you can customize Design Editor to display long or short component names, show or hide empty slots, or display or hide gridlines.

How to change tool display options

1 In e.Report Designer Professional, choose View➛Options.

Options—Design Editor appears.

2 Select options to specify the appearance of the following items:■ In Display, set the appearance of slots and components.■ In Name, set the appearance of slots and components names.■ In Grid, set the appearance of gridlines.

Choose OK.

Choosing design search pathsActuate applications use relative file paths to locate included files. With relative file paths, you can specify a full path, a partial path, or just the file name when including files such as images, libraries, and Actuate Basic files. If the included file is not in the directory specified by the full path, e.Report Designer Professional searches other directories you specify.

The order in which Actuate searches directories is always the same, but the type of files included determines which search paths Actuate e.Report Designer Professional uses. Depending on the type of file included, e.Report Designer Professional searches some or all of the following directories and paths:

1 Directory that contains the referring file

For example, your design and included library files are in C:\Program Files\Actuate7. You move them to C:\My Reports. When the referring design file opens, Actuate e.Report Designer Professional searches C:\My Reports for the included library file.

2 Directory specified in the ExtendSearchPath function

You can use the ExtendSearchPath function to specify additional directories to search when locating images at Factory-time or View-time. For more information about the ExtendSearchPath function, see Actuate Basic Language Reference.

138 D e v e l o p i n g A d v a n c e d e . R e p o r t s

3 Design search path

The design search path specifies the directories to search for the referring design file. e.Report Designer Professional does not use design search path for other design files. For information about specifying the design search path, see “How to choose a design search path,” later in this chapter.

4 Global search path

The global search path specifies the directories to search for any design file, including the referring file. For information about specifying the global search path, see “How to set a global search path,” later in this chapter.

5 Configuration file search path

You can use configuration files to specify additional directories to search. For information about specifying the configuration file search path, see “Specifying a search path” in Appendix A, “Using a configuration file.”

6 Current working directory

The current working directory is the directory in which you last saved a file or opened a file.

For information about how Actuate e.Report Designer Professional uses search paths to locate images, see “Locating images” in Chapter 12, “Working with frames and controls.”

For information about how Actuate e.Report Designer Professional uses search paths to locate included libraries and Basic files, see “Locating included libraries” in Chapter 6, “Working with libraries.” For information about how Actuate e.Report Designer Professional uses search paths to locate ROX files, see “Building and running the report object executable (.rox) file” in Chapter 2, “Understanding the design process.”

How to choose a design search path

1 In e. Report Designer Professional, open the report object design (.rod) file.

2 Choose Report➛Design Properties.

Design Properties—Report Settings appears.

3 Choose Design Search Path.

Design Properties—Design Search Path appears.

4 Choose New.

A field appears in Directories.

5 Type the directory name, or choose Browse to navigate to and select the directory.

C h a p t e r 5 , C u s t o m i z i n g t h e d e s i g n e n v i r o n m e n t 139

The directory you provide appears at the bottom of the list. Actuate e.Report Designer Professional searches the directories in the order they appear in the list.

6 To change the search order, select a directory and choose the up or down arrow.

7 To remove a directory from the design search path, select the directory and choose Delete.

8 Choose OK.

How to set a global search path

1 In e.Report Designer Professional, choose View➛Options.

Options—Design Editor appears.

2 Choose Global Search Path.

140 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Options—Global Search Path appears.

3 Choose New.

A field appears in Directories.

4 Type the directory name, or choose Browse to navigate to and select the directory.

The directory you choose appears at the bottom of the list. Actuate e.Report Designer Professional searches the directories in the order they appear in the list.

5 To change the search order, select a directory and choose the up or down arrow.

6 To remove a directory from the global search path, select the directory and choose Delete.

7 Choose OK.

C h a p t e r 5 , C u s t o m i z i n g t h e d e s i g n e n v i r o n m e n t 141

Choosing a directory for new designsOn Options—Design Editor, you can set the directory in which to save new designs by default. If you start a new design when you open e.Report Designer Professional, it saves the new design to this directory. If work on an existing design before saving the new design, e.Report Designer Professional saves the new design to the directory that contains the existing design.

When you specify a new design directory, this directory becomes the current working directory.

How to specify the new design directory

1 In e.Report Designer Professional, choose View➛Options.

Options—Design Editor appears.

2 In Default location for new designs, in Save In, type a new location, or choose Browse to navigate to the location.

Choose OK.

142 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Managing server profilesIn Actuate e.Report Designer Professional, you can set up and manage server profiles to support selecting a server and volume on which to publish a report object executable (.rox) file. In Actuate e.Report Designer Professional, you can view a list of available server profiles by choosing View➛Options➛Publish. In Options—Publish, you can add, modify, or delete a server profile.

If you have a report design open in Actuate e.Report Designer Professional, you publish that report’s ROX to an iServer by choosing File➛Publish to Server. For more information about using a server profile to publish a report to an iServer, see “Publishing a report object executable file to a server,” in Chapter 1, “Designing an e.report with the report wizard.”

How to modify a server profile

1 In Actuate e.Report Designer Professional, choose View➛Options.

Options—Design Editor appears.

2 Choose Publish.

Options—Publish appears, displaying a list of available server profiles.

Choosing Delete removes the selected server profile

C h a p t e r 5 , C u s t o m i z i n g t h e d e s i g n e n v i r o n m e n t 143

3 In Server profile, select a server profile name. Choose Modify.

Server Profile appears.

4 In Profile details, change the settings to modify the profile.

Choose OK.

The new settings apply to the selected server profile name. For more information about Profile details options, see “Publishing a report object executable file to a server,” in Chapter 1, “Designing an e.report with the report wizard.”

Changing the item list for Create New ReportIn e.Report Designer Professional, using the default settings, the following items appear in Create New Report:

■ Quick Report Wizard

■ Listing Report Wizard

■ Blank Report

■ Component Library

■ Sample Template

144 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Using Windows registry key settings, you can hide items that appear in the list in Create New Report. Use caution when you edit Windows registry keys. Changes to registry key entries and values can affect the Windows operating system. Before you begin, back up your system.

To hide Sample Template in Create New Report, you can remove the Sample Template entry in the configuration file that Actuate e.Report Designer Professional uses to specify templates. For more information about specifying a template using a configuration file, see “Specifying a template,” in Appendix A, “Using a configuration file.”

How to hide items in Create New Report using registry key entries

1 Choose Start➛Run.

Run appears.

2 Type:

regedit

Choose OK.

Registry Editor appears.

3 Navigate to HKEY_CURRENT_USER\Software\Actuate\e.Report Designer Professional 7.0\Settings.

4 To hide an item in Create New Report:

1 Right-click a registry key name that appears in the following table and choose Modify.

Edit DWORD Value appears.

2 In Value data, replace 0 with 1. Choose OK.

5 Close Registry Editor.

Item in Create New Report Registry Key name

Blank Report Hide Blank Report Wizard

Component Library Hide Library Wizard

Listing Report Wizard Hide Listing Report Wizard

Quick Report Wizard Hide Quick Report Wizard

P a r t 3 , D e s i g n i n g s t r u c t u r e d c o n t e n t 145

P a r t

3Part 3Designing

structured content

146 D e v e l o p i n g A d v a n c e d e . R e p o r t s

C h a p t e r 6 , W o r k i n g w i t h l i b r a r i e s 147

C h a p t e r

6Chapter 6Working with libraries

This chapter contains the following topics:

■ About libraries

■ Creating a component library

■ Publishing a component

■ Including a library in a design

■ Locating included libraries

■ Placing a library component in a report design

■ Modifying components from a library

■ About read-only libraries

148 D e v e l o p i n g A d v a n c e d e . R e p o r t s

About librariesYou can include one or more libraries in a report design. If a library is included in a report design, you can use the components or Actuate Basic functions from the library in the report design.

A library can be any one of the following:

■ Component library, report object library (.rol) file

A component library is a file that contains components. A developer designs the components and publishes them, or saves them, in a component library. You can reference library components to use them just as they are, or you can subclass components to make minor customizations. In either case, components included in your design inherit future updates made to the original library components. The use of inheritance with library components provides a powerful method for distributing updates to a large number of users.

■ Actuate Basic source file (.bas)

An Actuate Basic source file defines functions that do complex calculations. Functions defined in the Actuate Basic source file are available in Expression Builder as external functions.

■ Report object design (.rod) file

You can use the components in another report design just as you use the components in a component library. The components in a report design, however, are not necessarily intended for reuse.

You can also include libraries in a component library if you open the component library as the target design. If a library is included in a component library, you can use the components or Actuate Basic functions from the library in the component library.

In this chapter, the term design refers to the target design in Design Editor. The target design can be a report object design (.rod) or a component library, report object library (.rol) file.

When you compile a report object design (.rod) file, any libraries containing components that your design uses are included. Including large libraries increases the size of the ROX file.

To keep the size of your libraries to a minimum, maintain several levels of libraries. Establish one at the enterprise level to contain commonly used components across applications. Establish one or more libraries at the application level to contain application-specific components. Finally, establish local libraries that are used by a single report.

C h a p t e r 6 , W o r k i n g w i t h l i b r a r i e s 149

Creating a component libraryThe first step in creating a component library is to design the components you want to place in it. You can put any type of component in a component library, including data sources, connections, controls, and frames.

After you design one or more components, publish them in a report object library (.rol) file. If the file does not already exist, you can create a new library.

How to create a new component library

When you create a new library using these steps, the library is included in the target design.

1 In e.Report Designer Professional, open the target file (ROD or ROL) that contains the components you want to publish.

2 Choose Tools➛Library Organizer.

Library Organizer appears.

3 Choose New.

New Library appears.

4 In File name, type a name for the library.

5 In Save in, choose the folder where you want to save the library file.

6 Choose Save.

150 D e v e l o p i n g A d v a n c e d e . R e p o r t s

7 Choose OK.

The Library Browser appears, showing the new library with one icon that represents the library file itself.

Alternatively, you can create a new component library as the target design and create components in the library.

1 Choose File➛New.

Create New Report appears.

2 Select Component Library.

3 Choose OK.

Publishing a componentTo publish a component means to place it in a component library for reuse.

When you design a component, its definition is saved in the report object design (.rod) file where the component is built. After you publish a component, its definition is saved in the library and the original design file contains only a reference, or link, to the component. This means that if you change a component before you publish it, the component is changed in the

C h a p t e r 6 , W o r k i n g w i t h l i b r a r i e s 151

original design file only, but if you change the component in the library after it is published, it is changed in the original design file and in any other file that contains a reference to the library component.

You can publish components in a report object library (.rol) file or a report object design (.rod) file. You publish a component in a library file if you want to make the component available to other users. You publish a component in a report design file if you want to reuse the component without making it available for general use.

Publishing in a library fileBefore you publish a component in a library, be sure to test it thoroughly and design it for stability. When you use a component from a library, you should expect it to work well and change infrequently.

If you publish a query data stream in a library, it is best to publish the connection component with the data stream. Grouping the connection and the data stream makes it easier for others to reuse the data stream. The connection, for example, is required if you or other users want to edit the query.

Publishing in a report design fileYou publish a component in a report object design (.rod) file when you want to reuse the component without making it available for general use.

For example, suppose you want to use a frame in many places in one design. Instead of making multiple copies, references, or subclasses in Design Editor, you create references to or subclasses of the published component that appears in the Library Browser, as shown in the following illustration.

Design Editor

Before publishing component

After publishing component

Component definition

Design Editor

Component reference

Library Browser

Component definition

152 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Using the Library Browser in this way ensures that all references or subclasses point to a single original component. It also makes it easier to find the original component when you want to make a change. For example, you might want to change one property of the frame and have that change reflected throughout the design. If you had merely subclassed the frame from place to place, it would be more difficult to find the frame component from which all the others inherit. If you had made multiple copies, instead of subclassing, you would have to make the change in every copy.

How to publish a component

1 Open the report object design (.rod) file that contains the component you want to publish.

2 Display the Library Browser for the component library using one of the following methods:■ If the file in which you want to publish the component is not already

included in the report design, include it by following the steps in “How to include an available component library or Actuate Basic file in a report design,” later in this chapter.

References or subclasses of published component

Definition of published component

C h a p t e r 6 , W o r k i n g w i t h l i b r a r i e s 153

■ If the file in which you want to publish the component is included in the report design, choose View➛Library Browser and double-click the file name in Choose Included Module.

3 Drag the component from Design Editor, and drop it on the top-level icon in the Library Browser.

Component Drop appears.

4 Select Publish the component.

5 Choose OK.

Including a library in a designBefore you can use the components in a component library or the functions in an Actuate Basic file, you must include the file in your design. When you include a file, it is saved along with your design, and your design can access the components or functions in the file.

You can include a component library or Actuate Basic file that either resides on a file system or is available on the web. A component library or Actuate Basic file that is available on the web must reside in the document root directory structure of a web server. A file that is available on the web is read-only.

154 D e v e l o p i n g A d v a n c e d e . R e p o r t s

The procedure for including a component library or Actuate Basic file can also be used to include a report object design (.rod) file. However, if you include a report object design, keep in mind that the components in it, unlike those in a component library, are not necessarily designed for reuse. The components in a component library change less frequently and are better tested than those in a report design.

How to include an available component library or Actuate Basic file in a report design

You can include a component library or Actuate Basic source (.bas) file in an existing report design. You also can include a library or .bas file as you create a new report. To include a library as you create a report, choose Libraries on the Choose Data Source or Choose Database pages of the report wizard.

Library Organizer appears and you can proceed with step 3 below.

To include a library in an existing report:

1 Open the report design.

2 Choose Tools➛Library Organizer.

C h a p t e r 6 , W o r k i n g w i t h l i b r a r i e s 155

3 In Library Organizer, if the name of the library you want appears under Available Libraries, select it and choose the up arrow. Alternatively, you can double-click the name of the library.

Available Libraries shows all ROL, BAS, and ROD files that exist in all specified search paths. For information about search paths, see “Locating included libraries,” later in this chapter. To display the absolute and relative paths for a file, select the file name and choose Properties.

4 Choose OK to return to the report wizard.

How to find and include additional libraries

In Library Organizer, if the name of the library you want to include does not appear under Available Libraries, take the following steps:

1 Choose More.

Include Library appears.

156 D e v e l o p i n g A d v a n c e d e . R e p o r t s

2 In Include Library:■ Select From a File to locate a library in the file system. Choose Browse if

you want to locate a file in the file system.■ Select From a Web Site to locate a library that is available on the web.

3 Type the file name or the URL to the web site.

To include a library that is available on the web, type a URL similar to the following:

http://<web server>/<pathname>/<library name>

where <web server> is the name of the web server, <pathname> is the path to the library’s location in the web server’s document root directory, and <library name> is the name of the library file.

For example, to include the library Sales.rol on the web server MyCorp that resides in the web server document root’s Lib directory, type the following URL:

http://www.mycorp.com/lib/sales.rol

To include an Actuate Basic file that is available on the web, enter a URL similar to the following:

http://<user>:<password>@<web server>/<pathname>/<library name>

where <user> is the user’s login for the Encyclopedia volume, <password> is the user’s password, <web server> is the name of the web server, <pathname> is the path to the library’s location in the web server’s document root directory structure, and <library name> is the name of the library file.

The user name and password are clear text. They are not encrypted.

For example, you can set up a special Encyclopedia volume user account called Basic, with password cuyahoga, to support including Actuate Basic files over the web. To include the Actuate Basic file My.bas on the web server MyCorp that resides in the web server document root’s Bas directory, type the following URL:

http://basic:cuyahoga@www.mycorp.com/bas/my.bas

4 Choose OK.

Library Organizer appears, showing the files you included under Libraries Included in Your Report.

C h a p t e r 6 , W o r k i n g w i t h l i b r a r i e s 157

5 Choose OK.

How to include a component library or Basic file in a report design by default

1 In Actuate e.Report Designer Professional, choose View➛Options.

Options—Design Editor appears.

2 Choose Libraries.

158 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Options—Libraries appears.

3 Choose Add.

Locate Default Library appears.

4 Navigate to the file you want to add.

C h a p t e r 6 , W o r k i n g w i t h l i b r a r i e s 159

5 Select the file and choose Open.

6 In Options—Libraries, choose OK.

How to remove a component library or Basic file from a design

To remove a component library or Actuate Basic file from a report design:

1 In e.Report Designer Professional, choose Tools➛Library Organizer.

2 In Library Organizer, select the name of the library under Libraries Included in Your Report and click the down arrow. Alternatively, you can double-click the name of the library.

3 Choose OK.

If the library or Actuate Basic file was included in the report design by default, take the following steps:

1 In e.Report Designer, choose View➛Options.

Options—Design Editor appears.

2 Choose Libraries.

Options—Libraries appears.

3 In Default Libraries, select the file you want to remove. Choose Drop.

4 Choose OK.

Locating included librariesActuate e.Report Designer Professional uses relative file paths to locate included libraries. This means that when you include a library in a design, you can specify a full path, a partial path, or just the file name. If the included library is not found in the directory specified by the full path, Actuate e.Report Designer Professional searches the following directories:

1 Directory that contains the referring file

For example, your design and included library files are in C:\Program Files\Actuate7. You move them to C:\My Reports. When the referring design file is opened, Actuate e.Report Designer Professional searches C:\My Reports for the included library file.

2 Design search path

The design search path specifies the directories to search only for the referring design file. It is not used for other files. For information about specifying the design search path, see “How to choose a design search path” in Chapter 5, “Customizing the design environment.”

160 D e v e l o p i n g A d v a n c e d e . R e p o r t s

3 Global search path

The global search path specifies the directories to search for any design file, including the referring file. For information about specifying the global search path, see “How to set a global search path” in Chapter 5, “Customizing the design environment.”

4 Configuration file search path

You can use configuration files to indicate additional directories to search. For information about specifying the configuration file search path, see “Specifying a search path” in Appendix A, “Using a configuration file.”

5 Current working directory

The current working directory is the directory in which you last saved or opened a file.

Placing a library component in a report designOnce you have included a component library in a report design, you can place components from the library into the report design.

If the component’s properties are later changed in the library, these properties also change in your report design. For example, if the author of the library adds, removes, or modifies controls in a frame, the changes affect your report. If you change a property of the component in your report design, however, it does not change in the library.

Subclassing means creating a new component that inherits all characteristics from the library component, including future changes. You make a subclass when you want to make minor changes to the component.

Referencing means creating a link to an existing component rather than creating a new component. You use a reference when an existing component meets your needs and you want to use it as it exists or changes in the future.

When you place a library component in your report design, Actuate e.Report Designer Professional creates a reference to the component, unless the component is a flow or a control. When you drag-and-drop a flow or a control at the top level from a library, Actuate e.Report Designer Professional creates a subclass of the original component. When you drag-and-drop a control in a frame from a library, Actuate e.Report Designer Professional moves the control.

For more information about subclassing and referencing, see “Copying, subclassing, and referencing components” in Chapter 4, “Using Design Editor.”

C h a p t e r 6 , W o r k i n g w i t h l i b r a r i e s 161

When the target design is a component library and you place a component from an included library in the target design, the component is moved from the included library to the target design.

How to place a library component in a design

1 Include the appropriate component library in your design.

For information about how to include a component library, see “How to include an available component library or Actuate Basic file in a report design,” earlier in this chapter.

2 In e.Report Designer Professional, choose View➛Library Browser.

If more than one library is included, Choose Included Module appears.

3 Select the name of the library and choose OK. Alternatively, you can double-click the name of the library.

The Library Browser for the selected library appears.

4 In Library Browser, drag the component you want and drop it in Design Editor.

162 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Modifying components from a libraryYou can modify a component from a library in a report design. If the component is a reference to a library component, e.Report Designer Professional changes it to a local subclass of the library component when you apply the changes. In the structure pane of a report design, components that reference components that reside elsewhere appear in gray.

If you want to change a library component and have the changes reflected in every component that refers to the library component, do one of the following:

■ Open a Library Browser for the library, and change the component in that view.

■ Open the library as the target design, and change the component.

For more information about subclassing and referencing, see “Copying, subclassing, and referencing components” in Chapter 4, “Using Design Editor.”

About read-only librariesIn an environment where report developers share and reuse libraries, it is recommended that these libraries are made read-only so that they are not unintentionally modified. In e.Report Designer Professional, a library can be any one of the following:

■ A report object design (.rod) file.

■ A report object library (.rol) file.

■ A Basic source (.bas) file.

You make a library read-only by using the capabilities of your operating system. If a library is read-only, the words Read-Only appear in the title bar.

C h a p t e r 6 , W o r k i n g w i t h l i b r a r i e s 163

To make and save changes, you must make the library writable or save the library with a different file name.

If a read-only library becomes writable while it is open in e.Report Designer Professional, e.Report Designer Professional recognizes the change and removes the words Read-Only from the title bar. Likewise, if a writable library becomes read-only while it is open in e.Report Designer Professional, Actuate recognizes the change and adds the words Read-Only to the title bar.

164 D e v e l o p i n g A d v a n c e d e . R e p o r t s

C h a p t e r 7 , U s i n g a q u e r y d a t a s t r e a m 165

C h a p t e r

7Chapter 7Using a query data

streamThis chapter contains the following topics:

■ Understanding how reports get data

■ About data source connections

■ Defining a database connection

■ Working with a data stream

■ About organizing data

■ Sorting data effectively

■ About queries

■ Writing a query

■ Using Query by Example (QBE) syntax

■ Synchronizing a query

166 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Understanding how reports get dataBefore a report can display data, it must obtain the data from a source by using a data stream. A data stream is a group of components that queries the database and returns data to your report in an organized fashion. The following diagram shows how data flows from a data source, through a connection, to an Actuate report that uses a data stream. The table below the diagram describes the basic elements that make this connection work.

Data source

Connection

Connection component

Data source

component

Data rowData filter Data row

Report

Data row

Item Description

Data source Stores data. A database is the most common place to get data, but a database is not the only option. For information about other ways to get data, see “About types of data streams,” later in this chapter.

Connection Cable or other communication device and communication software that provide the communication link with the database. For more information about connections, see “About data source connections,” later in this chapter.

Connection component

Stores the information that the report needs to connect to the database. For more information about connections, see “About data source connections,” later in this chapter.

Data source component

Using the connection, selects data from the data source and puts the data into a data row. This chapter concentrates on one type of data source component called a query data source. For more information about query data sources, see “About query data source components,” later in this chapter.

Data row A set of variables containing the data from the data source. The format of this row is defined by the data row component in the report design. For more information about data rows, see “About data rows,” later in this chapter.

C h a p t e r 7 , U s i n g a q u e r y d a t a s t r e a m 167

About data source connectionsA connection is a communication link with a database. An Actuate report design always contains at least one connection component that establishes and maintains the connection between the data source and the report.

Actuate e.Report Designer Professional provides connection components for Microsoft SQL, Sybase, Oracle, Informix, Progress, DB2, SAP, and ODBC database connections.

The connection component stores data source-specific information needed to log on to the data source server, such as server name, user name, and password. Each of these items is a property of the connection component. For example, the user name is set in the UserName property. For more information about properties, see “Setting properties of components” in Chapter 4, “Using Design Editor.”

The data source connection serves two purposes:

■ When you build a query, Query Editor uses the connection to get lists of tables and columns from which you choose.

■ When you run the report, the query uses the connection to get data for your report.

Defining a database connectionIn most report designs, you must define a database connection. To define a database connection, choose Tools➛Database Connection, or see “How to define a database connection,” later in this chapter. For many database connection types, such as Oracle, you must also install a database client before you can connect to the database server.

Data filter (Optional) One or more filters perform additional steps to put the data into the form required by the report. Each filter passes a data row on to the next filter in the data stream. If there are no filters, the data row from the data source component is passed directly to the report. For more information about filters, see “About data filters,” later in this chapter.

Report The report receives data and displays it. The report must contain at least one report section component. For more information about report sections, see “About report sections” in Chapter 11, “Working with sections.”

Item Description

168 D e v e l o p i n g A d v a n c e d e . R e p o r t s

You must also define the database connection on the server before you can successfully deploy the report object executable (.rox) file. For more information about defining a database connection on the server, see Chapter 5, “Working with database connections,” in Administering Actuate iServer System.

Two types of reports do not require you to define a database connection:

■ A report section that shares a connection with another report section. For more information about sharing a connection, see “Sharing connections between report sections” in Chapter 11, “Working with sections.”

■ A report that does not get data from a database. For this type of report, you might need to write a custom data stream. Accessing a flat file of data, for example, requires that you work with a custom data stream. For more information about custom data streams, see Chapter 6, “Customizing a report,” in Programming e.Reports.

How to define a database connection

1 Drag a connection component from the Data palette and drop it into a Connection slot.

For information about which Connection slot to choose, see Chapter 5, “Understanding document generation,” in Programming e.Reports.

2 In Select Component, select the type of connection you require. Choose OK.

C h a p t e r 7 , U s i n g a q u e r y d a t a s t r e a m 169

Component Properties appears.

3 Select the data source from the drop-down list and type the connection properties your database server requires, as shown in the following table.

Connection type

Required connection properties

Optional connection properties

DB2 Name of data sourceDLL PathMaximumStringLengthUser Name

Password might be required, depending on your user account.

Informix User nameDatabase environment (the database and server name)

Password might be required, depending on your user account.

170 D e v e l o p i n g A d v a n c e d e . R e p o r t s

MS SQL User name Server name. If not supplied, e.Report Designer Professional uses a locally defined server as the default server.Password might be required, depending on your user account.

ODBC Name of data source Connection string.User name and password might be required, depending on which driver you are using.

Oracle User nameMaximumStringLengthHost string

Password might be required, depending on your user account.

ProgressSQL89 DatabaseList stringDLL PathStartUpParameters

ReadOnlyQuery. True is the default value.User name and password might be required, depending on your user account.

ProgressSQL92 DatabaseDLL Path. Set to AcPrg9 and cannot be changed.FetchRowBufferCount.The number of rows returned in each fetch. 100 is the default value. Must be less than 65,000.

ReadOnlyQuery. True is the default value.Host.ServiceOrPort.User name and password might be required, depending on your user account.

Connection type

Required connection properties

Optional connection properties

C h a p t e r 7 , U s i n g a q u e r y d a t a s t r e a m 171

Alternatively, you can choose OK and double-click the connection component in the structure pane. You can then set the properties in Component Editor.

For details about the connection properties of a particular connection type, see your DBMS documentation.

If you do not supply the required connection properties by setting them in the connection component, Database Login appears when e.Report Designer Professional needs to connect to the database. You or the report user types the connection properties at that time.

About ODBC connectionsODBC connections use two special connection properties, the data source name (DSN) and connection string.

Before using an ODBC connection, you must create an ODBC data source using the ODBC administrator utility supplied with your ODBC driver software. See your ODBC documentation for information about how to set up the data source. Specify the name of this data source in the DataSource property of the connection component. The data source name can be a User DSN, System DSN, or File DSN.

The connection string includes any other information needed to connect. The contents of this string depends on the driver you are using with your ODBC data source. For example, the connection string could include the name of a Microsoft Excel file. See your ODBC driver documentation for information about the connection string for the driver you are using. Type the connection string in the ConnectionString property field.

SAP Description.Application server IP address.SAP router string.System number.SAP Java Connector libraries.

For more information about connecting to an SAP data source, see “How to configure the report development environment,” in Chapter 10, “Designing a report that uses an SAP BW data stream.”

Sybase User nameMaximumStringLengthServer name

Password might be required, depending on your user account.

Connection type

Required connection properties

Optional connection properties

172 D e v e l o p i n g A d v a n c e d e . R e p o r t s

File DSNs can be shared by users who have the same drivers installed. If the data source name is a File DSN, enter the keyword FILEDSN in the ConnectionString property, for example:

FILEDSN=MYDATA

For information about supported ODBC connections, see

http://www.actuate.com/products/supportedprod.asp

About Progress connectionsFor a ProgressSQL89 connection, the ReadOnlyQuery property’s default value is True. When the ReadOnlyQuery property is set to True, FOR READ ONLY is appended to the SQL SELECT statement to avoid a share-lock problem. Set ReadOnlyQuery to False in the following situations:

■ The SQL statement uses a view or a table and a view. Before you execute a SQL statement on a view, make sure that you have the necessary privileges on the view.

■ There are two data streams that use the same connection. You want to append FOR READ ONLY to one SQL statement but not to the other. Append FOR READ ONLY by overriding the ObtainSelectStatement method for the appropriate DataStream component.

For a ProgressSQL92 connection, the ReadOnlyQuery property has a different meaning. If ReadOnlyQuery is set to the default value True, the transaction mode is set to Read Uncommitted. If ReadOnlyQuery is set to False, the transaction mode is set to Repeatable Read. Setting ReadOnlyQuery to True avoids the problem of lock table overflow.

Working with a data streamA data stream is a group of components that provides the data for your report. The data stream selects data from a data source database and then places the data into the data row structure required by the report.

A data stream can be made up of several types of components. Every data stream has a data source component and a data row component. Additional, optional components include filters, memory buffers, and intermediate data rows.

You can use more than one data stream in a report design by adding more report sections. For more information about report sections, see “About report sections” in Chapter 11, “Working with sections.”

For more information about modifying the data row component, see “Modifying a data row component,” in Chapter 8, “Working with an information object.”

C h a p t e r 7 , U s i n g a q u e r y d a t a s t r e a m 173

About types of data streamsActuate reports can use data streams to get data from any source, not just relational databases. For the purposes of this discussion, data streams fall into these categories:

■ Graphical query

Uses a graphical query data source component to obtain data from a relational database using a SQL query. The rest of this chapter discusses graphical queries in detail.

■ Textual query

Uses a textual query data source component to obtain data from a relational database using a SQL query. For information about textual queries, see Chapter 9, “Using Textual Query Editor.”

■ Stored procedure

Uses a stored procedure data source component to obtain data through stored procedures from the database. For information about stored procedures, see Chapter 10, “Using and customizing a stored procedure,” in Programming e.Reports.

■ Custom data stream

Works with data stored in any format, not just relational databases. For example, use a custom data stream if you want to read data from a flat file or spreadsheet. You can create custom data streams by programming in Actuate Basic. For more information about custom data streams, see Chapter 6, “Customizing a report,” in Programming e.Reports.

About query data source componentsA query data stream always includes at least two components, a query data source and a data row. You can see these components in the structure pane of Design Editor when you are building a report.

The query data source component contains a SQL query, which it uses to retrieve data from the database. Use Query Editor to write the query. For more information about writing queries, see “About queries,” later in this chapter.

Before you write the query, you must add a query data source component to the report design. If you start a new report design by using a report wizard or a blank report, e.Report Designer Professional adds the data stream components to the report design, including the query data source component.

174 D e v e l o p i n g A d v a n c e d e . R e p o r t s

If you want to work with stored procedures rather than a query, you add data stream components by dragging and dropping them. For information about working with a data stream with stored procedures, see Chapter 10, “Using and customizing a stored procedure,” in Programming e.Reports.

How to add a query data source component to a report design

In this procedure, you add query data source and data row components from the Data palette in Design Editor. You can also use a prebuilt query data source or data row from a library or from another report design. For more information about the ways to add components to a report, see “About sources from which you can drag components” in Chapter 4, “Using Design Editor.”

1 Make sure the report design contains a database connection if one is required. For more information about connections, see “Defining a database connection,” earlier in this chapter.

2 Drag a database source icon from the Data palette and drop it in the report section’s DataStream slot.

Select Component appears.

3 Select SQL Query Data Source (Graphical), and choose OK.

4 Drag a data row component from the Data palette and drop it in the query data source component’s DataRow slot.

C h a p t e r 7 , U s i n g a q u e r y d a t a s t r e a m 175

About data rowsA data row is a component that stores the output of a data source component or filter. The data row is a set of data values stored in variables. The list of variables defines the data that you can include in the report.

When you run the report, the data source component instantiates a set of data row objects that contain the data retrieved from the database. For more information about objects and instantiation, see “About Actuate’s object-oriented design” in Chapter 2, “Understanding the design process.”

When you write a query using Query Editor, e.Report Designer Professional adds variables to the data row, depending on which database columns you select. When you write a custom data stream, you must write your own data row.

As you read Actuate documentation and work with Actuate e.Report Designer Professional, keep in mind the difference between the data row component and the data row objects. A data row component is a class you work with when you are designing a report. A data row object is an instance of that class that is instantiated to hold the data coming from the data source when you run the report.

In sum, each report has one data row component, but as you run the report, it can process thousands of data row objects—or none, if no rows match the query.

For more information about modifying a data row component, see “Modifying a data row component,” in Chapter 8, “Working with an information object.”

About data filtersA data filter is a component that can compute new values, perform custom lookups, select rows, and sort and join data. After the data source component has returned a data row, the data might pass through a series of filters before being delivered to the report. You create filters to perform additional steps that could not be accomplished by the query data source component alone. For more information about filters, see Programming e.Reports.

About organizing data In reports, the rows of data can be organized in a particular order. For example, in a sales report you might sort orders alphabetically by customer name. The customers, in turn, might be sorted by city. The set of column or field names that determines sort order is called the sort key.

176 D e v e l o p i n g A d v a n c e d e . R e p o r t s

If your report uses a query data stream, use one or more of the following techniques to sort data:

■ In a grouped report or crosstab, use group sections to specify the sort key. For more information about group sections, see “About group sections” in Chapter 11, “Working with sections.”

■ Use Query Editor to specify additional sort keys for grouped reports. For more information about using Query Editor to sort data, see “Sorting data with Query Editor,” later in this chapter.

■ Use the OrderBy property to specify the sort key. For more information about using the OrderBy property to sort data, see “Sorting data with the OrderBy property,” later in this chapter.

■ Use Query Editor to specify all sort keys. For more information, see “Using presorted data,” later in this chapter.

Sorting data effectivelyMost reports require data to be sequenced in a particular order. Actuate e.Report Designer Professional supports a wide range of data sources from SQL databases to custom data sources such as flat files and spreadsheets. Sorting can be performed on the data source and the rows returned to e.Report Designer Professional in the proper sequence for the report. Alternately, sorting can be internally performed by e.Report Designer Professional using the sort filter, AcMemoryDataSorter. The option used to sort data primarily depends on the capabilities of the data source. SQL databases contain the functionality to sort themselves. Custom data sources cannot sort themselves. Actuate e.Report Designer Professional provides the sort filter to sort custom data sources for reports.

Internal sorting increases report generation time. To sort data effectively, you must know about the following:

■ Using database sort utilities

■ Sorting internally

■ Setting the sorting property

Using database sort utilitiesTo improve report generation performance, sort database utilities in one of the following ways:

■ In the group section’s key property, type the sort key. Actuate e.Report Designer Professional generates a SQL OrderBy clause that contains the sort key you chose.

C h a p t e r 7 , U s i n g a q u e r y d a t a s t r e a m 177

■ Add an OrderBy clause to a SQL statement executing on the database. You can add an OrderBy clause using Query Editor. In supported environments, you add the OrderBy clause to the SQL query executing from within a stored procedure. For information about supported database environments, see the Supported Products matrix:

http://www.actuate.com/products/supportedprod.asp

Sorting internallyUse the sort filter to sort data from custom data sources.The sort filter sorts data using the virtual memory management services of the iServer System. Sort performance depends on the memory available to store the file in memory. Internal sorting for files that contain more than 10,000 records can adversely affect report generation performance.

Setting the sorting propertyYou set the report section’s sorting property to tell e.Report Designer Professional about the sort requirements for the data source. If your data source is in the right sequence for your report, set the sort property to Presorted. If you want e.Report Designer Professional to sort the data source based on the data source’s capabilities, let the sort property use the default value AutoSort. If the sort property is set to AutoSort, the Factory calls the method CanSortDynamically to determine whether the data source can sort itself. If it can sort itself, database utilities sort the data source. Otherwise, e.Report Designer Professional instantiates a Memory Data Sorter filter to sort the data internally.

For information about the developer’s responsibilities for using Actuate e.Report Designer Professional internal sorting, see AcDataAdapter::CanSortDynamically method in Chapter 3, “AFC classes,” in the Actuate Foundation Class Reference.

About queriesA query is a SQL SELECT statement that specifies which data to retrieve from the database. When you use e.Report Designer Professional, you do not need a detailed understanding of the SQL language because you can use Query Editor to graphically select tables, columns, and other query options. Actuate e.Report Designer Professional writes the SQL SELECT statements as you make selections in Query Editor. A familiarity with SQL, however, helps you write better queries. If you have never written a SQL query or used a query building tool, refer to your SQL or DBMS documentation.

178 D e v e l o p i n g A d v a n c e d e . R e p o r t s

If you have a detailed understanding of SQL, you might want to use Textual Query Editor instead of the graphical Query Editor. For more information about Textual Query Editor, see Chapter 9, “Using Textual Query Editor.”

You can convert structured queries designed in the graphical Query Editor into textual queries, but you cannot convert textual queries into structured queries.

How to convert graphical queries into textual queries

1 Open the graphical Query Editor.

2 Choose SQL➛Edit SQL on the menu bar.

A warning appears to remind you that you cannot convert the query back to a graphical format.

3 Choose Yes.

Textual Query Editor appears.

C h a p t e r 7 , U s i n g a q u e r y d a t a s t r e a m 179

About SQL SELECT statementsSELECT is a statement in SQL, a language commonly used for database applications. The SELECT statement specifies which data you want to retrieve from the database. The SQL SELECT statement is divided into parts called clauses. The following diagram shows how you create each clause graphically in Query Editor.

For more information about how to perform these actions in Query Editor, see “Writing a query,” later in this chapter.

Comparison of WHERE and HAVING conditionsYou can impose two kinds of conditions as part of a query:

■ Conditions on row retrieval. Define these conditions in the WHERE clause. In Query Editor, use the Conditions page to specify these conditions.

Your action in Query Editor Text Actuate writes in SELECT

Specify tables FROM clause

Create joins Part of the WHERE clause

Select columns SELECT clause

Put conditions on row retrieval WHERE clause

Sort data ORDER BY clause

Summarize data GROUP BY clause

Put conditions on aggregate rows HAVING clause

180 D e v e l o p i n g A d v a n c e d e . R e p o r t s

■ Conditions on aggregate rows. Define these conditions in the HAVING clause. In Query Editor, use the Having page to specify these conditions.

When a query runs, it follows these steps to apply conditions:

1 The query retrieves all rows that meet the row retrieval conditions. For example, the query could select salary numbers for all departments in a specific company.

2 The query groups those rows, as specified in the GROUP BY clause, and creates aggregate rows that summarize the groups. For example, the query could combine the salary numbers by department and create rows containing the average salary for each department.

3 The query applies the second set of conditions to the aggregate rows it created. For example, the query could select those departments with an average salary greater than the company average.

When you want to select data based on values in individual rows in the database, use row retrieval (WHERE) conditions. When you want to select data based on values, such as total order amounts, that are not known until after the query creates aggregate rows, use aggregate row (HAVING) conditions.

Comparing GROUP BY and ORDER BYWhen a query contains a GROUP BY clause, the SELECT clause must contain only the group column and aggregate expressions. The GROUP BY clause groups rows based on the group column, and the aggregate expressions calculate values for each group. The GROUP BY clause does not put the groups in order. To order the groups, use an ORDER BY clause.

In the following example, the query contains a GROUP BY clause. The SELECT clause contains the group column, items.category, and an aggregate expression, AVG(items.pricequote). The GROUP BY clause groups the rows in the items table by category, and the aggregate expression AVG(items.pricequote) calculates the average price for each category. The ORDER BY clause sorts the categories alphabetically:

All rows returned by WHERE

Aggregate rows created by GROUP BY

Aggregate rows returned by HAVING

C h a p t e r 7 , U s i n g a q u e r y d a t a s t r e a m 181

SELECT items.category, ( AVG(items.pricequote) ) As avgpriceFROM itemsGROUP BY items.categoryORDER BY items.category

Category Average price------------- --------------------Controller $217.00Driver $235.00DSP $271.00Dynamic Ram $38.00Processor $438.00Static Ram $93.00

Writing a queryActuate e.Report Designer Professional provides a graphical tool called Query Editor. To write a query using Query Editor, perform the following procedures in order. For each procedure in this list, there is a corresponding section with detailed, step-by-step instructions.

Required procedures

■ Opening Query Editor

■ Selecting tables

■ Selecting columns

■ Creating computed columns

Optional procedures

■ Creating joins

■ Putting conditions on row retrieval (WHERE)

■ Sorting data with Query Editor

■ Sorting data with the OrderBy property

■ Summarizing data

■ Putting conditions on aggregate rows (HAVING)

■ Viewing the SELECT statement

182 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Opening Query EditorFor Query Editor to work, Actuate e.Report Designer Professional must be able to establish a database connection. If you do not already have an open database connection when you start Query Editor, Actuate e.Report Designer Professional attempts to connect to a database using the connection properties defined in the connection component.

If the connection component does not contain the necessary information, Actuate e.Report Designer Professional cannot connect. Database Login appears so that you can supply the necessary information.

For more information about defining a connection, see “Defining a database connection,” earlier in this chapter.

How to open Query Editor

1 Choose View➛Data Source.

If e.Report Designer Professional is able to connect to the database, Query Editor and Database Browser appear. If e.Report Designer Professional is unable to connect to the database, Database Login appears.

2 In Database Login, type the required information and choose OK.

Some of the fields in Database Login might already be filled in, depending on whether these values were set in the connection component. For more information about defining connection properties, see “Defining a database connection,” earlier in this chapter.

How to customize Query Editor display

To lengthen or shorten the column names that appear in Query Editor pages, choose SQL➛Column Qualifiers, and then choose one of the following:

■ Full Name—Displays the database, schema, table, and column name in the following format:

sales.dbo.customers.phone

■ Table and Column—Displays the table and column name in the following format:

customers.phone

C h a p t e r 7 , U s i n g a q u e r y d a t a s t r e a m 183

Selecting tablesBegin writing the query by selecting which database tables contain the information you want in your report. Database Browser shows a graphical representation of all the tables to which you have access.

Database Browser can display views, system tables, and table and view synonyms depending on which database management system you are using.

As you choose tables, Actuate e.Report Designer Professional writes the FROM clause of the SQL SELECT statement.

For more information about working with a database that includes table and view synonyms, see “Working with table and view synonyms,” later in this chapter.

If you are using an AcProgressConnection with a Progress 9.x database, tables not owned by PUB and views created with the SQL92 engine are not available in Database Browser.

Using the same table multiple timesYou can add the same table to the query more than once. For example, you might want to use a table of address data to obtain both a Ship To address and a Bill To address in the same data row or use a table of physician data to obtain

Server

Database or schema

Tables

Columns

184 D e v e l o p i n g A d v a n c e d e . R e p o r t s

both the referring physician and treating physician for a health care claim form.

When you add a table that already exists in the query, a dialog appears in which you can specify an alias, or additional name, for the table. If you do not specify an alias, e.Report Designer Professional uses a default alias value.

How to select tables

1 Click the plus icons in Database Browser until the tables you want appear.

2 Drag one or more tables from Database Browser and drop them in the upper pane of Query Editor.

If you experience poor performance when you drop tables in Query Editor or your database contains more than 100 tables, make sure Auto Joins is disabled. If Auto Joins is enabled, choose SQL➛Auto Joins.

3 If you drop a table more than once, Alias Name appears.

To change the default alias e.Report Designer provides, type a new name in the Alias field. Choose OK.

4 To delete a table from the Tables and Joins page, select the table and press Delete.

C h a p t e r 7 , U s i n g a q u e r y d a t a s t r e a m 185

Modifying table properties in a queryAfter you add a table to a query, you can change some properties. You can indicate how table and column references appear in the SQL code that Actuate e.Report Designer Professional writes. For example, if you have several schemas with identical structures, as described earlier, you should use an alias to identify which table to access in a query. Use the Owner property as necessary for your particular database.

For more information about displaying an owner name qualifier in Database Browser, see “Displaying an owner name qualifier in Database Browser,” later in this chapter.

How to modify a table in a query

1 In the upper pane of Query Editor, double-click a table.

Query Editor—Table Property appears.

2 To change the table name, select or type new names in the following fields:■ Qualifier■ Owner■ Table or View

3 To choose the format you want e.Report Designer Professional to use when referring to tables in the SQL SELECT statement, select one of the following options in Name Qualification:■ qualifier.owner.table■ owner.table■ table

For information about the Alias field, see “Using the same table multiple times,” earlier in this chapter.

186 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Displaying an owner name qualifier in Database BrowserOptions—Query Editor settings for Database Browser determine which qualifiers, owners, and tables and views appear when you log into a database. For databases that support a three-level hierarchy, Database Browser displays the fully qualified table name using the following format:

<qualifier><owner name>.<table name>

For databases that support a two-level hierarchy, Database Browser displays the fully qualified table name using the following format:

<qualifier><table name>

Specifying tables to appear in Database BrowserYou can limit the tales and views that appear in Database Browser using Options—Query Editor. If a database contains tables and views identified by <owner name>.<table name>, you can specify a value of <owner name> to appear in Database Browser. Also, you can specify a value for <table name> to display tables that match that value.

How to specify which tables appear in Database Browser

1 Choose View➛Options➛Query Editor.

Options—Query Editor appears.

2 In Owner pattern match, type a pattern to limit the table owners that appear in Database Browser.

For example, if you type ma* in Owner pattern match, Database Browser displays the owners whose names begins with ma.

3 In Table and view pattern match, type a pattern to limit the tables that appear in Database Browser.

For example, if you leave Owner pattern match empty and you type s* in Table and view pattern match, Database Browser displays the tables whose names begin with s.

Choose OK.

Customizing the FROM clauseIf the FROM clause that Actuate e.Report Designer Professional generates is not suitable for your query, you can write your own FROM clause.

You can also customize the FROM clause by overriding the ObtainSelectStatement method. For more information about the ObtainSelectStatement method, see Actuate Foundation Class Reference.

C h a p t e r 7 , U s i n g a q u e r y d a t a s t r e a m 187

How to customize the FROM clause

1 In DataSource—Query Editor, choose SQL➛Custom From Clause.

Custom FROM Clause appears.

2 Choose Use Custom FROM Clause.

3 Type the FROM clause.

In the following illustration, the parameters :[OrderHeader.DateOrdered] and :[OrderHeader.DateShipped] are static parameters, not ad hoc parameters. For more information about parameters, see Chapter 18, “Designing a report parameter.”

Choose OK.

If you choose Use Default FROM Clause before you choose OK, e.Report Designer Professional does not use your custom FROM clause.

Working with table and view synonymsDevelopers create table and view synonyms in databases for the following purposes:

■ To provide a more meaningful name for a table or view than the base name in the database. If a database was developed in a foreign country, for example, you might rename the tables and views in your native language.

■ To protect applications from changes in the base table name that might occur over the life of a database.

188 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Table and view synonyms give you two options:

■ View and work with the base name of a table or view and its dependencies.

■ View and work with the synonym name of the table or view and its dependencies.

Actuate e.Report Designer Professional supports Oracle synonyms for tables and views.

Because synonyms act as aliases, they support working with tables and views when you do not know the specific location of those tables and views. When you develop a synonym for a table or view, the synonym remains connected to the original associated files.

In a database, the base name is the name of a database object, which can be a table or a view. A developer created the base name when creating the table or view in the database.

Views and tables can have multiple synonyms in a database. Because Actuate e.Report Designer Professional is a read-only application when it works with databases, you cannot create synonyms using Actuate e.Report Designer Professional. In Database Browser, the text to the right of the synonym explains on which object the synonym was defined.

When Actuate e.Report Designer Professional accesses a database, it accesses all objects available to the user. Database Browser and Options—Query Editor determine what appears. If you change selections in Options—Query Editor, view Database Browser to see how your selections affect its appearance. DataSource—Query Editor works with a table or view synonym in the same way that it works with a table or view base name. The only difference is the name of the table and view.

For more information about modifying table properties, see “Modifying table properties in a query,” earlier in this chapter. For more information about displaying an owner name qualifier in Database Browser, see “Displaying an owner name qualifier in Database Browser,” earlier in this chapter.

How to view table synonyms options

1 Choose View➛Options.

Options—Design Editor appears.

2 Choose Query Editor.

Options—Query Editor appears.

C h a p t e r 7 , U s i n g a q u e r y d a t a s t r e a m 189

3 In Tables and Views, select one of the following options:■ Show Tables and Views■ Show Tables Only■ Show Views Only

The default setting is Show Tables and Views.

4 In Names, select one of the following options:■ Base Names■ Synonyms■ Base Names and Synonyms

The default setting is Base Names.

5 If you select Show System Objects, the database objects the user did not build appear.

Choose OK.

190 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Selecting columnsYou can write a query to retrieve all columns or only some of the columns from each table. You can also make the order of the columns in the data row different from their order in the database. As you select columns, e.Report Designer Professional writes the SELECT clause of the SQL SELECT statement and declares variables in the data row.

How to select columns

1 In the lower pane of DataSource—Query Editor, choose Columns.

DataSource—Query Editor—Columns appears.

2 Select columns using one of the following methods:■ In Column Name, use the drop-down list to select the column you want.■ Drag the columns from the upper pane of DataSource—Query Editor

and drop them in Column Name.

You can select multiple columns and drag them all at the same time. To select all columns, drag the asterisk (*). This technique selects all the columns in the table at the time you run the report object executable (.rox) file, which might not be the same as the columns listed now in Query Editor.

C h a p t e r 7 , U s i n g a q u e r y d a t a s t r e a m 191

How to change column order and data type

1 In Columns, select the column name.

2 Choose the up arrow or down arrow.

3 To change the Actuate Basic data type of the column in the report’s data row, do one of the following:■ Double-click the column name in the upper pane of Query Editor.

In Column Property, the Database Type field displays the data type of the column in the database.

In Actuate Basic Type, select the Actuate Basic data type you want.

■ In the lower pane of Query Editor, in Columns, click in a field under Actuate Type. Choose a data type from the drop-down list.

How to delete columns

To delete a column using Query Editor, in Columns, select the column name and press Shift+Delete.

Creating computed columnsInstead of using a single column from the database, you can create a computation. This computation can involve one or more columns. For

192 D e v e l o p i n g A d v a n c e d e . R e p o r t s

example, to make the query return the extended price for an item in a sales order, you might use the computation [items.price] * [items.quantity].

To create a computed column, do one of the following:

■ In Design Editor, choose Insert➛Computed Field and drop the control in the appropriate location in your report design.

Using Expression Builder, build the expression for the computed field.

■ In Design Editor, drag <Computed> from Field List and drop it in the appropriate location in your report design.

Using Expression Builder, build the expression for the computed field.

■ Use the Columns page of Query Editor, as explained in “How to create a computed column with Query Editor,” later in this chapter.

How to create a computed column with Query Editor

1 In Query Editor, choose Columns.

2 In Column Name, type a name for the computed column.

3 In Actuate Type, choose a data type from the drop-down list.

4 In Formula, type the expression that computes the value of the column. For more information about this syntax, see “Using Query by Example (QBE) syntax,” later in this chapter.

If you want more room to type the expression, choose Builder to open Expression Builder.

If the expression evaluates to a string, the string must not exceed 1021 characters. If the string exceeds 1021 characters, e.Report Designer Professional gives an error.

If you are planning to use aggregate rows in the query, use one of the aggregate functions Sum( ), Min( ), Max( ), Ave( ), First( ), Last( ), or Count( ). For more information about aggregate functions, see “Computing

Type new name Type expression

Choose Builder

C h a p t e r 7 , U s i n g a q u e r y d a t a s t r e a m 193

aggregates in a value expression” in Chapter 12, “Working with frames and controls.”

5 In Actuate Type, choose a data type from the drop-down list.

When you change a formula, Actuate e.Report Designer Professional resets the type to Variant.

Creating joinsWhen you select more than one table, e.Report Designer Professional creates joins to link related tables if it can determine the columns on which the tables are joined. A join is a SQL query operation that combines records from two tables and returns them in a result set based on the values in the join fields. For example, customer and order tables could be joined on a common field such as customer ID. The result set would contain combined customer and order records where the customer IDs are equal.

Without a join operation, you would have to assume that the data in the tables is in the correct order. If the data were not in order, the result set might contain a customer from one table and an order from another. This would give an inaccurate picture of what one customer is ordering.

To decide where joins should occur, e.Report Designer Professional applies these criteria in order:

1 The relationship information, if available, in the data dictionary of a database.

2 Primary and foreign keys.

3 Matching column names and types.

For Progress8 and Progress9 with the SQL89 engine, some differences apply:

■ Joins are not defined in the database.

■ Actuate e.Report Designer Professional does not create joins based on matching column names and types.

These differences apply regardless of whether you are using a native or an ODBC connection. Therefore, you must create the joins manually. For more information about creating joins, see “How to create a join,” later in this chapter.

For more information about joins, primary keys, and foreign keys, refer to your DBMS documentation.

The joins e.Report Designer Professional creates might not match the actual structure of your database schema. If you need to find out about the joins in your database, ask your database administrator for a schema diagram.

194 D e v e l o p i n g A d v a n c e d e . R e p o r t s

You can also establish joins using Query Editor. The types of join you can create depend on your database management system. Query Editor supports the following types of joins.

As you create joins, Actuate e.Report Designer Professional writes the WHERE clause of the SQL SELECT statement.

How to create a join

1 In Query Editor, drag the primary key column name from a table and drop it on the foreign key column name in another table.

2 If your primary key requires more than one column to establish a unique value, repeat step 1 to drop additional column names on the same foreign key.

For example, in a database of parts from several manufacturers, the part ID alone might not be unique. Several manufacturers might use the same number. You would need to use both the part ID and manufacturer name to establish a unique key.

3 To change the type of join, double-click the join operator icon.

Type of join Description

Inner join Returns records from two tables where the values of the joined fields have a specified relationship, such as equal to or greater than.

Left outer join Returns records from the leftmost table even if there are no matching values in the other table.

Right outer join Returns records from the rightmost table even if there are no matching values in the other table.

Primary key Foreign key

C h a p t e r 7 , U s i n g a q u e r y d a t a s t r e a m 195

4 In Join Properties, to change the join operator, select an operator from the drop-down list.

5 To create a left or right outer join instead of an inner join, select one of the options in Type of Join.

How to delete a join

1 Select the join line or join operator.

2 Press Delete.

Double-click here

Select

196 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Putting conditions on row retrieval (WHERE)You can specify conditions that must be met by the rows in the database. For example, rather than retrieving information about all customers, you can retrieve information about customers in a certain state. As you put conditions on row retrieval, Actuate e.Report Designer Professional adds them to the WHERE clause of the SQL SELECT statement.

For more information about conditions, see “Comparison of WHERE and HAVING conditions,” earlier in this chapter.

There are two methods for putting conditions on row retrieval. You can use either or both of the following methods in a single query:

■ Use simple Query by Example (QBE) expression syntax. When you specify more than one condition using the QBE syntax, all must be True for a particular row to be returned. That is, you can specify only AND conditions. You use QBE to place conditions on one column at a time.

■ Use SQL syntax. Use this syntax to specify an OR condition or to specify a condition that involves more than one column.

How to put conditions on row retrieval

1 In the lower pane of Query Editor, choose the Conditions page.

2 Choose a column in one of the following ways:■ Drag the column from the upper pane of Query Editor and drop it in the

Conditions page.■ In the Conditions page, click under Column Name and select a column

name from the drop-down list.

3 Choose a condition in one of the following ways:■ In Query Expression, type the conditions you want to apply, using the

QBE expression syntax. For more information about this syntax, see “Using Query by Example (QBE) syntax,” later in this chapter.

If you want more room to type the expression, choose Builder to open Expression Builder.

■ Type a SQL expression in the lower part of the page. This expression can include any valid SQL syntax, including nested SELECT statements.

■ If you want users to type conditions when they run the report, select Ad Hoc. For more information about ad hoc parameters, see “Defining and configuring an ad hoc parameter” in Chapter 18, “Designing a report parameter.”

■ If you want users to type a single value when they run the report, create a static parameter. For more information about static parameters, see “Defining a parameter” in Chapter 18, “Designing a report parameter.”

C h a p t e r 7 , U s i n g a q u e r y d a t a s t r e a m 197

4 To add more conditions, repeat steps 2 and 3.

5 To delete a column from the Conditions page, select the column name and press Shift + Delete.

Sorting data with Query EditorYou can change the order of the retrieved rows by specifying one or more columns to define a sort key.

If your report includes group sections, they determine the sort order. The sort keys in group sections take precedence over those specified using Query Editor. Use Query Editor to specify sorting in the following circumstances:

■ You are not using group sections.

■ You want to perform sorting in addition to that which is performed by the group sections.

■ You want to use custom sorting instead of the automatic sorting provided by group sections.

For an overview of sorting, see “Sorting data effectively,” earlier in this chapter. For more information about group sections, see “Sorting data with group sections” in Chapter 11, “Working with sections.”

As you use Query Editor to select columns for sorting, e.Report Designer Professional adds them to the ORDER BY clause of the SQL SELECT statement. If it is not possible to modify the ORDER BY clause of the SQL SELECT statement, you can sort data with the OrderBy property. For more information about the OrderBy property, see “How to sort data using the OrderBy property,” later in this chapter.

Specify column name

Type QBE syntax Type SQL syntax

Select to allow user to enter conditions

Choose Builder

198 D e v e l o p i n g A d v a n c e d e . R e p o r t s

How to sort data using Query Editor

1 In Query Editor, choose Order By.

2 From Available Columns, select one or more columns to be your sort key.

3 Choose the left arrow.

The column names appear in Order By.

4 To change the order of the columns in the sort key, do the following:

1 In Order By, select the column name.

2 Choose the up arrow or down arrow.

5 To sort a particular column in descending order, deselect Asc.

6 To delete a column from the Order By page, select the column name and press Shift + Delete.

Sorting data with the OrderBy propertyYou can sort data with the OrderBy property. Sorting data with the OrderBy property does not change the ORDER BY clause of the SQL SELECT statement. Use the OrderBy property when:

■ The query is from a library, so e.Report Designer Professional cannot modify it.

■ The query is typed as text in a method, so Actuate e.Report Designer Professional cannot modify it.

■ The report design uses a data stream that is not a query, for example a flat file or a stored procedure.

Select columnsAdd or remove column

Select ascending or descending alphabetical sort

Change column order in sort key

C h a p t e r 7 , U s i n g a q u e r y d a t a s t r e a m 199

If you specify a sort order using the report wizard or Sorting and Grouping—Sorting, e.Report Designer Professional modifies the OrderBy property accordingly but does not change the ORDER BY clause of the SQL SELECT statement.

How to sort data using the OrderBy property

1 If the structure pane is not visible, choose View➛Report Structure.

2 Double-click the report section component in the structure pane.

3 In Component Editor, for the OrderBy property, type a column name or a list of column names separated by commas. Alternatively, choose a column from the drop-down list.

4 Choose Close.

Using presorted dataYou can sort data using only the ORDER BY clause of your query without taking advantage of the sorting provided by group sections. Set the sorting properties of the report section to Presorted. Use the Presorted selection when:

■ The query from a read-only library requires no modification.

■ Specialized sorting is performed in the query, which you should not modify.

How to use presorted data

1 Double-click the report section component in the structure pane.

Component Editor appears.

200 D e v e l o p i n g A d v a n c e d e . R e p o r t s

2 For the Sorting property, choose Presorted from the drop-down list.

3 In Query Editor, set the Order By to provide the required row order.

Summarizing dataTo summarize a group of retrieved data, you create an aggregate row. An aggregate row is a single row that combines the data from a group of rows when those rows have one or more columns in common. For example, you can group all the rows for a particular customer and create one aggregate row that contains the total number and average dollar amount of all that customer’s orders.

To create an aggregate row, you first specify aggregate expressions in the Columns page of Query Editor, then specify column names in the Group By page.

As you write aggregate expressions, e.Report Designer Professional adds them to the SELECT clause of the SQL SELECT statement. As you select columns for aggregate rows, e.Report Designer Professional writes the GROUP BY clause of the SQL SELECT statement.

For more information about the GROUP BY clause, see “Comparing GROUP BY and ORDER BY,” earlier in this chapter.

How to summarize data

1 Create columns that compute aggregate values by following the steps in “Creating computed columns,” earlier in this chapter.

2 In Query Editor, choose the Group By tab.

If the Group By tab is hidden:

1 Choose View➛Options.

Options—Design Editor appears.

2 Choose Query Editor.

Options—Query Editor appears.

3 Select Enable Group By and Having editors.

Choose OK.

C h a p t e r 7 , U s i n g a q u e r y d a t a s t r e a m 201

3 From Available Columns, choose one or more columns to be the basis of your aggregate rows.

You must choose all of the columns that appear in the SELECT clause of the query. That is, choose all the columns you dragged into the Columns page.

4 Choose the left arrow.

The column names appear in Group By.

5 To delete a column from the Group By page, select the column name and press Shift+Delete.

Putting conditions on aggregate rows (HAVING)You can set conditions that must be met by the aggregate rows. For example, rather than including aggregate rows for all customers, you can include only customers with order totals of more than $10,000. As you put conditions on aggregate rows, e.Report Designer Professional writes the HAVING clause of the SQL SELECT statement.

For more information about how to specify aggregate rows, see “Summarizing data,” earlier in this chapter. For more information about conditions, see “Comparison of WHERE and HAVING conditions,” earlier in this chapter.

There are two methods for putting conditions on aggregate rows. You can use either or both of these methods in a single query:

■ Use QBE expression syntax.

■ Use SQL syntax.

When you set more than one condition using QBE syntax, all must be True for a particular row to be returned. That is, you can set only AND conditions. To set an OR condition, use the SQL syntax. To set a condition that involves more than one aggregate row, use the SQL syntax.

How to put conditions on aggregate rows

1 In Query Editor, choose Having.

If Having is hidden:

202 D e v e l o p i n g A d v a n c e d e . R e p o r t s

1 Choose View➛Options.

Options—Design Editor appears.

2 Choose Query Editor.

Options—Query Editor appears.

3 Select Enable Group By and Having editors.

Choose OK.

2 Click under Column or Aggregate, and choose an aggregate name from the drop-down list.

3 Set a condition in one of the following ways:■ In Query Expression, type the conditions you want to apply, using the

QBE expression syntax. For more information about this syntax, see “Using Query by Example (QBE) syntax,” later in this chapter.

If you want more room to type the expression, choose Builder to open Expression Builder.

■ Type a SQL expression in the lower part of the page. This expression can include any valid SQL syntax, including nested SELECT statements.

4 To add more conditions, repeat steps 2 and 3.

5 To delete a column from the Having page, select the column name and press Shift + Delete.

Viewing the SELECT statementUse the SQL page to look at the SQL SELECT statement. Actuate e.Report Designer Professional writes this statement while you make choices in the other pages of Query Editor. You can copy the SQL SELECT statement from the SQL page to the Clipboard.

Type QBE syntax Type SQL syntax

Specify aggregate name

Choose Builder

C h a p t e r 7 , U s i n g a q u e r y d a t a s t r e a m 203

How to view the SELECT statement

1 In Query Editor, choose the SQL page.

2 Review the SQL SELECT statement that Actuate e.Report Designer Professional writes as you work with Query Editor.

How to copy the SELECT statement to the Clipboard

1 In the SQL page of Query Editor, select the text you want to copy.

2 Choose Edit➛Copy.

Optimizing SQL queriesMost commonly used SQL statements are built using Query Editor in e.Report Designer Professional. Optimized SQL queries contain special clauses or keywords that yield performance benefits in your database environment. Consult with your database administrator or vendor for information about constructing optimized SQL statements. You can write an optimized SQL query in Textual Query Editor. For information about using Textual Query Editor, see Chapter 9, “Using Textual Query Editor.”

To evaluate the performance impact of a SQL statement, run the query in your database environment. You can also use the following technique to measure the performance of optimized SQL statements in e.Report Designer Professional.

How to measure performance

1 Select the data stream component containing the data source for your report.

2 Create the variable Start_Time as a Double data type.

204 D e v e l o p i n g A d v a n c e d e . R e p o r t s

3 Type the following code in the Start( ) method:

Function Start( )Super::Start( )

ShowFactoryStatus(“Starting report”)Start_Time = Now

End Function

4 Type the following code in the Finish( ) method:

Sub Finish( ) Dim Finish_Time as Double, Elaspsed_Time as Double

Dim Duration as String

Super::Finish( )

Finish_time = Now( )

Elapsed_Time = Finish_Time - Start_TimeElapsed_Time = Elapsed_Time * (24 * 3600)Elapsed_Time = CInt(Elapsed_Time)Duration = CStr(Elapsed_Time)

ShowFactoryStatus(“Elapsed time (seconds): “ + Duration)

End Sub

Using Query by Example (QBE) syntaxActuate e.Report Designer Professional provides a simple Query by Example (QBE) syntax with which you write expressions that e.Report Designer Professional translates into SQL. The QBE syntax is useful only in reports that use a query data stream. Use QBE syntax in the following situations:

■ To set conditions on row retrieval in the Conditions page of Query Editor.

■ To set conditions on aggregate rows in the Having page of Query Editor.

■ To choose values for ad hoc parameters in Actuate Active Portal request page.

In all three cases, e.Report Designer Professional reads the QBE expression and adds the corresponding SQL code to the query. For information about QBE syntax, see Chapter 4, “Running a report,” in Using e.Reports.

C h a p t e r 7 , U s i n g a q u e r y d a t a s t r e a m 205

The values in all types of QBE expressions must be of the correct data type. For example, you cannot use a string value for a numeric column. If e.Report Designer Professional cannot convert a value in a QBE expression to the data type required by the database column, the word <ERROR> appears in the SQL code.

For more information about how QBE syntax is used with different types of parameters, see Chapter 18, “Designing a report parameter.”

The QBE syntax is different from the syntax you use to specify search criteria in the Search dialog when you are viewing a report. For information about that syntax, see Chapter 5, “Working with an information object for Actuate Query,” in Using e.Reports.

How to enter Query by Example (QBE) expressions as Query conditions

Use Query Editor to enter QBE expressions.

1 In the Conditions page, in Column Name, enter a database column name such as items.pricequote.

2 In Query Expression, type a QBE expression such as the following:

>100

3 Choose the SQL page to display the following code:

SELECT items.itemspricequoteFROM itemsWHERE items.pricequote>100

Synchronizing a queryWhen you create a query in a report design, the query addresses information in the database to which you are connected. The relevant structure of the database, known as the database schema, or data dictionary, is stored with the report object design (.rod) file or report object library (.rol) file. The database

206 D e v e l o p i n g A d v a n c e d e . R e p o r t s

schema evolves as the database design evolves. Therefore, a query in a report object design that originally addressed a certain set of tables and views in a database can increasingly become out of sync with the database schema, and therefore the database, to which it connects.

One way of synchronizing the query with the changing schema is to work in the upper pane of Query Editor. You can drop the table or view, and then add the table or view back to the query. Dropping and then adding updates the new definitions as provided by the database. Dropping a table or view also, however, removes the WHERE and ORDER BY conditions that might have been in the query.

About the query synchronization toolsThe query synchronization tools in e.Report Designer Professional help you efficiently work with the problem of an outdated query. Query synchronization supports the following:

■ Displaying and analyzing the differences between the tables defined in the query and those in the database.

■ Deciding which changes you want to implement for the areas where your query is out of date.

The query synchronization tools go deeper than the tables and views level, however, because changes in the database can occur at any level. Columns can be deleted or renamed. Data types can change. The synchronization tools are able to handle these kinds of lower-level changes.

Query synchronization is different from, but also includes, verifying a SQL statement. Query synchronization supports the user synchronizing and updating the query. Then the process verifies the SQL statement.

You can choose to verify a SQL statement without synchronizing the query. When you verify a SQL statement, you are checking to see only whether your SQL statement has valid syntax.

Understanding changes to a report design during query synchronizationBecause of changes that can occur when you synchronize a query, it can be helpful to create a copy of your original report object design (.rod) file before you begin. Then you can observe the behavior of the synchronization process before you commit to a changed, updated query. Also consider the following before you begin with the synchronizing processes:

■ The query synchronization process contains several automatic updating features. As a result of choosing to accept an update, new columns might

C h a p t e r 7 , U s i n g a q u e r y d a t a s t r e a m 207

be added. Column data types also might change when you choose to accept an update.

■ If you have synchronized a query that causes a data type to change and that data is reflected in a control in the report design, the Factory processes check for compatibility at build time. The build process also checks for incompatible or deleted column types. For more information about what the build, run, and view processes examine, see “Understanding how Actuate builds a report,” in Chapter 2, “Understanding the design process.”

■ Customized methods, which refer to a parameter or row variable that is changed as a result of synchronization, are not reported or updated.

■ Developer-defined methods are not reported or updated.

About the steps of query synchronizationQuery synchronization involves six major steps:

1 Ensuring the connected database is correct.

2 Refreshing the data dictionary.

3 Using Synchronize Query With Schema

4 Analyzing tables and columns.

5 Using other tools on the query.

6 Changing the Actuate Basic type while checking the query.

Information about each step follows.

Step 1: Ensuring the connected database is correctFor query synchronization to work effectively, the report design must reference the correct database. You have an opportunity to check whether you are connected to the correct database before you begin synchronization. When you work with several versions of a database, it is easy to lose track of the one to which you are connected.

Many databases, such as Sybase, are not file based. Other databases, such as Microsoft Access, are file-based. A database that is not file-based is connected and installed differently from a database that is filed based. Because of the differences, the databases are checked in different ways. The following steps explain how to check each type.

208 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Query Editor displays the Sybase qualified database name, such as AcTestDB, in Database Browser.

1 In Query Editor, select a table. Choose View➛Properties.

2 In Query Editor—Table Property, change the qualifier to the correct database if necessary.

For information about using Query Editor—Table Property, see “Modifying table properties in a query,” earlier in this chapter.

If you are working with a file-based database, such as MS Access, and you have installed your version of e.Report Designer Professional in a nonstandard location, or if you are unsure of the full path names of the databases with which you are working, you might need to ensure that the full path names match.

Several of the example reports in the e.Report Designer Professional Example directory use Access databases. Access displays the full path name of the connected database, and its installed location, in Database Browser.

To examine whether file paths match, do the following:

1 Compare the path name shown at the top of Database Browser with the qualified path name that appears in Query Editor—Table Property.

C h a p t e r 7 , U s i n g a q u e r y d a t a s t r e a m 209

2 If these path names do not match, change the file path in Query Editor—Table Property to the correct path of the database to which you want to connect.

3 Choose Apply to initiate the table consistency check.

Step 2: Refreshing the data dictionaryWhen you implement query synchronization, the processes examine the data dictionary, which is stored with the report object design (.rod) file. The data dictionary is basically a snapshot, or copy, of the database schema in the connected database. It is desirable to have the most up-to-date data dictionary when you are synchronizing a query.

The database schema of the connected data source could change while Query Editor is open. In this case, the data dictionary needs to be refreshed against the live database, so the query can be compared with the latest database schema changes.

You can set the data dictionary to be refreshed each time a query is checked.

To indicate that you want to refresh the data dictionary, do the following:

1 In Query Editor, choose View➛Options.

Options—Design Editor appears.

2 Choose Query Editor.

Options—Query Editor appears.

210 D e v e l o p i n g A d v a n c e d e . R e p o r t s

3 Select Refresh Data Dictionary when checking a query. Choose OK.

When you choose to refresh the data dictionary, it takes longer to check a query.

Step 3: Using Synchronize Query With SchemaAfter you check Query Editor—Table Property to ensure the necessary path qualifications match, and after you decide whether to refresh the data dictionary, you are ready to begin the steps of synchronizing the query. During synchronization, you can copy information about nonsynchronized tables and columns for use by the database administrator. You can paste this information into a clipboard, another window, or another application.

1 In Query Editor, choose SQL➛Synchronize Query.

Alternatively, you can choose Synchronize Query With Schema on Query Editor toolbar.

If the query is not synchronized, the following processes occur.■ Synchronize Query With Schema appears.

C h a p t e r 7 , U s i n g a q u e r y d a t a s t r e a m 211

■ Actuate e.Report Designer Professional displays information about nonsynchronized tables and columns as follows:- The tables listed in the upper pane are those from the FROM clause

of the query that can no longer be found in the database schema.- In the lower pane, the fully qualified names of tables are listed. Also,

columns and data types that are referred to in the query but do not match the database schema are listed.

If you are synchronizing a query with a report object design (.rod) file built after release 4 of e.Report Designer Professional, the synchronization processes are able to recognize original data types. ■ The detected data type from the data dictionary appears in the New DB

Type column. ■ The data type indicated in your query appears in the old DB type

column.■ If a table has an alias, the table appears under each of its aliases.

212 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Columns in a query built for a report design using a version of e.Report Designer prior to release 4 are shown as having an unknown data type.

2 To copy and paste the nonsynchronized information, do the following:

1 Choose Copy All, or use the standard copy and paste key combinations, Ctrl+C and Ctrl+V, respectively.

2 Paste the selected rows from the active pane into another application, such as WordPad, Microsoft Word, or an e-mail application.

C h a p t e r 7 , U s i n g a q u e r y d a t a s t r e a m 213

Step 4: Analyzing tables and columns1 Choose Accept Update to update the new table definitions given in

Synchronize Query With Schema.

When you accept the table definitions, the following appear in the output window.■ Items that are referenced by the query but are not synchronized.■ Tables and columns that are not found but are still referenced in the

query.

2 You can use the output window as a checklist to keep track of what changes you are making.

Double-click each item in the output window to bring up more information to help you resolve items that are not synchronized.

When you double-click on an item in Actuate Output, you see either an message or the appropriate tool, as the following two images illustrate.

214 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Step 5: Using other tools on the query1 When you double-click information in the Actuate Output, use the various

dialogs that appear to help you change the table, column, or data type to the one you need. ■ Selecting an invalid or not found table entry opens Table Property, as

shown in the following illustration. Use Table Property to rename the table in the query to match the table name in the database.

C h a p t e r 7 , U s i n g a q u e r y d a t a s t r e a m 215

If the table is obsolete and does not need to be replaced, go to the table’s context menu and delete the table.

■ Selecting a not-found column entry opens Change Column. Use this dialog to change the reference of the column to a valid reference or remove all references of the column from the query.

If the table that contains the problem column no longer exists in the database, resolve the table problem before making changes to the column.

For more information about changing the column name, see “Changing the column name,” later in this chapter.

■ Actuate Output indicates whether the data type of a database column has changed.

e.Report Designer Professional changes the column’s data type in the report design when you choose Accept Update in Synchronize Query With Schema.

■ In Actuate Output, if you double-click a line item, a message tells you either that the column data type has changed or the table or column is no longer valid.

■ If a referenced table or column has already been removed from the stored table definition, the message indicates the table or column is no longer valid.

2 Be sure that tables and columns are corrected and are no longer highlighted in Query Editor.

3 Choose SQL➛Synchronize Query again.

If the query’s stored table definition is in sync with the data dictionary, the synchronized processes go on to verify that the SQL statement syntax is valid.

216 D e v e l o p i n g A d v a n c e d e . R e p o r t s

If that statement syntax is correct, a message appears that confirms the statement is valid. If the SQL statement is not valid, an error message appears.

SQL syntax verification is passed to the connected database server for processing. The database server’s scope of syntax checking might vary by database vendor.

Step 6: Changing the Actuate Basic type while checking the queryWhile you are working with your query, you might also want to change how a database type is mapped to an Actuate Basic data type. To change the Actuate Basic data type, do the following:

1 Select a column in the upper pane of Query Editor.

2 Choose View➛Properties.

3 In Column Property, select the appropriate Actuate Basic data type. Choose Close.

Checking the consistency of a tableTo check the consistency of a table, you can do either of the following:

■ Use the Check Table option on the context menu.

■ Use Query Editor—Table Property.

When you select the Check Table option on the context menu for tables inside Query Editor, a message appears if the table is synchronized with the database.

C h a p t e r 7 , U s i n g a q u e r y d a t a s t r e a m 217

Synchronize Query With Schema opens if the table is not synchronized with the database schema. This dialog does the following:

■ Displays the table schema differences.

■ Supports accepting or rejecting the updates given

To check the consistency of a table, you can also invoke Table Property. For information about using table properties, see “Modifying table properties in a query,” earlier in this chapter.

When you rename the table and choose Apply, the check and synchronize operations for the renamed table update the stored table definition with the latest schema definition. Note that the table name change operation is automatic, and it implies an Accept and Update operation.

After you correct the table, you can go back and fix any problems in the column in the table. To correct problems in the column, see “Changing the column name,” later in this chapter.

Changing the column nameChange Column Used in Query provides a method for changing the column name. You might need to change the table name before changing the names of any of its columns. For more information about changing the table name, see “Checking the consistency of a table,” earlier in this chapter.

How to open Change Column Used in Query

1 In Query Editor, right-click the column you want to change.

Be sure you select the column’s context menu, rather than the table’s context menu.

218 D e v e l o p i n g A d v a n c e d e . R e p o r t s

2 From the context menu, choose Change Column.

How to change the column name

1 In Change Column Used in Query, select a column name from the New Column drop-down list.

The New Column list displays all available valid names contained in the stored table definition of the data dictionary. Changing the column name fixes your query by replacing all references of the original column name with the new column name.

2 To remove all references to the original column from the query, select Remove column references.

C h a p t e r 7 , U s i n g a q u e r y d a t a s t r e a m 219

Selecting this operation removes all references of the original column from the query. Query statements are updated, as well.

3 Choose OK.

The new column name is visible on the Columns page and in the upper pane of Query Editor.

The original column is no longer a valid column in the query.

220 D e v e l o p i n g A d v a n c e d e . R e p o r t s

C h a p t e r 8 , W o r k i n g w i t h a n i n f o r m a t i o n o b j e c t 221

C h a p t e r

8Chapter 8Working with an

information objectThis chapter contains the following topics:

■ About information objects

■ Using Information Object Wizard

■ Creating an information object from an existing report object design file

■ Modifying a data row component

222 D e v e l o p i n g A d v a n c e d e . R e p o r t s

About information objectsAn information object is a predefined data source connection that includes a customizable query. You can use Actuate Query, a tool you access using Actuate Active Portal or Management Console, to customize the query in the following ways:

■ Select columns to include.

■ Specify how to group and sort data.

■ Set up search criteria.

■ Select a display format for the output:■ DHTML■ Adobe portable document format (.pdf) file■ Microsoft Excel (.xls) file■ Actuate e.Analysis

For more information about using Actuate Query, see Chapter 5, “Working with an information object for Actuate Query,” in Using e.Reports. For more information about Actuate e.Analysis, see Using e.Analysis.

An information object can include:

■ One report section with one data source

A data source for an information object can be a query data stream, a flat file, or a multiple-input filter.

■ Customizable display names for column titles

■ Parameters that control the data retrieved

■ Filters that support specifying additional selection criteria

The information object output, the data object instance (.doi) file, supports:

■ A title

■ Page-width expansion based on the number of columns the query returns

■ Display names for column headings

■ A page footer showing a page number and date on each page

C h a p t e r 8 , W o r k i n g w i t h a n i n f o r m a t i o n o b j e c t 223

Using Information Object WizardInformation Object Wizard builds the information object’s design file, runs it, and displays the data in columns in a report viewer. To sort and group data in an information object design, you can use Query Editor.

You can also create an information object using an existing report object design (.rod) file to reuse the data source connection information and query. For information about using an existing ROD to create an information object design, see “Creating an information object from an existing report object design file,” later in this chapter.

Understanding column display in an information objectThe following illustration shows an information object’s data object instance (.doi) file. If you do not specify display names to use for column titles, e.Report Designer Professional uses the data source column names as the headings for columns. If a column name is not available in the data source, the information object displays the data source variable name.

Creating an information objectThis procedure assumes there is an existing database connection to use with the information object you create. For information about building a database connection, see “How to define a database connection,” in Chapter 7, “Using a query data stream.”

How to use Information Object Wizard

1 In e.Report Designer Professional, choose File➛New.

Create New Report appears.

Data source column names

Column display names

224 D e v e l o p i n g A d v a n c e d e . R e p o r t s

2 On Create New Report, select Information Object Wizard.

Choose OK.

Information Object Wizard—Data Sources appears.

3 On Information Object Wizard—Data Source, select Choose from a list of predefined databases. Choose Next.

Information Object Wizard—Choose Database appears and displays a list of available database connections.

C h a p t e r 8 , W o r k i n g w i t h a n i n f o r m a t i o n o b j e c t 225

4 On Information Object Wizard—Choose Database, select a database. For this example, select Quikdata Sample Database. Choose Next.

Database Login appears. You do not need a user name or password to access this sample database. Requirements for another database can differ. For information about connecting to your database, contact your database administrator.

5 Choose OK.

Information Object Wizard—Select Fields appears.

6 On Information Object Wizard—Select Fields, in Table or View, select a table or view. For this example, select customers.

The list of fields in the customers table appears in Available Fields.

7 To add fields to the query, in Available Fields, complete the following tasks:■ To add a field, select the field and choose Add (>).■ To add all fields, choose Add All(>>). For this example, choose Add

All(>>).

226 D e v e l o p i n g A d v a n c e d e . R e p o r t s

The list of fields from the customers table appear in Selected Fields.

8 For this example, repeat steps 6 and 7 for the following tables:■ Items■ Orders

9 Choose Next.

Information Object Wizard—Finish appears.

Running an information object using Information Object WizardAfter you create an information object design and save it, you can run it. Running the information object design compiles the data object executable (.dox) file and generates the data object instance (.doi) file. Using the default settings, running the DOX selects all columns and displays the columns and fields in a DOI in a report viewer.

In Information Object Wizard, to view the information object design without running it, you can select Change the report design. When you choose Finish, information object design appears in e.Report Designer Professional.

C h a p t e r 8 , W o r k i n g w i t h a n i n f o r m a t i o n o b j e c t 227

How to run an information object using Information Object Wizard

To run an information object design using the Information Object Wizard, you create the design using the Information Object Wizard as shown in the preceding illustration.

1 On Information Object Wizard—Finish, in Choose one of the following, select Display the report.

Choose Finish.

Save As appears.

2 In File name, type a name for the file. For this example, type:

Quikdata_Information_Object.rod

In Save in, navigate to a location for the information object design file.

Choose Save.

Status messages appear in the status line of the application window as e.Report Designer Professional builds and runs the information object. e.Report Designer Professional writes and compiles the data object executable (.dox) file based on the choices you made in information object Wizard. The status line of the application indicates when compilation completes. When the first page generates, the data object instance (.doi) file appears in Quikdata_Information_Object—Report Viewer.

228 D e v e l o p i n g A d v a n c e d e . R e p o r t s

For information about using column display names rather than the column names from the data source, see “Modifying a data row component,” later in this chapter.

Creating an information object from an existing report object design file

To create a report design file that generates an information object from an existing report object design (.rod) file, you must set the ReportType property to InformationObject. If you change an Actuate Basic report’s ReportType property to InformationObject, the report’s format and functionality changes to support only the features of an Actuate information object.

An information object design does not support the following ROD features:

■ Multiple report sections

■ Sorting and grouping by group sections

■ Changing the order in which columns appear in the data object instance (.doi) file.

For example, if you change the ReportType of an Actuate Basic report object design (.rod) file from FormattedReport to InformationObject, the resulting information object uses the data source specified in a Connection slot of the first report section. If no data source connection component appears in the Connection slot at the report level, the information object uses the data source specified in the Connection slot of the data stream.

C h a p t e r 8 , W o r k i n g w i t h a n i n f o r m a t i o n o b j e c t 229

If the report object design (.rod) file contains additional report sections, the information about the additional report sections remains in the information object’s design (.rod) file, but the information object ignores them. If you later set the ReportType property to FormattedReport, the generated report object instance (.roi) file contains all report sections.

For more information about information objects, see “About information objects,” earlier in this chapter.

How to create an information object from an existing report object design

1 In the structure pane, select the report component.

Choose View➛Component Properties.

<Report name>—Component Editor appears.

2 On <Report name>—Component Editor, set ReportType to InformationObject, as shown in the following illustration.

Choose Close.

3 Save the information object design file.

4 Choose Report➛Build and Run.

The DOI appears in <Report name>—Report Viewer.

Modifying a data row component To modify the appearance of an information object’s data object instance (.doi) file, you can use Data Row Editor and Column Editor to edit the data row component. For example, you can set a display name for each data source column in an information object design file.

For more information about using Data Row Editor and Column Editor, see “Using Data Row Editor” and “Using Column Editor,” later in this section.

230 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Using Data Row EditorYou can use Data Row Editor to display an information object or report object design’s data row component. Data Row Editor displays the available data row columns, as shown in the following illustration.

User-created variables added to the data row component using Column Editor also appear in Data Row Editor. You can use Data Row Editor to delete a variable added using Column Editor.

From Data Row Editor, you can access Column Editor to modify or add a column in an information object or report object design (.rod) file. For information about using Column Editor, see “Using Column Editor,” later in this chapter.

How to delete a column using Data Row Editor

1 Choose View➛Data Row Editor.

Data Row Editor appears, displaying the available columns.

2 To delete a column, select the column and choose Delete.

For more information about Query Editor, see “Writing a query,” in Chapter 7, “Using a query data stream.”

Choose Close.

Using Column EditorYou can use Column Editor to modify or add a column to the data row component in an information object or report object design (.rod) file. Columns you add using Column Editor appear in Data Row Editor.

In Data Row Editor, there are two ways to access Column Editor:

C h a p t e r 8 , W o r k i n g w i t h a n i n f o r m a t i o n o b j e c t 231

■ To display empty fields in which you can provide attributes for a new column, choose Add.

■ To edit the attributes of an existing column, select the column and choose Modify.

Depending on the ReportType property setting and column type, some options are unavailable for modification. For example, if the ReportType is InformationObject, for the information object design’s customers_creditrank variable shown in the following illustration, Variable name, Table.column, Data type, and Expression are unavailable.

If the ReportType is FormattedReport, for the report object design’s customers_creditrank variable shown in the following illustration, Variable name, Table.column, and Data type are unavailable for modification.

232 D e v e l o p i n g A d v a n c e d e . R e p o r t s

In Column Editor, you can modify available options for existing variables or provide values to create a variable in the data row component. The following table describes the column attributes that can appear in Column Editor.

Column attribute Description Action

Variable name Name that appears in the data row.

Editable if user-created.

Display name An optional heading that appears instead of the column name in generated output, such as the data object instance (.doi) file or Excel.

Editable. Column Editor does not support using the following characters in Display name:\ / : ? "

Table.column name Name of the column in the data source. This value only appears if a query retrieves the value from the data source.

Not editable.

Data type Actuate Basic data type of the content in the column. Changing the data type changes the control type in the design. If a query selects the column, e.Report Designer Professional sets the data type.

Editable if user-created. Choose the appropriate type. For example, you can change Integer to Double or String. A warning appears if you choose an incorrect data type for a variable.

Format Data format. Information object only.

Editable. For example, to display a date as the day of the week, month, day, and four-digit year, select Long Date from the drop-down list.

Width Column display width in number of characters. e.Report Designer Professional uses this value and the font size to calculate the column width. Information object only.

If the columns appear too large or too small, adjust this value. If you set this attribute value too low, the column truncates characters.

Column can be used as custom filter

Option used to make a column available as a user-defined filter in Actuate Query. e.Report Designer Professional selects this attribute by default. Information object only.

If the column has a defined parameter, the column does not appear in the filter section of the Actuate Query wizard and this attribute is not available for modification in Column Editor.

C h a p t e r 8 , W o r k i n g w i t h a n i n f o r m a t i o n o b j e c t 233

For more information about Actuate Basic expressions, see Chapter 14, “Introducing Actuate Basic,” in Part 3, “Programming with Actuate Basic,” in Programming e.Reports.

For more information about e.Analysis, see “Analyzing report data with e.Analysis,” in Chapter 12, “Working with frames and controls.”

How to modify a column using Column Editor

1 Choose View➛Data Row Editor.

Data Row Editor appears, displaying the available columns.

2 To modify a column’s properties:

1 Select a column. Choose Modify.

Column Editor appears.

2 Modify the available fields and options.

Choose OK.

The modified variable appears in Data Row Editor.

3 Choose Close.

Expression Field used to add or modify an expression for a user-defined variable. Information object only.

For this attribute, an information object supports an expression that applies to a row. For example, an information object supports the following Actuate Basic expression for a user-created Integer-type variable:[items_quantity] * 2The Actuate Basic expression can refer to parameters and global variables. This expression is distinct from any SQL expression that Query Editor creates. An information object does not support an aggregate expression, such as:Sum( [items_quantity] )

e.Analysis option Actuate e.Analysis AnalysisType property. Information object only.

Select Automatic, Dimension, or Measure.

Column attribute Description Action

234 D e v e l o p i n g A d v a n c e d e . R e p o r t s

How to add a column to a data row component using Column Editor

1 Choose View➛Data Row Editor.

Data Row Editor appears.

2 To add a column:

1 Choose Add.

Column Editor appears.

2 Provide values for the available fields and select options.

Choose OK.

The variable appears in Data Row Editor.

3 Choose Close.

Modifying a font in an information objectIn an information object, you can modify the attributes of the font properties that appear in the following table:

Font property Text affected

DataFont Data retrieved from the data source

LabelFont Display names for columns

PageDecorationFont Page number and date in the footer

TitleFont Information object’s title

C h a p t e r 8 , W o r k i n g w i t h a n i n f o r m a t i o n o b j e c t 235

In e.Report Designer Professional, you can change the default data and label fonts on Options—Fonts. You can also change the fonts a particular information object uses. For information about changing the default fonts, see “Setting the default font for labels, data, and source editor,” in Chapter 5, “Customizing the design environment.” For more information about fonts, see AcFont data type in Actuate Foundation Class Reference.

How to change the data or label font an information object uses

1 In the structure pane, double-click the information object’s report component.

<Information object component name>—Component Editor—Properties appears.

2 In the Auto Contents group, to set font attribute values, expand a group:■ DataFont■ LabelFont■ PageDecorationFont■ TitleFont

3 Set the font attribute values.

Choose Close.

236 D e v e l o p i n g A d v a n c e d e . R e p o r t s

C h a p t e r 9 , U s i n g Te x t u a l Q u e r y E d i t o r 237

C h a p t e r

9Chapter 9Using Textual Query

EditorThis chapter contains the following topics:

■ About Textual Query Editor

■ Writing a textual query

■ Choosing the textual query data source

■ Opening Textual Query Editor

■ Writing the SQL query

■ Preparing and describing the SQL query

■ Accepting the SQL query

■ Editing the SQL query

■ Editing column properties

■ Using static parameters with a textual query

■ Using ad hoc parameters with a textual query

■ Sorting data with a textual query

■ Converting graphical queries into textual queries

238 D e v e l o p i n g A d v a n c e d e . R e p o r t s

About Textual Query EditorTextual Query Editor is a textual tool for writing SQL SELECT queries. Textual Query Editor provides a way to define SQL SELECT statements without overriding AFC methods. Actuate e.Report Designer Professional creates the data row and binds columns.

Textual Query Editor does not critically analyze your SQL SELECT statement. Use Textual Query Editor if you have a detailed understanding of the SQL language and want to write SELECT queries directly in SQL.

Textual Query Editor processes SQL SELECT queries exactly as you enter them. You prepare and describe your queries by choosing Describe Query. Textual Query data source processes one result set returned from the query. Textual Query data source does not support multiple result sets.

You can convert structured queries designed in the graphical Query Editor into textual queries, but you cannot convert textual queries into structured queries. The textual query does not contain enough information to support its conversion to the data structures of the graphical Query Editor.

For information about converting a graphical query into a textual query, see “How to convert graphical queries into textual queries” in Chapter 7, “Using a query data stream.”

Writing a textual queryTo write a query using Textual Query Editor, you perform the following procedures in order. For each procedure in this list, a corresponding section with detailed, step-by-step instructions follows.

Required procedures■ Choosing the textual query data source.

■ Opening Textual Query Editor.

■ Writing the SQL query.

■ Preparing and describing the SQL query.

■ Accepting the SQL query.

C h a p t e r 9 , U s i n g Te x t u a l Q u e r y E d i t o r 239

Optional procedures■ Editing the SQL query.

■ Editing column properties.

■ Using static parameters with a textual query.

■ Using ad hoc parameters with a textual query.

■ Sorting data with a textual query.

Choosing the textual query data sourceTo use Textual Query Editor, choose the textual query data source for your report design.

How to choose the textual query data source

1 Open your report, or create a new one. The default data source setting is DataStream—SqlQuerySource.

2 Delete the default data source by selecting it in the structure pane and choosing Edit➛Delete from the menu bar.

3 Drag a data source component from the Data palette and drop it in the DataStream slot.

240 D e v e l o p i n g A d v a n c e d e . R e p o r t s

4 In Select Component, select SQL Query Data Source (Textual). Choose OK.

The textual query datastream component appears in your report design.

Opening Textual Query EditorAfter you place a textual query data source in your report, you can open Textual Query Editor by choosing View➛Data Source.

C h a p t e r 9 , U s i n g Te x t u a l Q u e r y E d i t o r 241

Writing the SQL queryTo choose the data to include in the report, you write a query. A query is a SQL SELECT statement that specifies the data to retrieve from a database.

If you plan to use stored procedures provided by the database, use Stored Procedure Data Source Builder. For more information about working with stored procedures, see Chapter 10, “Using and customizing a stored procedure,” in Programming e.Reports.

Enter the SQL SELECT statement in the upper pane of Textual Query Editor. Depending upon your database login, you might have to fully qualify the table name with the name of the database. You do not have to specify the database name in subsequent clauses of the query, such as the WHERE clause.

For example, to select all columns from the customers table of the Actest database, you can specify the fully qualified name Actest.customers in the SELECT statement. To retrieve data for only those customers in Massachusetts, specify State in the WHERE clause of the SELECT statement as shown in the following illustration.

242 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Preparing and describing the SQL queryChoose Describe Query to prepare and describe the SQL SELECT statement. If e.Report Designer Professional is unable to connect to the database, the Database Login appears.

In Database Login, type the required information, and choose OK. Some of the fields in Database Login might already be filled in, depending on whether these values were set in the connection component. For more information about defining connection properties, see “Defining a database connection” in Chapter 7, “Using a query data stream.”

Describe Query sends the SQL SELECT statement to the connected database server to describe the query’s result columns. It also updates the relevant information in the Columns, Static Parameters, and Adhoc Conditions pages of Textual Query Editor.

Actuate e.Report Designer Professional sends the SQL SELECT statement to your connected database server. Database connections for Sybase and Microsoft SQL Server execute the query to prepare and describe the result columns, which affects the response time. All database connections return the result columns information to Textual Query Editor.

C h a p t e r 9 , U s i n g Te x t u a l Q u e r y E d i t o r 243

If you use the select all character, an asterisk (*), in your SQL SELECT query, Actuate e.Report Designer Professional retrieves information for all columns in the table.

The following illustration shows Textual Query Editor with the result column information filled in.

When you choose Describe Query, Textual Query Editor does not preserve table information. You must add the table.column reference name for each column. For example, after choosing Describe Query you must add the reference name customers.custID for the column custID.

Accepting the SQL query1 Check the properties on all of Textual Query Editor’s pages to verify that

they are correct.

2 Choose OK to accept the query and its column and parameter properties.

Editing the SQL queryActuate e.Report Designer Professional does not automatically format the text of the SQL SELECT statement. The main Edit menu is unavailable from Textual Query Editor. Standard text editing functionality such as copy and paste is still available, however, in the upper pane of Textual Query Editor. For example, use Ctrl+C to copy text, Ctrl+V to paste, and Ctrl+X to cut. Use the delete key on your keyboard to delete text. You can also access these commands and others on the context menu.

244 D e v e l o p i n g A d v a n c e d e . R e p o r t s

You can also access these commands and others on the context menu. Right-click in the upper pane of Textual Query Editor to display the context menu.

Choose Undo to undo your editing of the SQL SELECT statement. Undo affects only the query that you type. It does not apply to any other Textual Query Editor function, such as Describe Query or Clear Query.

Use Clear Query to erase the entire query and its corresponding properties in the lower pane.

For information about the Describe Query button, see “Preparing and describing the SQL query,” earlier in this chapter.

Choose OK to accept the query when you finish editing.

C h a p t e r 9 , U s i n g Te x t u a l Q u e r y E d i t o r 245

Editing column propertiesTextual Query Editor’s Columns page supports editing the result columns’ properties. The information you enter provides data for setting up the corresponding data row variables. The following table describes the result column properties.

Columns properties

Description

Column Name Read-only text field. This property is the name of a selected column as reported by the Describe Query operation. e.Report Designer Professional assigns a name if Describe Query does not report a column name: column<selectOrderNumber>. For example, if the column is the second column selected, the assigned name is column2. If column names are duplicates, e.Report Designer Professional adds a unique number to the column name. For example, Address, Address_1, Address_2.

Database Type Read-only text field. This property is the column’s native database data type as reported by the Describe Query operation. For example, Number, Varchar, or Char.

Actuate Type Drop-down list. This property is the Actuate Basic data type to which e.Report Designer Professional maps the column’s database data type. Examples are Double, String, and Integer.

Display Length Text field. This property is the display length of the fetched result column’s data. e.Report Designer Professional uses the display length to determine the default size of the corresponding data control. e.Report Designer Professional displays the default display length, if any.

Reference Names Text field. This property is a comma-separated field that specifies the reference names of the corresponding data row variable. The first reference name you specify is the primary name. e.Report Designer Professional uses the primary name to display the name of a data row variable elsewhere, for example, in Field List. For a new query, the default reference name is the same as the column name.

246 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Using static parameters with a textual queryTextual Query Editor’s Static Parameters page supports editing the properties of a query’s static input parameters. Indicate static parameters in your SQL SELECT statement using the single colon syntax, as follows:

column <comparison op> :static_param

In this case, column is the name of the column; <comparison op> is a comparison operator such as =, >, or <; colon (:) indicates the static parameter. Static_param is the name of the static parameter. For example, the following statement specifies a static parameter called MyCity:

select city from actest.offices WHERE city = :MyCity

The static parameter can be:

■ A local parameter that you have defined.

■ An inherited parameter that you or e.Report Designer Professional has defined.

■ A global parameter that you have defined.

The parameter’s data type must be compatible with the database column’s data type.

If the parameter is not defined, e.Report Designer Professional defines a local parameter. If you later define a parameter with the same name as the local parameter defined by e.Report Designer Professional, the local parameter defined by e.Report Designer Professional is removed.

When you choose Describe Query to prepare and describe the query, Actuate e.Report Designer Professional provides information about the static parameter on the Static Parameters page. When you accept the query and run the report, the static parameter appears in Requester or the request page.

The following illustration shows a SQL SELECT query that specifies a static parameter and the resulting Static Parameters page.

C h a p t e r 9 , U s i n g Te x t u a l Q u e r y E d i t o r 247

The following table describes the static parameter properties.

How to modify static parameters with a textual query

1 In Static Parameters, choose Builder.

Static Parameters properties

Description

Parameter Name Read-only text field. The parameter name is defined in the SQL SELECT statement. It is used to name the corresponding parameter variable. Parameter names are not case-sensitive.

Actuate Type Drop-down list. This property is the Actuate Basic type of the parameter variable. The default value Actuate type is String. If the drop-down list is not available, choose Builder and specify a Type in Parameter Properties—General. The parameter’s data type must be compatible with the database column’s data type.

248 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Parameter Properties—General appears.

2 Use Parameter Properties—General to specify a display name, default value, and whether the parameter is required or hidden. Requester reflects these attributes when you run the report.

For more information about using Parameter Properties, see “Modifying a parameter for the request page” in Chapter 18, “Designing a report parameter.”

Using ad hoc parameters with a textual queryWhen a user runs a report that contains ad hoc parameters, the request page prompts the user for input. If the user enters a value for the ad hoc parameter, the request page adds the ad hoc parameter’s corresponding conditional expression to the query’s WHERE clause.

Textual Query Editor differs from the structural Query Editor in that it does not critically analyze your SQL SELECT statement. Textual Query Editor cannot by itself determine where to insert the conditional expression for ad hoc parameters in a SQL SELECT statement. Textual Query Editor provides a syntax to mark where in the SQL SELECT statement to insert an ad hoc parameter’s conditional expression.

C h a p t e r 9 , U s i n g Te x t u a l Q u e r y E d i t o r 249

Use Textual Query Editor’s Adhoc Conditions page to specify the conditional expression for each ad hoc parameter in your query.

Examples of the required syntax follow:

<space>:?name<space>

or

<space>:?name<end-of-statement>

How to define an ad hoc parameter using Textual Query Editor

1 Type the query into Textual Query Editor’s upper pane. Use the following syntax to specify ad hoc parameters and to mark where to insert the corresponding conditional expression:

:?adhoc_param

Here, the characters :? indicate an ad hoc parameter, and adhoc_param is the name of the ad hoc parameter. For example, the following SQL query specifies the ad hoc parameter deptNum:

SELECT * from actest.offices WHERE :?deptNum

Ad hoc conditions defined in textual SQL SELECT statements must have a leading space. Ad hoc parameter names must be followed by a space separator, unless the parameter name is the last word in the SQL SELECT statement.

2 Choose Describe Query to prepare and describe the query.

3 Choose Adhoc Conditions.

e.Report Designer Professional supplies the default value information about your query’s ad hoc parameters.

4 If necessary, edit the ad hoc parameter’s properties.

When you accept the query and run the report, Requester prompts you for a QBE expression as input for the ad hoc parameters. For more information about Query by Example expressions, see “Using Query by Example (QBE) syntax” in Chapter 7, “Using a query data stream,” and Chapter 4, “Running a report,” in Using e.Reports.

250 D e v e l o p i n g A d v a n c e d e . R e p o r t s

The following illustration shows a SQL SELECT query that specifies an ad hoc parameter and the resulting Adhoc Conditions page.

The following table describes the ad hoc parameter properties.

Adhoc Conditions properties

Description

Parameter Name Read only text. This property is the ad hoc parameter’s name that you specify in your query. It is used as the corresponding parameter’s variable name. Parameter name is not case-sensitive. An ad hoc parameter cannot have the same name as a static parameter.

Column Name Text field. This property is the column name to use in the ad hoc conditional expression.

Expression Type Drop-down list. This property is the column’s Actuate Basic type. It is used to generate the appropriate syntax for the conditional expression.

C h a p t e r 9 , U s i n g Te x t u a l Q u e r y E d i t o r 251

How to modify ad hoc parameters with a textual query

1 In Adhoc Conditions, choose Builder.

Parameter Properties—General appears.

2 In Parameter Properties—General, provide the parameter’s display name, default value, and whether the parameter is required or hidden. Requester reflects these attributes when you run the report.

For more information about using Parameter Properties, see “Modifying a parameter for the request page” in Chapter 18, “Designing a report parameter.”

Sorting data with a textual queryUse the sort drop-down list to specify how to sort data retrieved by the textual query data source.

For more information about sorting data in a report design, see “Sorting data inside groups” in Chapter 11, “Working with sections.”

252 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Textual Query Editor offers three sort options:

■ By Query. Add a dynamic Order By clause to the query as needed at run time. This is the default sort option setting.

■ Presorted. The SQL query already specifies the appropriate sorting columns and order in its Order By clause.

■ By Filter. Use e.Report Designer Professional’s sort filter utility to sort the results data.

Converting graphical queries into textual queries1 In e.Report Designer Professional, choose Data Source Editor.

2 In Query Editor, choose SQL➛Edit SQL.

A warning reminds you that you cannot convert the query back to a graphical format.

3 Choose Yes.

C h a p t e r 9 , U s i n g Te x t u a l Q u e r y E d i t o r 253

Textual Query Editor opens and displays the query.

254 D e v e l o p i n g A d v a n c e d e . R e p o r t s

C h a p t e r 1 0 , D e s i g n i n g a r e p o r t t h a t u s e s a n S A P B W d a t a s t r e a m 255

C h a p t e r

10Chapter 10Designing a report that

uses an SAP BW datastream

This chapter contains the following topics:

■ About SAP BW data streams

■ Configuring the report development environment

■ Creating a report design that uses an SAP BW BEx Query data stream

■ Creating an MDX query

■ Creating a report design that uses an SAP BW ODS data stream

■ Changing the Java Virtual Machine’s maximum heap size

256 D e v e l o p i n g A d v a n c e d e . R e p o r t s

About SAP BW data streamsUsing e.Report Designer Professional, you can design reports that use SAP BW data streams. You can retrieve and display data from:

■ SAP BW BEx queries

■ SAP BW Operational Data Stores

For more information about data streams, see Chapter 5, “Understanding document generation,” in Programming e.Reports.

Configuring the report development environmentBefore you can create a report design that uses an SAP BW data stream, you must install the SAP Java Connector libraries and configure your report development environment.

Installing the SAP Java Connector librariesYou must install version 6.20 of the SAP Java Connector libraries for BW 3.0. You can download the SAP Java Connector libraries from the SAP Service Marketplace at the following URL:

http://service.sap.com/connectors

For library download information, see Note 19466 at the following URL:

http://service.sap.com/notes

To download a patch over the web, navigate to the following URL and choose Download Kernel/Frontend Patches:

http://service.sap.com/ocs

How to configure the report development environment

1 Install the SAP GUI client with the following options:■ BW add-ons■ SAP GUI 6.20

2 Using SAPlogon, create a BW login configuration with the following properties:■ Description, for example CB3 BW

The description should consist of more than three characters.

C h a p t e r 1 0 , D e s i g n i n g a r e p o r t t h a t u s e s a n S A P B W d a t a s t r e a m 257

■ Application server, for example 012.34.56.78■ SAP router string, for example /H/01.23.45.67/H/890.123.456.789/H/■ System number, for example 03

3 Install Microsoft Data Access Components 2.6.

4 Place the following SAP Java Connector libraries in \Program Files\Actuate7\MyClasses:■ sapjco.jar

■ librfc32.dll■ sapjcorfc.dll

For more information about installing the SAP Java Connector libraries, see “Installing the SAP Java Connector libraries,” earlier in this chapter.

Creating a report design that uses an SAP BW BEx Query data stream

Use the Report Wizard to create a report design that uses an SAP BW BEx Query data stream.

How to create a report design that uses an SAP BW BEx Query data stream

1 Choose File➛New.

Create New Report appears.

2 Select Quick Report Wizard. Choose OK.

Report Wizard—Data Sources appears.

258 D e v e l o p i n g A d v a n c e d e . R e p o r t s

3 Select Build a new database connection. Choose Next.

Report Wizard—Build New Database Connection appears.

4 To specify your database connection information:■ In Type of database, select SAP Connection.■ In Connection information, type the property values for the BW login

configuration you created using SAPlogon.■ Choose Next.

For more information about creating a BW login configuration, see “Configuring the report development environment,” earlier in this chapter.

C h a p t e r 1 0 , D e s i g n i n g a r e p o r t t h a t u s e s a n S A P B W d a t a s t r e a m 259

Report Wizard—Select Data Stream appears.

5 Select SAP BW BEx Query. Choose Next.

SAP Logon appears.

6 Choose OK.

260 D e v e l o p i n g A d v a n c e d e . R e p o r t s

SAPQueryCubeSource—SAP BW BEx Data Source Builder appears.

7 To create an MDX query:■ In InfoProvider, select an InfoProvider.■ In BEx Query, select a BEx query.■ Create an MDX query.■ Choose OK.

For more information about SAP BW BEx Data Source Builder and creating an MDX query, see “Creating an MDX query,” later in this chapter.

C h a p t e r 1 0 , D e s i g n i n g a r e p o r t t h a t u s e s a n S A P B W d a t a s t r e a m 261

8 If a prompt appears, choose No.

Report Wizard—Choose Layout Style appears.

9 To specify the report layout:■ In Available Layout Styles, select the report layout.■ In Paper Size, select the appropriate paper size.■ In Orientation, select Portrait or Landscape.■ Choose Next.

Report Wizard—Finish appears.

10 To complete the report design:■ In Enter a title for your report, type a report title.■ Select Display the report or Change the report design.

262 D e v e l o p i n g A d v a n c e d e . R e p o r t s

■ Choose Finish.

If you select Change the report design, the report design appears in Design Editor after you choose Finish.

When the report design appears in Design Editor, you can:■ Modify the MDX query.

For more information about MDX queries, see “Creating an MDX query,” later in this chapter.

■ Drag database fields from Field List and drop them into frames in the report design.

C h a p t e r 1 0 , D e s i g n i n g a r e p o r t t h a t u s e s a n S A P B W d a t a s t r e a m 263

For more information about Field List, see “Placing controls in a report design” in Chapter 12, “Working with frames and controls.”

■ If you chose Crosstab in Available Layout Styles, modify the crosstab control.

For more information about the crosstab control, see Chapter 17, “Presenting data in a crosstab report.”

Creating an MDX queryUse SAP BW BEx Data Source Builder to create a Multidimensional Expressions (MDX) query. MDX is the language component of Microsoft’s Object Linking and Embedding Database for Online Analytical Processing (OLE DB for OLAP) specification. OLE DB for OLAP specifies a set of COM interfaces through which a program can gain access to the services of an OLAP data provider. The OLE DB for OLAP specification includes data structures and protocols for issuing queries to and exchanging data with a data provider. For more information about MDX, see MDX Solutions by George Spofford.

264 D e v e l o p i n g A d v a n c e d e . R e p o r t s

SAP BW BEx Data Source Builder displays the BEx query’s metadata in the upper pane and the MDX query in the lower pane.

To create an MDX query, you must specify the query’s axes. If the BEx query you select uses an SAP variable that requires a value, you must provide a value for the variable. You can also specify:

■ An ORDER function

■ A FILTER function

■ Slices

How to display SAP BW BEx Data Source Builder

1 Open a report design that uses an SAP BW BEx Query data stream.

2 In the structure pane, select the appropriate SAP BW BEx Query data stream component.

3 Choose View➛Data Source.

Metadata

MDXquery

C h a p t e r 1 0 , D e s i g n i n g a r e p o r t t h a t u s e s a n S A P B W d a t a s t r e a m 265

How to refresh the display of metadata in SAP BW BEx Data Source Builder

If the BEx query changes within the SAP BW, refresh the display of metadata by choosing Refresh Metadata.

How to display technical names in SAP BW BEx Data Source Builder

By default, SAP BW BEx Data Source Builder displays business names for the BEx query’s metadata. To toggle the display of technical names, choose Toggle Unique Names.

About DimensionsIn Dimensions, SAP BW BEx Data Source Builder displays the following elements:

■ Dimensions

■ Hierarchies

■ Levels

■ Parent nodes

■ Members

■ Attributes

Dimension

Hierarchy

Level

Parent node

Member

Attribute

266 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Specifying an MDX query’s axesSAP BW BEx Data Source Builder—Axes specifies an MDX query’s axes.

When you use SAP BW BEx Data Source Builder—Axes, you must observe the following rules:

■ You can only add one dimension to an axis.

■ The first axis in the list should include key figures (measures).

If an axis other than the first axis includes key figures, all key figures should be of the same data type. If all key figures are not of the same data type, the data type of the first data row must be compatible with the data types of subsequent data rows. For example, if the data type of the first data row is Double, the data type of subsequent data rows can be Integer.

■ You can add up to a maximum of 10 axes.

Performance decreases as the number of axes increases.

Using the context menus in Key Figures and Dimensions, you can create MDX fragments that use:

■ The .MEMBERS operator, for example:

SELECT{[Measures].MEMBERS} ON AXIS(0),{[ODB_BRANC].MEMBERS} ON AXIS(1),{[ODB_REGIO].MEMBERS} ON AXIS(2)

■ The DESCENDANTS( ) function, for example:

SELECT{[Measures].MEMBERS} ON AXIS(0),{DESCENDANTS([0BUS_AREA].[All],[0BUS_AREA].[LEVEL01],SELF_AND_AFTER)} ON AXIS(1)

■ Individual items, for example:

SELECT{[Measures].MEMBERS} ON AXIS(0),{[ODB_BRANC].MEMBERS} ON AXIS(1),{[ODB_CNTRY].[USA], [ODB_CNTRY].[CAN]} ON AXIS(2)

C h a p t e r 1 0 , D e s i g n i n g a r e p o r t t h a t u s e s a n S A P B W d a t a s t r e a m 267

How to filter empty members

1 In SAP BW BEx Data Source Builder, choose Axes.

SAP BW BEx Data Source Builder—Axes appears.

2 To remove tuples that correspond to empty slices of data in the result set, choose Filter Empty Members for the appropriate axis.

In the following illustration, branches that do not have any associated regions and key figures are removed from the result set.

Choosing Filter Empty Members inserts the keywords NON EMPTY before the axis specification in the MDX query, for example:

SELECT{[Measures].MEMBERS} ON AXIS(0),NON EMPTY {[ODB_BRANC].MEMBERS} ON AXIS(1),{[ODB_REGIO].MEMBERS} ON AXIS(2)

Report layout examplesIn Report Wizard—Choose Layout Style, you must choose one of the following layout styles for your report:

■ Blocked

■ Columnar

■ Crosstab

■ Tabular

The following examples describe how to specify the MDX query’s axes for:

■ A blocked, columnar, or tabular report

■ A crosstab report with one column

■ A crosstab report with more than one column

■ A crosstab report with column grouping

268 D e v e l o p i n g A d v a n c e d e . R e p o r t s

These examples all use the same BEx query. The following illustrations show the BEx query’s Key Figures and Dimensions.

Example: Creating a blocked, columnar, or tabular reportThe following illustration shows the first page of a columnar report.

C h a p t e r 1 0 , D e s i g n i n g a r e p o r t t h a t u s e s a n S A P B W d a t a s t r e a m 269

How to specify the axes for a blocked, columnar, or tabular report

1 In Key Figures, right-click Revenue. Choose Column➛Item.

2 In Dimensions, right-click Products➛PRODPGRP. Choose Row➛Members.

The following MDX fragment specifies the query’s axes:

SELECT{[Measures].[CKGZE7ZS7UHEQ58R8LOS56L85]} ON AXIS(0),{[ODB_PROD PRODPGRP].MEMBERS} ON AXIS(1)

Example: Creating a crosstab report with one columnThe following illustration shows a crosstab report with one column.

How to specify the axes for a crosstab report with one column

1 In Key Figures, right-click Revenue. Choose Column➛Item.

2 In Dimensions, right-click Products➛PRODPGRP. Choose Row➛Members.

The following MDX fragment specifies the query’s axes:

SELECT{[Measures].[CKGZE7ZS7UHEQ58R8LOS56L85]} ON AXIS(0),{[ODB_PROD PRODPGRP].MEMBERS} ON AXIS(1)

270 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Example: Creating a crosstab report with more than one columnThe following illustration shows a crosstab report with more than one column.

How to specify the axes for a crosstab report with more than one column

1 In Key Figures, right-click Revenue. Choose Column➛Item.

2 In Dimensions:

1 Right-click Products➛PRODPGRP. Choose Row➛Members.

2 Right-click Quarter➛Quarter➛Quarter Level 01. Choose Column➛Members.

The following MDX fragment specifies the query’s axes:

SELECT{[Measures].[CKGZE7ZS7UHEQ58R8LOS56L85]} ON AXIS(0),{[0CALQUART1].[LEVEL01].MEMBERS} ON AXIS(1),{[ODB_PROD PRODPGRP].MEMBERS} ON AXIS(2)

Example: Creating a crosstab report with column groupingThe following illustration shows a crosstab report with column grouping.

C h a p t e r 1 0 , D e s i g n i n g a r e p o r t t h a t u s e s a n S A P B W d a t a s t r e a m 271

How to specify the axes for a crosstab report with column grouping

1 In Key Figures, right-click Revenue. Choose Column➛Item.

2 In Dimensions:

1 Right-click Products➛PRODPGRP. Choose Row➛Members.

2 Right-click Quarter➛Quarter➛Quarter Level 01. Choose Column➛Members.

3 Right-click Scenarios➛Scenarios➛Scenarios Level 01. Choose Column➛Members.

The following MDX fragment specifies the query’s axes:

SELECT{[Measures].[CKGZE7ZS7UHEQ58R8LOS56L85]} ON AXIS(0),{[0CALQUART1].[LEVEL01].MEMBERS} ON AXIS(1),{[ODB_VALTP].[LEVEL01].MEMBERS} ON AXIS(2),{[ODB_PROD PRODPGRP].MEMBERS} ON AXIS(3)

Specifying an ORDER functionSAP BW BEx Data Source Builder—Order specifies an MDX query’s ORDER function.

272 D e v e l o p i n g A d v a n c e d e . R e p o r t s

An ORDER function is applied to an individual axis. When you use SAP BW BEx Data Source Builder—Order, you must observe the following rules:

■ Deleting an axis from the query deletes from the query any order entries applied to that axis.

■ If you add multiple order entries for the same axis, these order entries must have the same sort type, for example ascending.

■ You can use the combo box in the On column to move an order expression from one axis to another axis.

For example, you can create the following MDX fragment:

ORDER({[ODB_REGIO].MEMBERS}, ([Measures].[CKGZE7ZS7UHEQ58R8LOS56L85]), ASC) ON AXIS(2)

How to specify an MDX query’s ORDER function

1 In SAP BW BEx Data Source Builder, choose Order.

SAP BW BEx Data Source Builder—Order appears.

2 Right-click one of the following elements. Choose Order.■ In Key Figures, an individual measure.■ In Dimensions, one of the following elements:

- A parent node. Selecting this element appends .CHILDREN to the order entry.

- A member.

This element is the criterion by which the members of the set are ordered.

Choose Axis for Order Clause appears.

3 Select the axis to which you want to apply the order.

Choose OK.

4 In Sort By, choose one of the following options:■ ASC

ASC means ascending with hierarchy preserved.

C h a p t e r 1 0 , D e s i g n i n g a r e p o r t t h a t u s e s a n S A P B W d a t a s t r e a m 273

■ BASC

BASC means ascending with hierarchy broken.■ DESC

DESC means descending with hierarchy preserved.■ BDESC

BDESC means descending with hierarchy broken.

For more information about sorting, see “Sorting example,” later in this chapter.

5 Repeat steps 2 through 4 as necessary to specify the query’s ORDER function.

Sorting exampleWhen you sort data, you can preserve the data’s hierarchy or break the data’s hierarchy. For example, the following data is sorted in ascending order with hierarchy preserved:

City Revenue------ -------------California

San Jose $200,000San Francisco $300,000Los Angeles $400,000

New YorkSyracuse $100,000Buffalo $200,000Albany $700,000

The following data is sorted in ascending order with hierarchy broken:

City Revenue------ -------------Syracuse, New York $100,000Buffalo, New York $200,000San Jose, California $200,000San Francisco, California $300,000Los Angeles, California $400,000Albany, New York $700,000

274 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Specifying a FILTER functionSAP BW BEx Data Source Builder—Filters specifies an MDX query’s FILTER function.

A filter is an expression that you apply to an axis to restrict the members of the set the MDX query returns. When you use SAP BW BEx Data Source Builder—Filters, you must observe the following rules:

■ Deleting an axis from the query deletes from the query any filter entries applied to that axis.

■ You must include a measure in a filter expression. You can also include an element from anywhere in the dimension structure.

■ You can use the combo box in the On column to move a filter expression from one axis to another axis.

For example, you can create the following MDX fragment:

FILTER({[ODB_BRANC].MEMBERS}, ([ODB_PROD].[MO19199601],[Measures].[CKGZE7ZS7UHEQ58R8LOS56L85]) > 100.00) ON AXIS(1)

The following MDX fragment combines a FILTER function and an ORDER function:

ORDER(FILTER({[ODB_BRANC].MEMBERS},([Measures].[CKGZE7ZS7UHEQ58R8LOS56L85]) > 10000)),([ODB_PGRP].MEMBERS,[Measures].[CKGZE7ZS7UHEQ58R8LOS56L85]), ASC) ON AXIS(2)

How to include a measure in a filter expression

1 In SAP BW BEx Data Source Builder, choose Filters.

SAP BW BEx Data Source Builder—Filters appears.

2 In Key Figures, right-click the measure and choose Filter➛Condition.

Choose Axis to Filter on appears.

3 Select the axis to which you want to apply the filter.

C h a p t e r 1 0 , D e s i g n i n g a r e p o r t t h a t u s e s a n S A P B W d a t a s t r e a m 275

Choose OK.

4 In SAP BW BEx Data Source Builder—Filters, type a value in Value.

The query compares the measure you chose in step 2 to this value to determine which members to return.

5 In Operator, type one of the following operators:■ =■ >■ <■ >=■ <=■ <>

The query uses this operator to compare the measure you chose in step 2 to the value you typed in step 4.

6 To make the value a report parameter, select Parameter.

The value in Value is the default value for the parameter. A valid default value is required. For more information about report parameters, see Chapter 18, “Designing a report parameter.”

How to include a nonmeasure element in a filter expression

1 Include a measure in the filter expression.

For more information about including a measure in a filter expression, see “How to include a measure in a filter expression,” earlier in this chapter.

2 In SAP BW BEx Data Source Builder, choose Filters.

SAP BW BEx Data Source Builder—Filters appears.

3 In Dimensions, right-click one of the following elements. Choose Filter➛Selection.■ A parent node.

Selecting this element appends .CHILDREN to the filter entry.■ A member.

276 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Choose Axis to Filter on appears.

4 Select the axis to which you want to apply the filter.

Choose OK.

5 In SAP BW BEx Data Source Builder—Filters, type a member in Value.

Enclose the member in square brackets, for example [MO19199601].

The query compares the element you chose in step 3 to this member to determine which members to return.

6 To make the value a report parameter, select Parameter.

The value in Value is the default value for the parameter. A valid default value is required. For more information about report parameters, see Chapter 18, “Designing a report parameter.”

Specifying slicesSAP BW BEx Data Source Builder—Slices specifies an MDX query’s slices.

Unlike an ORDER function or a FILTER function, a slice is applied to the query’s result set rather than to an individual axis. In MDX, you must structure a slice as a tuple. In SAP BW BEx Data Source Builder—Slices, you must group the slice elements so that Actuate can place them in the correct tuple.

When you use SAP BW BEx Data Source Builder—Slices, you must observe the following rules:

C h a p t e r 1 0 , D e s i g n i n g a r e p o r t t h a t u s e s a n S A P B W d a t a s t r e a m 277

■ Each slice must have the same number of elements.

■ The combined slice elements must form a tuple.

■ You can use only an individual measure, a parent node, or a member to create a slice element.

For example, you can create the following MDX fragment:

WHERE {([ODB_VALTP].[A])}

How to specify slices

1 In SAP BW BEx Data Source Builder, choose Slices.

SAP BW BEx Data Source Builder—Slices appears.

2 Right-click one of the following elements. Choose Slice.■ In Key Figures, an individual measure■ In Dimensions, a parent node or a member

3 To make the value a report parameter, select Parameter.

The value in Value is the default value for the parameter. A valid default value is required. If the value is a member, enclose it in square brackets. For more information about report parameters, see Chapter 18, “Designing a report parameter.”

4 To add another slice:

1 Repeat step 2.

2 In Add new slice to Group, select the slice to which you want to add an element, or select New Slice Grouping to create a new slice. Choose OK.

5 Repeat step 4 as necessary.

Specifying values for SAP variablesSAP BW BEx Data Source Builder—SAP Variables specifies the values for SAP variables. SAP variables are an extension of the MDX standard.

278 D e v e l o p i n g A d v a n c e d e . R e p o r t s

For example, assume you have a data warehouse that contains sales data. If the data is too large for a single cube, you can divide the warehouse into several cubes based on year, for example 1997, 1998, and so on. If you want to execute the same MDX query for different years, however, you must modify the query for each year. If you use an SAP variable called Year, the cubes are logically consolidated into one cube, for example SalesCube. You can then execute the same MDX query on SalesCube using different values of Year.

For example, you can use SAP BW BEx Data Source Builder—SAP Variables to create the following MDX fragment:

[0P_CALYE] INCLUDING [0CALYEAR].[1994][ODBCONT] INCLUDING [ODB_CONT].[EUR]

How to specify a value for an SAP variable

1 In SAP BW BEx Data Source Builder, choose SAP Variables.

SAP BW BEx Data Source Builder—SAP Variables appears.

2 If Mandatory is selected for the SAP variable, type a value for the variable in Value.

If the value is a member, enclose it in square brackets.■ If the variable’s type is Single, type a single value, for example [1998].■ If the variable’s type is Multivalue, type a range.

Separate the lower and upper bounds of the range with a colon (:), for example [1996]:[1998].

■ If the variable’s type is Complex, type a set of values and ranges.

Separate the values and ranges with semi-colons (;), for example [1992]; [1995]:[1997].

3 To make the value a report parameter, select Parameter.

For a nonmandatory variable, if you type a value in Value, this value is the default value for the parameter. If you do not type a value in Value and the report user does not provide a value when he runs the report, the SAP variable does not appear in the MDX query.

C h a p t e r 1 0 , D e s i g n i n g a r e p o r t t h a t u s e s a n S A P B W d a t a s t r e a m 279

For a mandatory variable, you must type a value in Value. This value is the default value for the parameter.

If the report user provides a value other than the default value when he runs the report, the number of columns returned in the query’s result set may differ from the number of columns that the BindDataRow( ) method binds. For example, if the report user provides a member value for an SAP variable and the member value does not exist, related hierarchy columns may not be returned in the result set.

For more information about report parameters, see Chapter 18, “Designing a report parameter.”

4 Select Include if you want the MDX query to return data associated with the SAP variable’s value.

If you select Include and a value is provided for the variable either on SAP BW BEx Data Source Builder—SAP Variables or by the report user, the keyword INCLUDING appears in the MDX query, for example:

[0P_CALYE] INCLUDING [0CALYEAR].[1994][ODBCONT] INCLUDING [ODB_CONT].[EUR]

Do not select Include if you want the MDX query to return data that is not associated with the SAP variable’s value.

If you do not select Include and a value is provided for the variable either on SAP BW BEx Data Source Builder—SAP Variables or by the report user, the keyword EXCLUDING appears in the MDX query, for example:

[0P_CALYE] EXCLUDING [0CALYEAR].[1994][ODBCONT] EXCLUDING [ODB_CONT].[EUR]

Displaying and verifying an MDX querySAP BW BEx Data Source Builder—MDX displays an MDX query using technical names for the BEx query’s metadata. For more information about displaying technical names in SAP BW BEx Data Source Builder, see “How to display technical names in SAP BW BEx Data Source Builder,” earlier in this chapter.

280 D e v e l o p i n g A d v a n c e d e . R e p o r t s

How to verify an MDX query

To verify that an MDX query is valid, choose Verify MDX. If the query is not valid, e.Report Designer Professional displays an error message describing the problem.

How to clear an MDX query

To clear an MDX query, choose Clear Query.

Creating a report design that uses an SAP BW ODS data stream

Data in an SAP BW Operational Data Store (ODS) object is stored in database tables. An ODS object is associated with several InfoObjects. InfoObjects are similar to database columns. When you create a report design that uses an SAP BW ODS data stream, you create a data row component and associate the data row’s variables with InfoObjects.

To create a report design that uses an SAP BW ODS data stream, you must:

■ Create a blank report design.

■ Create an SAP connection component.

■ Create an ODS data source component.

■ Create a data row component.

■ Associate the data row’s class variables with the InfoObjects.

■ Set the fetch limit.

■ Drag database fields from Field List and drop them into frames in the report design.

How to create a report design that uses an SAP BW ODS data stream

1 Create a blank report design.

1 Choose File➛New.

2 In Create New Report, select Blank Report. Choose OK.

C h a p t e r 1 0 , D e s i g n i n g a r e p o r t t h a t u s e s a n S A P B W d a t a s t r e a m 281

2 Delete the DataStream component and the Connection component.

1 In Design Editor, select the DataStream component. Press Delete.

2 In Design Editor, select the Connection component. Press Delete.

The structure pane should look like the following illustration.

3 Create an SAP connection component.

282 D e v e l o p i n g A d v a n c e d e . R e p o r t s

1 Drag Connection from the Data palette and drop it in Connection.

2 In Select Component, select SAP Connection. Choose OK.

3 In Component Properties, enter the property values for the BW login configuration you created using SAPlogon. Choose OK.

For more information about creating a BW login configuration, see “Configuring the report development environment,” earlier in this chapter.

C h a p t e r 1 0 , D e s i g n i n g a r e p o r t t h a t u s e s a n S A P B W d a t a s t r e a m 283

4 Create an ODS data source component.

1 Drag Database Source from the Data palette and drop it in DataStream.

2 In Select Component, select SAP BW ODS. Choose OK.

284 D e v e l o p i n g A d v a n c e d e . R e p o r t s

3 In Component Properties, type the name of the ODS object. Choose OK.

5 Create a data row component.

1 Drag Data Row from the Data palette and drop it in DataRow.

The structure pane should look like the following illustration.

2 Create a class variable for each InfoObject in the ODS object.

C h a p t e r 1 0 , D e s i g n i n g a r e p o r t t h a t u s e s a n S A P B W d a t a s t r e a m 285

- In the structure pane, double-click DataRow1.- In Component Editor, choose Variables.- In Component Editor, choose New.- Complete Class Variable as shown in the illustration. Choose OK.

- Create the remaining class variables. Component Editor should look similar to the following illustration.

6 Associate the data row’s class variables with the database cursor’s columns (InfoObjects).

1 In the structure pane, select SAPOdsSource.

2 In Component Editor, choose Methods.

3 In Component Editor, select Sub BindDataRow( cursor As AcDBCursor ). Choose Override.

286 D e v e l o p i n g A d v a n c e d e . R e p o r t s

4 In Method Editor, type code similar to the following. Choose Close.

In the following example, database cursor columns (InfoObjects) are specified by position (1, 2, 3, etc.). You can also specify database cursor columns with the names of the InfoObjects. Do not include the leading zero.

Sub BindDataRow( cursor As AcDBCursor )cursor.BindColumn( 1, "NewReportApp::DataRow1", "column1" )cursor.BindColumn( 2, "NewReportApp::DataRow1", "column2" )cursor.BindColumn( 3, "NewReportApp::DataRow1", "column3" )

.

.

.End Sub

7 Set the fetch limit.

The fetch limit is the maximum number of rows to fetch from the ODS data source. If the Java Virtual Machine does not have enough memory to accommodate the result set, you must decrease the fetch limit or increase the Java Virtual Machine’s maximum heap size. For more information about changing the Java Virtual Machine’s maximum heap size, see “Changing the Java Virtual Machine’s maximum heap size,” later in this chapter, and Chapter 7, “Setting Actuate server parameters,” in Administering Actuate iServer System.

1 In Component Editor, choose Properties.

2 In FetchLimit, type the fetch limit. Choose Close.

10,000 is the default value. To retrieve all rows, type 0.

8 Drag database fields from Field List and drop them into frames in the report design.

For more information about Field List, see “Placing controls in a report design” in Chapter 12, “Working with frames and controls.”

C h a p t e r 1 0 , D e s i g n i n g a r e p o r t t h a t u s e s a n S A P B W d a t a s t r e a m 287

Changing the Java Virtual Machine’s maximum heap size

To change the Java Virtual Machine’s maximum heap size, create a registry key of type integer called JVMMaxHeapSize under HKEY_CURRENT_USER\Software\Actuate\e.Report Designer Professional 7.0\Settings. The unit for JVMMaxHeapSize is MB. For example, to change the Java Virtual Machine’s maximum heap size to 128 MB, set JVMMaxHeapSize to 128. If you set JVMMaxHeapSize to 0 or you do not set JVMMaxHeapSize, e.Report Designer Professional uses the Java default value.

Actuate’s Java Object Interface and charts also use the JVMMaxHeapSize setting.

288 D e v e l o p i n g A d v a n c e d e . R e p o r t s

C h a p t e r 1 1 , W o r k i n g w i t h s e c t i o n s 289

C h a p t e r

11Chapter 11Working with sections

This chapter contains the following topics:

■ About sections

■ About report sections

■ About group sections

■ Creating groups using Component Editor

■ Creating groups using Sorting and Grouping

■ About sequential sections

■ About conditional sections

■ About parallel sections

■ About the table of contents

■ Restructuring a large report

290 D e v e l o p i n g A d v a n c e d e . R e p o r t s

About sectionsA section is a component that determines the logical structure of the report. When you design a report, sections act as containers for other components. When you run the report, sections receive the incoming data rows and determine which components to instantiate to create the appropriate output.

Sections appear only as icons in the structure pane of Design Editor. When you look at the report design in the layout pane of Design Editor or run the report and view it, you do not see the sections themselves. The only visible sign of a section’s existence is the effect it has on the organization of the visual components, such as frames and controls.

The following table summarizes the five types of sections. Each type of section is described in more detail later in this chapter.

The report designer’s layout of sections can affect the success of end-user searches in report documents. For more information about report document searching, see “Understanding report document searching,” in Chapter 12, “Working with frames and controls.”

Section Description Example of use

Report section

Retrieves information from a data source and contains components to display that information.

Design a report or subreport.

Group section

Sorts data on a common field, such as customers grouped by state, and contains components to display the data group.

Design a grouped report to print orders for customers in various states.

Sequential section

Contains several frames or sections that display or print in a specified order.

Print two related reports, such as a sales history and a staffing history, one after the other.

Conditional section

Uses a conditional expression to determine which of two frames or sections to display or print.

Print different frames for salaried or commission employees.

Parallel section

Contains two or more report sections, sequential sections, or group sections that appear or print simultaneously in different flows on the same page.

Present two related reports, such as employee addresses and salary histories, printed side by side for easy comparison.

C h a p t e r 1 1 , W o r k i n g w i t h s e c t i o n s 291

About report sectionsA report section initiates and maintains the data stream to retrieve information from a data source. A report section also contains components to display the retrieved information.

Combining report sections in a report designYour report design can contain a single report section or many report sections. Each report section has its own data stream. The term subreport is sometimes used to indicate that a particular report section is only one of several in a report design.

You can combine report sections in several ways, as summarized in the following list:

■ Nested reports

■ Sequential reports

■ Conditional reports

■ Parallel reports

Using nested reportsYou can use a report section to read rows from a database, perhaps a company wide database of customers. For each row from the first report, you can use another report section to read rows from another database, perhaps a file that contains your notes for each customer. This second report is a nested report. You build a nested report by placing a report section in the Content slot of another report section.

Using sequential reportsYou can print several reports in sequence. The second report begins after the first one finishes, and so on. You build a sequential report by placing several report sections in a sequential section. For more information about sequential sections, see “About sequential sections,” later in this chapter.

Using conditional reportsYou can choose which of two report sections is actually instantiated depending on conditions when the user runs the report. For example, you can make a decision based on parameters entered by the user. You build a conditional report by placing two report sections in a conditional section. For more information about conditional sections, see “About conditional sections,” later in this chapter.

292 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Using parallel reportsYou can print two or more reports side by side. For example, you can print the job history for an employee on the left side of a page and print a salary history report on the right side of the page. You build a parallel report by placing several report sections in a parallel section. For more information about parallel sections, see “About parallel sections,” later in this chapter.

Placing a report section in a report designTo place a report section in a report design, do one of the following:

■ Select the appropriate Content slot and choose Insert➛Report.

Create New Report appears. You cannot use a template to place a report section in an existing report design.

■ Drag the report section icon from the Structure palette and drop it in the Content slot of a sequential section, the Reports slot of a parallel section, the Then or Else slot of a conditional section, or the Content slot of the report component.

You can also use a prebuilt report section from a library or from another report design.

For more information about slots, see “About slots” in Chapter 4, “Using Design Editor.”

C h a p t e r 1 1 , W o r k i n g w i t h s e c t i o n s 293

Placing components in a report sectionA report section can contain the following components:

■ Connection in the Connection slot.

■ Data stream in the DataStream slot.

■ Frame in the Before, After, PageHeader, or PageFooter slot.

■ Frame or section in the Content slot.

■ Subpage in the Subpage slot.

If you do not use a subpage, the report section uses the main page style component.

Sharing connections between report sectionsEach report section normally has its own connection component. If you place multiple sections in a report design, however, you can choose to have them share a connection to increase performance. Most databases incur considerable overhead when you open or close a connection. Some vendors limit the number of connections you can have open at the same time.

If you do not place a connection component in a report section, and that report section requires a connection, the Factory searches upward through the report structure to look for a connection when the user runs the report.

For example, suppose your report includes two report sections, which you want to print one after the other. You use a sequential section to hold the two report sections. Rather than placing a connection component in each report section, you can place the connection component in the sequential section so that both report sections can use it.

About group sectionsA group section is a component that groups data on a common field and contains components to display that data. For example, you can use a group section to group customer data by state. If your report uses a query data stream, the group keys in group sections are also used as sort keys to sort the data. Use a group section to accomplish the following tasks:

■ Build a grouped report.

■ Sort data in a report with a query data stream.

■ Accumulate and display totals or other summary data for a group of data.

■ Associate headers and footers with a group of data.

294 D e v e l o p i n g A d v a n c e d e . R e p o r t s

A common type of report is a grouped report, in which Actuate sorts data and displays it according to one or more common data values. Actuate groups all the data that shares one common value. For example, you can display orders in groups by customer. You can group the customers in turn by geographic region.

A grouped report presents data in an organized way that is more meaningful to the reader than simply listing the data. A grouped report also provides a way to avoid repeating information. For example, you need to print the customer’s name and address only once, at the beginning of the group of orders for that customer, rather than including the customer name with every order.

For example, consider the following set of rows. Each row represents an item in a sales order. The rows are sorted according to order number. The set of rows that contain all the items for one order is called one order group. The order groups, in turn, are sorted according to customer number. The set of rows that contain all the orders for one customer is called one customer group.

The column that contains a value on which rows are sorted is called a sort key column. Each group section in your report design corresponds to one sort key column.

Actuate e.Report Designer Professional gives you multiple ways to develop group sections in a report. One consists of dragging and dropping components in the Design Editor’s structure pane. This method relies heavily on Component Editor. A second way to implement group sections involves the Sorting and Grouping dialog. For information about these design techniques, see “Creating groups using Component Editor,” and “Creating groups using Sorting and Grouping,” later in this chapter.

Customer No. Order No. Item No.

1 100 11 100 21 100 31 105 11 105 22 101 12 101 22 117 12 117 2

Sorted data rows

Order 100

Order 105

Order 101

Order 117

Order groups

Customer 1

Customer 2

Customer groups

C h a p t e r 1 1 , W o r k i n g w i t h s e c t i o n s 295

Creating groups using Component EditorPlacing a group section in another group section is called nesting group sections. The outermost group section is placed in the Content slot of a report section. The following illustration shows nested group sections.

To place a group section in a report design, drag the group section icon from the Structure palette drop it in the Content slot of a report section or group section in Design Editor.

296 D e v e l o p i n g A d v a n c e d e . R e p o r t s

You can also use a prebuilt group section from a library or from another report design.

Specifying a group key for a group section After placing a group section component in a report design, you specify which data corresponds to that section. Each group section corresponds to a sort key column, which is one of the columns returned by the data stream.

To set the key for a group section, set the section’s Key property to the appropriate column name. For example, the following illustration shows the Key property in the Properties page for the OfficeGroup1 section.

If you are not using the query data source component provided by Actuate e.Report Designer Professional, you must make sure the sort key in the data stream matches the keys in the group sections. If you are using the e.Report Designer Professional query data source component, e.Report Designer Professional modifies the sort key in the query to match the group sections.

Sorting data with group sectionsIf you are using the Actuate query data source component, you can use group sections to sort data. When you place or modify a group section, e.Report Designer Professional records the column name you assign to the group section’s Key property. When you run the report, e.Report Designer Professional modifies the ORDER BY clause of the query to match the keys in the group sections.

You can choose whether the sorting for each key is done in ascending or descending order. Type Asc or Desc after the sort key name in the group section’s Key property. Ascending order is the default setting. The following illustration shows how to sort customers in descending order.

Key property specifies the sorted group of data that corresponds to this group section

C h a p t e r 1 1 , W o r k i n g w i t h s e c t i o n s 297

As you place group sections one inside the other, you create a nested group structure that specifies the sort order of the data. The innermost group section often contains a frame to print the most detailed level of data. If you want to sort the data in that frame, add one final sort key column to the query using Query Editor. For more information about how to edit the sort key, see “Sorting data with Query Editor” in Chapter 7, “Using a query data stream.”

The following illustration shows a typical structure of nested group sections and the corresponding ORDER BY clause in the query. Actuate e.Report Designer Professional adds the first two sort keys to match the keys in the group sections. You add the third entry, items.itemcode, using Query Editor.

Grouping data by intervalIn some cases, it is more convenient to group data by interval than by a single value. For example, if you are grouping data by date, you probably want to group the data by a period such as a week, month, or year, and not by a single date. To group data by interval, use the GroupInterval and GroupOn properties.

Group sections in structure pane

Corresponding ORDER BY clauseORDER BY customers.custID, orders.orderID, items.itemcode

298 D e v e l o p i n g A d v a n c e d e . R e p o r t s

For example, in the following report, a shipping schedule is grouped by periods of one calendar week.

The report design contains one group section with the following properties.

These properties specify grouping the data in the report by the database column orders.shipByDate, and grouping dates in the same calendar week together. To group dates in the same two consecutive calendar weeks together, set GroupInterval to 2. You can also group dates by month, quarter, or year.

Placing components in a group sectionA group section provides slots in which you can place components for the section to use in various ways.

C h a p t e r 1 1 , W o r k i n g w i t h s e c t i o n s 299

A group section can contain the following components:

■ Connection component in the Connection slot.

■ Frame in the PageHeader, Before, Content, After, or PageFooter slot. You can then place a Chart component in the new Frame in any of these slots.

■ Report, Sequential, Parallel, or Conditional in the Before, Content, or After slot.

■ Subpage component in the Subpage slot.

■ Another group section in the Content slot.

The following illustration shows which types of components you can place in each slot.

For more information about slots, see “About slots” in Chapter 4, “Using Design Editor.”

Subpage

Connection

Report

Parallel

Structure components

Conditional

Group

Frame

Sequential

300 D e v e l o p i n g A d v a n c e d e . R e p o r t s

The following table summarizes how you use each of the slots in a group section.

The following illustration shows the sequence in which components from these slots display or print. The pages shown are for a grouped report with a subpage section.

Slot Contains Location Example of use

Connection Connection Not applicable (the component does not appear in the report).

Separate database connection for this section.

Before Frame Before the group. Column headings such as Name and Phone for a customer group.

PageHeader Frame Top of each page as the group continues.

Running header that repeats the column headings to keep readers oriented.

Content Frame or section

Between Before and After. Content is where the group’s data prints.

Customer names and phone numbers.

PageFooter Frame Bottom of each page of the group.

Page numbers or text: “To be continued.”

After Frame After the group. Total number of customers in the group.

Subpage Subpage, Frame

After the page footer. A second, “subdesign” in the report.

C h a p t e r 1 1 , W o r k i n g w i t h s e c t i o n s 301

Understanding what group sections do when you run a reportRemember that a group section corresponds to one column from the sort key. Each time the section receives a data row, the group section determines whether the value of the sort key has changed. The change in the value of the sort key indicates the end of one group of data and the start of the next group. The group section instantiates each of the components it contains in sequence. Some components, such as the Before frame, are instantiated only once each time the value of the sort key changes.

The following illustration shows the sequence of events for a simple group section that processes a series of data rows containing orders sorted by customer number and order number.

Customer 1, Order 1

Customer 1 Title

Customer 1 Orders

Customer 1 Totals

302 D e v e l o p i n g A d v a n c e d e . R e p o r t s

1 The customer group section receives a data row.

2 The frame in the customer group’s Before slot is printed if the row contains a new customer number.

3 The OrderGroup section in the Content slot prints the order.

Keep in mind that the OrderGroup section contains its own components and prints them for each group of order data, which is the items in one order. The order group keeps track of both its own sort key, which is the order number, and that of the customer group section. If either key changes, or if both do, the order group section begins a new data group. This is the essence of how nested group sections work.

4 The frame in the customer group’s After slot is printed if the data row contains a new customer number.

This process repeats for each order the data stream returns. The following illustration shows the report that results.

Creating groups using Sorting and GroupingActuate e.Report Designer Professional provides an easy way to add grouping levels to a report using Sorting and Grouping. In this dialog, you can specify the group sections and the group key for each group section. You can move groups up and down in the priority list, and you can set options for each group, such as grouping intervals.

The settings in Sorting and Grouping apply to the report section that contains the selected component or slot. If no component or slot is selected, the settings apply to the top-level report section.

To use Sorting and Grouping with a library, open the library directly. You cannot use Sorting and Grouping with a view of an included library.

Customer group titleOrdersCustomer group total

Customer group titleOrders

Customer group total

Abernathy, James

Order 1

Total: $$

Anderson, Sally

Order 1

Order 2

Total: $$

C h a p t e r 1 1 , W o r k i n g w i t h s e c t i o n s 303

Adding groupsTo create group sections for a report, do the following:

1 Choose Tools➛Sorting and Grouping.

Sorting and Grouping—Grouping displays the fields available for grouping. The left side shows fields in your report’s tables and views that are not yet specified as group keys. The right side shows the same fields in the detail frame of the report.

The detail frame is the content frame of the innermost group section in a nested report or the content frame of a report that does not have nested sections.

2 Double-click the field to group, or select the field and choose >.

Actuate e.Report Designer Professional adds a group section for the field, removing the field from the Available Fields list and the detail frame of the report. e.Report Designer Professional adds the group directly before the detail frame.

3 Double-click a second field to group on.

Actuate e.Report Designer Professional adds the new group after the first group and before the detail frame.

4 To add more groups, double-click each group in the Available Fields list or choose >.

5 If you want to change the order of fields to group by, use the up arrow and down arrow buttons.

304 D e v e l o p i n g A d v a n c e d e . R e p o r t s

6 To finish grouping, choose OK.

For information about setting grouping options, see “Setting grouping options,” later in this chapter.

For information about sorting in the groups, see “Sorting data inside groups,” later in this chapter.

Removing groups1 Select the group key for the group in the right pane of Sorting and

Grouping.

2 Choose the < arrow.

e.Report Designer Professional removes the group from the right pane, and the field displays again in the Available Fields list.

You can also double-click the group key to move the group from the right to the left pane.

Setting grouping optionsYou can set grouping options to display Page Header, Page Footer, Before, and After frames for a group and to insert a page break before or after each group. You can set a sort order for the groups. This sorting is at the group level. To sort at the data row level in the groups, see “Sorting data inside groups,” later in this chapter.

1 In Sorting and Grouping, choose Grouping Options.

This button is available only if the report has one or more groups.

2 In Grouping Options, choose the Group Key field and select a group key from the list.

3 To change the sort order of the selected group, choose the Sort Order field and select Ascending or Descending from the list.

C h a p t e r 1 1 , W o r k i n g w i t h s e c t i o n s 305

4 To turn any of the frames on or off for the selected group, select the frame field and choose Yes or No from the list.

5 To add a page break before or after the selected group, select the Page Break Before or Page Break After field and choose Yes.

6 To set a grouping interval, see “Setting grouping intervals,” later in this chapter.

Setting grouping intervalsA grouping interval is a way of summarizing data further. For example, a grouping interval for a Phone field might be the 3-digit area code. Using this grouping interval, you could create a report that grouped orders by area code.

306 D e v e l o p i n g A d v a n c e d e . R e p o r t s

When you select a group key in Grouping Options to create a grouping interval for, e.Report Designer Professional displays intervals that are relevant to that key. For example, if you select Customer_Name, the list of intervals includes 1st letter, 2 initial letters, and 3 initial letters.

To set a grouping interval for a group key:

1 In Grouping Options, select the group key from the list.

2 Choose the Grouping Interval field and select an interval from the list.

3 Choose OK.

Sorting data inside groupsOnce you have created group sections for a report, you can sort the detail records inside the groups. This sorting is at the data row level. The sorting described in the previous section is at the group level. You can sort in ascending or descending order.

The fields listed on Sorting and Grouping—Sorting are fields that have not already been chosen as group keys on Sorting and Grouping—Grouping.

To sort detail records in a report:

1 Choose Tools➛Sorting and Grouping.

2 Choose the Sorting tab.

3 Click under Fields To Sort By.

A drop-down list appears. The list contains fields that are not already chosen as group keys. Fields are listed alphabetically.

4 Select a field from the list.

C h a p t e r 1 1 , W o r k i n g w i t h s e c t i o n s 307

5 To specify the sort order, select Ascending or Descending.

6 Repeat steps 3, 4, and 5 for each additional field you want to sort by.

7 To delete a sort key, select the field and choose None from the list.

If the deleted field was last in the list, the field is blank. Otherwise, the remaining fields move up in the list.

8 If you want to change the order of fields in the Fields To Sort By list, use the up arrow and down arrow buttons.

9 Choose OK.

About sequential sectionsA sequential section is a component that contains several frames or sections that display or print in a specified order. For example, you might use a sequential section to create a report that prints a company’s sales history followed by its staffing history. Use a sequential section to accomplish the following tasks:

■ Include several reports to display or print data from several queries.

■ Include several reports with the same query to print different reports based on the same data but with different controls.

308 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Placing a sequential section in a report designTo place a sequential section in a report design, drag the sequential section icon from the Structure palette and drop it in another section’s Content slot.

You can also use a prebuilt sequential section from a library or from another report design.

The following illustration shows a typical report structure using a sequential section. The section prints three reports, one after the other.

Placing components in a sequential sectionA sequential section provides three slots, the Connection slot, the Content slot and the Subpage slot. A sequential section can contain the following components:

■ One or more frames or sections in the Content slot

■ One optional subpage in the Subpage slot

C h a p t e r 1 1 , W o r k i n g w i t h s e c t i o n s 309

The following illustration shows which types of components you can place in the Content slot.

The components you place in the Content slot do not all have to be the same type. If you do not place a subpage in the Subpage slot, the sequential section uses the current page component.

For more information about slots, see “About slots” in Chapter 4, “Using Design Editor.”

Specifying the print order in a sequential sectionUsing the default print order setting, the components in a sequential section print in the order in which you placed them in the section. You can change the default order setting and so change the order in which they appear in the report object instance (.roi) file and the order in which they print.

How to specify the printing order in a sequential section

A simple way to change the printing order or the display order in the generated report object instance (.roi) file is to swap the positions of the components in the structure pane of Design Editor, using Scratch Pad. For information about Scratch Pad, see “About Scratch Pad” in Chapter 4, “Using Design Editor.”

You can also use the following steps to specify an order number for each component:

1 In the structure pane, right-click a Content component in the sequential section and choose Slot Information.

Structure Reference List appears.

2 To reorder a component in Structure Reference List, select the name of the component and use the up or down arrow buttons to move the component in the list.

Structure components

310 D e v e l o p i n g A d v a n c e d e . R e p o r t s

The following illustration is from Forecast.rod, contained in e.Report Designer Professional’s Examples directory.

What sequential sections do when you run a reportThe following illustration shows the sequence of events for a simple sequential section.

1 The report section that contains the sequential section can pass data along to the sequential section. Any frames that are contained in the sequential section can receive this data. In this illustration, the TitlePage frame receives data from the outer report.

Select component name and use arrow buttons to reorder

Data (if any) from containing report

Title

Report 1

Report 2

Report 3

C h a p t e r 1 1 , W o r k i n g w i t h s e c t i o n s 311

2 Each component in the section prints its output. In this illustration, the TitlePage frame is printed first, then each report section is printed. Each report section can contain its own data stream and print data from a different query.

The following illustration shows the report that results.

About conditional sectionsA conditional section is a component that uses a conditional expression to determine which of two frames or sections to display or print. Use a conditional section to accomplish the following tasks:

■ The user who runs the report can enter parameters to choose which content to print.

■ The user can choose between two subreports to display data from different queries.

■ The user can choose between frames depending on data in the data row.

Reports 1, 2, 3

Report 1

Report 3

Report 2 cont’d

Report 2

312 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Placing a conditional section in a report designTo place a conditional section in a report design, drag the conditional section icon from the Structure palette and drop it in another section’s Content slot. You cannot, however, place a conditional section in a parallel section.

You can also use a prebuilt conditional section from a library or from another report design.

The following illustration shows a report structure that uses nested conditional sections.

Specifying the condition for a conditional sectionAfter placing a conditional section component in a report design, you specify its conditional expression. When a user runs the report, Actuate evaluates this expression to determine what to print for that section. Depending on where

Conditional section

C h a p t e r 1 1 , W o r k i n g w i t h s e c t i o n s 313

you placed the conditional section, the expression can refer to parameters, global variables, or data row columns.

You can use column names in the conditional expression only if the conditional section is in the Content slot of a report section or group section.

To specify the conditional expression, set the section’s IfExp property to a Boolean expression that returns True or False. If the expression in IfExp is True, the component in the Then slot is used. If the expression is False, the component in the Else slot is used.

Placing components in a conditional sectionA conditional section provides four slots, the Connection, Then, Else, and Subpage slots. A conditional section can contain the following components:

■ A connection component in the connection slot. This component is optional.

■ A frame or section in the Then and Else slots.

■ An optional subpage in the Subpage slot.

314 D e v e l o p i n g A d v a n c e d e . R e p o r t s

The following illustration shows which types of components you can place in the Then or Else slots.

You can place only a connection component in the Connection slot. The components you place in the Then or Else slots do not have to be the same type. If you do not place a subpage in the Subpage slot, the conditional section uses the current page component.

For more information about slots, see “About slots” in Chapter 4, “Using Design Editor.”

Understanding what conditional sections do when you run a reportEach time the section’s content is to be printed, Actuate e.Report Designer Professional evaluates the conditional expression and chooses the appropriate component to generate the output. The following illustration shows how an Employees group section could be implemented using a conditional section to print alternative frames for salaried and commission employees. The data rows contain information about employees and departments, sorted by employee name in each department.

Structure components

Department name

Department Title

Prints if status = “salaried”

Prints if status = “commission”

C h a p t e r 1 1 , W o r k i n g w i t h s e c t i o n s 315

1 The Department group section receives a data row.

2 The frame in the Department group’s Before slot is printed if the data row contains a new department name, such as Operations.

3 The Employee group section prints information about the employee. The conditional expression is evaluated, and depending on the result, one of the frames prints.

This process repeats for each employee. The following illustration shows the report that results.

For more information about group sections, see “About group sections,” earlier in this chapter.

About parallel sectionsA parallel section is a component that contains two or more subreports that appear or print simultaneously in different flows on the same page. Use a parallel section to present different reports side by side.

Accounting Sales

Anderson, J.

Parker, M.

Porter, C.Evans, L.

Salaried frame

Charter, K.

Commission frame

Title

316 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Placing a parallel section in a report designYou can place a parallel section component in the Content slot of any type of section. To place a parallel section in a report design, drag the parallel section icon from the Structure palette and drop it in another section’s Content slot.

You can also use a prebuilt parallel section from a library or from another report design.

Placing components in a parallel sectionA parallel section provides three slots, the Connection slot, the Reports slot and the Subpage slot. A parallel section can contain the following components:

■ A connection component in the Connection slot.

■ Two or more report sections in the Reports slot.

■ One optional subpage in the Subpage slot.

The following illustration shows a typical parallel section.

If you do not place a subpage in the Subpage slot, the parallel section uses the current page component.

C h a p t e r 1 1 , W o r k i n g w i t h s e c t i o n s 317

Assigning flows to parallel subreportsThe subpage or page component used by a parallel section must have enough flows to print all of the subreports. For example, if you place three subreports in a parallel section, the subpage or page must contain three flows. You specify the flow in which a report appears by assigning the flow name to the report.

If the parallel section contains a subpage component, the section uses the flows on that subpage. Otherwise, the parallel section uses the flows on the current page component. Remember that a report design can contain several page components. For example, the design might include different page components for the even-numbered and odd-numbered pages.

For more information about pages and subpages, see Chapter 16, “Designing a page layout.”

How to specify flows for parallel subreports

1 Double-click a report section in the parallel section.

2 In the FlowName property, type the name of the flow in which the report is to appear.

The name is the class name you assigned to the flow.

3 Repeat steps 1 and 2 to assign flows to all the report sections in the parallel section.

What parallel sections do when you run a reportThe following illustration shows a typical set of components in a parallel section, the flow layout in the subpage, and the output that results when you run the report. The information that appears in each report depends on how you designed each subreport.

Subpage Displayed or printed report

Flow1 Flow2 Report1

Report2

Structure pane

318 D e v e l o p i n g A d v a n c e d e . R e p o r t s

About the table of contentsThe table of contents provides an effective way for you to learn about a report’s organization and easily navigate to grouped information in reports. The table of contents and search provide complementary navigational tools. Once you navigate to the information group, you can browse forward or use the search feature to find detailed information. Very large tables of contents present two problems:

■ Long report generation and viewing time

■ Usability issues

Extremely large tables of contents can cause View-time errors.

About table of contents propertiesActuate e.Report Designer Professional table of contents properties default values are set to include the levels of information needed in the table of contents. The values for the TOC➛TocAddComponent and TOC➛TocAddContents properties determine whether the components and subcomponents appear in the table of contents. The information groups that should appear in the table of contents are usually represented by section components. The default values for TocAddComponent and TocAddContents on lower-level components such as frames and controls suppress table of contents entries. Usually these components are not presented in the report’s table of contents.

Developing a table of contents for grouped reportsTable of contents entries for group sections are generated because the default value for the TOC➛TocAddComponent property is TOCIfAllVisible. By setting TocAddComponent to TOCIfAllVisible, one entry for the group section and one entry for each unique value of the group section’s key property appear in the table of contents only if the user has access to any of the pages produced by the group section. To disregard any access considerations, set TocAddComponent to TOCIfAnyVisible. For information about how Actuate determines whether a user has access to pages, see Chapter 8, “Designing a report with page-level security,” in Programming e.Reports.

If the number of detail rows generated for the group section is large, break up the group section into smaller group sections to limit the number of table of contents entries.

C h a p t e r 1 1 , W o r k i n g w i t h s e c t i o n s 319

The following illustration shows the structure of the Detail report in the \Program Files\Actuate7\Erdpro\Examples\Detail folder. Instead of having a single group section with a key consisting of multiple columns, this report has four nested group sections. Each nested group section has a single column sort key. The groups are as follows:

■ OfficeGroup sorted by office ID

■ SalesRepGroup sorted by sales representative’s last name

■ CustomerGroup sorted by customer name

■ OrderGroup sorted by order ID

The following illustration shows the default settings for the TOC properties group for the group section SalesRepGroup.

320 D e v e l o p i n g A d v a n c e d e . R e p o r t s

The table of contents built from the nested group sections appears in the following illustration. The table of contents allows for easy navigation because a manageable number of entries are present at each level of the table of contents.

Developing a table of contents for other reportsReport section components automatically generate a single table of contents entry, because e.Report Designer Professional’s default settings for TOC➛ TocAddComponent is TOCIfAllVisible and TOC➛TocAddContents is True.

The Forecast report’s table of contents contains only one entry for each of the report sections in the report design, because the TOC➛TocAddContents property is set to False for the Issues, TopDeals, Negative Changes, and Positive Changes reports. For the Negative Changes report, the following illustration shows the TocAddContents property set to False. The Forecast report is located in the \Program Files\Actuate7\Erdpro\Examples\Forecast folder.

C h a p t e r 1 1 , W o r k i n g w i t h s e c t i o n s 321

The following illustration shows the Forecast report’s table of contents, displaying only one entry for each of the report sections.

Restructuring a large reportTo make large reports more usable, break up large reports into smaller reports that you access from a master report. Restructuring works well when the database content changes during the time you need the report. To create the restructured report, do the following:

■ Identify small reports of less than 500 pages that contain related information groups.

■ Create a separate report for each related information group.

■ Create a small master report that contains hyperlinks to the smaller reports.

If CPU resources and Factory servers are available, report generation throughput improves because the master report and subreports execute in parallel. The ability to jump to key information groups improves the report’s usability. After applying this technique, however, information might be more difficult to find using the Actuate search tools because of the multiple, independent reports.

The Forecast report in the \Program Files\Actuate7\Erdpro\Examples folder structures a long report into a master report and subreports. The report design’s online viewing features illustrate navigation between a master report and subreports. The report design uses a sequential section component to organize the master report, Summary, and the subreports, Issues, TopDeals, NegativeChanges, and PositiveChanges. You navigate to the subreports from hyperlinks in the Summary report. Each report contains its own SQL query.

322 D e v e l o p i n g A d v a n c e d e . R e p o r t s

The Summary report contains hyperlinks to the beginning of each of the subreports.

The type of hyperlink destinations in your report design can affect report generation and viewing time. The Factory builds a list of object instances corresponding to hyperlink destinations. Links to unique destinations such as report or group sections perform faster than links to controls because a control can generate thousands of object instances. To jump from one report to the beginning of another report, set the hyperlink destination to the report or group section component representing the report.

For example, the following illustration shows how you jump from the Top Deals section in the Summary report to the Top Deals subreport by choosing More as shown in the following illustration.

C h a p t e r 1 1 , W o r k i n g w i t h s e c t i o n s 323

Report bursting further optimizes the Forecast report for online viewing. Report bursting is the technique of creating multiple report documents from a single report object executable (.rox) file. In the optimized Forecast report, each of the subreports is a separate report object instance (.roi) file. Viewing performance improves because you view a smaller ROI file. The hyperlinks from the Summary report jump to separate ROI files corresponding to the subreports. You cannot run reports that use report bursting synchronously. A report that uses report bursting generates other reports. Because the iServer cannot display multiple reports synchronously, the iServer generates an error message.

Depending on your data and reporting needs, alternatives to restructuring the report include report bursting and page-level security. For more information about report bursting, see Chapter 13, “Understanding report bursting techniques,” in Programming e.Reports. For more information about page-level security, see Chapter 8, “Designing a report with page-level security,” in Programming e.Reports.

324 D e v e l o p i n g A d v a n c e d e . R e p o r t s

C h a p t e r 1 2 , W o r k i n g w i t h f r a m e s a n d c o n t r o l s 325

C h a p t e r

12Chapter 12Working with frames and

controlsThis chapter contains the following topics:

■ About frames

■ About controls

■ Placing frames in a report design

■ Placing controls in a report design

■ Setting display values for controls

■ Formatting data in a control

■ Formatting frames and controls

■ Providing help

■ Hiding frames and controls

■ Working with image controls

■ Working with OLE controls

■ Understanding report document searching

■ Creating an index to improve search performance

■ About the LinkExp property

■ Analyzing report data with e.Analysis

326 D e v e l o p i n g A d v a n c e d e . R e p o r t s

About framesA frame is a rectangular container for controls. When you run the report and view or print it, you see a collection of frames and controls. By placing a set of related controls in a frame, you can manipulate the controls as a group. For example, you can move a frame from one place to another in a report design or publish it in a component library for reuse in other designs.

The following illustration shows a simple frame. This frame contains eight controls, including the horizontal line through the image.

You can create frames that do not display data from the data stream. These frames contain only static controls such as images and labels. Most frames, by contrast, display data from the data rows provided by the data stream. Each frame is associated with one type of data row.

When you place a frame in a report section, Actuate e.Report Designer Professional associates the frame with that report’s data row. For example, in the following illustration, Actuate e.Report Designer Professional associates Data Row 1 with Frame 1 and Data Row 2 with Frame 2.

C h a p t e r 1 2 , W o r k i n g w i t h f r a m e s a n d c o n t r o l s 327

When you place a frame from a component library in a report, keep in mind that the frame was probably designed to work with a particular data row. Make certain that the data row in the report has all the variables needed. For example, a library frame might display data from database columns called customers.Lname and customers.Fname. The data row in the report must include variables for at least those two columns. It can also contain other variables.

For more information about data rows, see “About data rows” in Chapter 7, “Using a query data stream.”

About controls A control is a component that displays data, graphics, or other information. Controls are the most visible building blocks in a report. When you run a report and view or print it, all the information you see appears in controls. There are two general types of controls: data controls and static controls.

About data controlsData controls typically display data from one or more variables in a data row. A data control can also display values that are evaluated from a specified expression that can include Actuate Basic functions, operators, data row variables, or any combination of the three. For example, to display the total amount for an item in an order, you might multiply the number of items by the

328 D e v e l o p i n g A d v a n c e d e . R e p o r t s

price per item and display the result in a currency control. To display the current date and time, you can use the Now( ) function and display the result in a text control.

If data controls display data from a data row, you must place them in a frame. Otherwise, place them either in a frame or directly on a page. Data controls include text, dynamic text, integer, floating point, currency, and date/time controls.

For more information about displaying data in a control, see “Setting display values for controls,” later in this chapter.

About static controlsStatic controls display static elements, such as lines, images, and text labels. Static controls, which include label, image, and drawing controls, do not interact with a data row. They can be placed in a frame or directly on a page.

Understanding how controls affect report generation timeThe report generation time required to build a page is directly proportional to the number of controls on the page. Also, the time required to render an Actuate DHTML report is directly proportional to the number of controls on the page. Minimize the number of controls on a page to optimize report generation or rendering time.

For example, you can draw a table with rectangle and line controls or by using text controls with a border to create the table cells. Use the technique that results in the fewest controls. Ensure that you do not use both techniques. When you create a rectangle on a report page, use the rectangle control instead of drawing a rectangle with four line controls.

A report that uses dynamic text controls also takes longer to generate than a report that doesn’t use them. Use the dynamic text control only if the data to display from the data row contains multiple style formats or a variable amount of text. Otherwise, use the text control. For more information about using the dynamic text control, see Chapter 13, “Working with a dynamic text control.”

Placing frames in a report designTo place a frame in a report design, drag the frame icon from the Structure palette and drop it in a section’s Content, Before, After, PageHeader, or PageFooter slot. You also can place a frame in another frame.

C h a p t e r 1 2 , W o r k i n g w i t h f r a m e s a n d c o n t r o l s 329

The following illustration shows a group section component that contains frames in Before and PageHeader slots. The arrow shows how to place a frame in the Content slot.

You also can use prebuilt frames from a library. For more information about the ways to add frames to a report, see “Placing components in a report design” in Chapter 4, “Using Design Editor.”

The following illustration shows Design Editor after a frame is placed in the Content slot of a group section. The frame appears as an icon in the structure pane and as a rectangular area in the layout pane. Keep in mind that these are two views of the same frame, not two different frames.

Frame symbol in structure pane

Frame inlayout pane

330 D e v e l o p i n g A d v a n c e d e . R e p o r t s

You can also place a frame in a report design by dragging the gray bar under the slot name.

To remove the frame from the report design, drag the bottom edge of the frame to the top edge of the frame.

To place a frame in an empty Content slot, use one of the methods described above, or choose Insert➛Detail. To remove the frame from the report design, choose Insert➛Detail again.

Placing controls in a report designIn general, you place a control in a frame or directly on a page. Controls that display data from the data stream’s data row must, however, be placed in a frame. This section concentrates on placing controls in frames. For more information about placing controls on pages, see Chapter 16, “Designing a page layout.”

You can drag a control from the Controls palette and drop it in a frame’s Content slot or directly into the frame in the layout pane. You can also use the Insert menu or draw the control instead of simply dropping it. For a description of these methods of adding controls, see “Placing components in a report design” in Chapter 4, “Using Design Editor.”

Actuate e.Report Designer Professional provides a shortcut for placing data controls from the data stream in a frame. By using Field List, you place the data controls and associate them with data in one operation.

The following illustration shows a frame that contains an image, a label, and a text control.

C h a p t e r 1 2 , W o r k i n g w i t h f r a m e s a n d c o n t r o l s 331

To place data controls in a frame, choose Insert➛Database Field, or use Field List.

Field List is a helper window that you use along with Design Editor. Use Field List to add data controls to a report design. Field List shows all the data row variables available for use in a particular frame. Variables that store values from database columns appear as the database column name, as shown in the following illustration. You can drag data row variables from Field List to the frame to add one or more controls that contain data from those variables.

Frame and controls in structure pane

Frame and controls in layout pane

Drag one or more columns and drop them in the layout pane

332 D e v e l o p i n g A d v a n c e d e . R e p o r t s

The report section that contains the frame also contains a data row component. This data row determines which variables appear in Field List. For example, in the following illustration, Field List would show variables from Data Row 1 for Frame 1 and from Data Row 2 for Frame 2.

How to place controls and bind them to data

To place controls and bind them to data, use Field List. Before working with Field List, you must define a data row that contains variables. If you open Field List before the data row exists, there is nothing for Field List to display.

When you write a query using Query Editor, Actuate e.Report Designer Professional creates the data row for you based on your choices in Query Editor. If you do not use Query Editor, you must define your own data row. For more information about Query Editor, see “About queries” in Chapter 7, “Using a query data stream.” For more information about writing your own data row, see Programming e.Reports.

1 Select the frame in which you want to place a data control.

2 Choose View➛Field List.

C h a p t e r 1 2 , W o r k i n g w i t h f r a m e s a n d c o n t r o l s 333

3 Drag one or more variables from Field List and drop them in the selected frame in the layout pane.

Setting display values for controlsYou can associate controls with several kinds of data values. To specify the value a control displays, set the control’s ValueExp property. Set this property indirectly through Field List or directly by typing a value expression in the Properties page of Component Editor.

ValueExp has two purposes:

■ Determines how to set the value of the control from the data row by providing an expression to do so.

■ Determines whether the control takes one or multiple rows, if ValueType is set to AutoValueControl.

The rest of this section discusses value expressions in detail. For more information about the Properties page, see “Setting properties of components” in Chapter 4, “Using Design Editor.”

Control value expressions can include anything that is allowed in an Actuate Basic expression, as well as some additional items. Value expressions can include the following:

■ Actuate Basic function calls

■ Actuate Basic statements, operators, symbols, and keywords

334 D e v e l o p i n g A d v a n c e d e . R e p o r t s

■ Variables and constants

■ Method calls

■ Data row variables or database columns

■ References to the values of other controls

■ Aggregate values computed over a set of data rows

For example, the following value expression computes the percentage of credit remaining to a customer:

100 - ([customer.balance] / [customer.limit] * 100)

To get help writing a value expression, choose Builder next to the ValueExp property. Expression Builder appears. For more information about how to use Expression Builder, see “About Expression Builder” in Chapter 3, “Understanding the design environment.”

Using the ValueType propertyMost controls take a single value, for example a name or a number. Graphs and one-pass aggregate controls take multiple values. A graph takes values from many data rows. An aggregate control summarizes many data values, for example in a minimum, maximum, or sum.

If the ValueType property is set to the default value AutoValueControl, e.Report Designer Professional determines whether the control takes a single value or multiple values based on the expression in the ValueExp property. If you write Actuate Basic code to compute an aggregate, however, such as standard deviation, the value expression is blank and e.Report Designer Professional determines that the control takes only a single value. To indicate that the control takes multiple values, set ValueType to SummaryControl.

If ValueType is set to SummaryControl or PerRowControl, e.Report Designer Professional uses ValueType rather than the value expression to determine whether the control takes a single value or multiple values. For example, if ValueType is set to PerRowControl and the value expression is Sum([Sales]), the result is the same as if the value expression were [Sales]. It is never necessary to use PerRowControl.

C h a p t e r 1 2 , W o r k i n g w i t h f r a m e s a n d c o n t r o l s 335

Understanding Null values in control value expressionsRelational databases provide a special value called Null, which indicates that the field contains no data. Actuate Basic processes a control’s value expression containing Null in the same way that Visual Basic processes Null. The control is calculated appropriately in the finished report. To test for Null values, use the IsNull( ) function. For more information about Null and IsNull( ), see “Computing aggregates in a value expression,” later in this chapter, and Actuate Basic Language Reference.

Displaying data from a single column in a controlTo make a control display data from a single column in the data row, you will probably find it easiest to use Field List. For more information about how to use Field List, see “Placing controls in a report design,” earlier in this chapter. Instead of using Field List, you can select the column from the drop-down list box in the control’s ValueExp property or type the name of the column in brackets, using the following format:

[<table>.<column>]

For example:

[customers.FirstName]

The table name is one of the tables in your query. If you gave the table an alias, use the alias name. The name must be exactly the same as what you used in the query. If the column name is unique, you can omit the table name.

The column is one of the columns from the table. The column must be one of the columns selected by the query.

Displaying data from several columns in a controlYou can combine data from several columns into one control by setting the control’s ValueExp property to an expression that includes several column names. This type of control, as in the following example, is called a calculated control.

[items.quantity] * [items.pricequote][customer.limit] - [customer.balance][customer.fname] & " " & [customer.lname]

Referencing data row variables or functionsYou can use bracket notation to include a data row variable or function in a value expression. This is useful if you create your own data row, add extra variables to a data row created by Query Editor, or add a function to a data

336 D e v e l o p i n g A d v a n c e d e . R e p o r t s

row. Instead of the table and column name, use the variable or function name. For example, to reference a data row variable, enclose its name in brackets, as shown in the following example:

[customer_fname]

You can also use this notation for structures or objects in the data row. For example, suppose the data row includes a structured data type called Address that includes such variables as FullName, Street, and City. To reference one of these variables, use brackets and dot notation, as shown in the following example:

[Address.FullName]

You can use the same dot notation to refer to members of objects if the data row contains object reference variables.

In a data row that contains customer invoice data, you could include a function to tell how much of the invoice total is overdue. To reference that function in a value expression, enclose the function name in brackets, as shown in the following example:

[Amount30DaysLate]

When you use the bracket notation in a value expression, e.Report Designer Professional first checks to see whether the name inside the brackets is a database column. Therefore, if the data row variable or function name is the same as a column alias, the column is used instead.

For more information about customizing the data row and referring to objects, see Programming e.Reports.

Using methods or functions in a value expressionA control’s value expression can include calls to methods and functions. The methods and functions can be defined in the Actuate Foundation Classes, in Actuate Basic, or in code you write. For example, the following expression computes a discount based on a user-defined method, ComputeDiscount:

ComputeDiscount( [customer.id], [order.total_amount] )

The following expression uses an AFC method to display the page number:

PageNo$( )

The following expression uses an Actuate Basic function to display the current date:

Date$( )

C h a p t e r 1 2 , W o r k i n g w i t h f r a m e s a n d c o n t r o l s 337

Displaying a value that is not from the data rowSome controls are not associated with data from the data row. Label controls can display only static text. Data controls, such as integer controls, are often associated with columns from the data row, but they can also display values that are not derived from the data row. For example, you can use an integer control to display a page number.

For a label control, use the Text property to specify the text you want to display, such as a column heading. You can also use an expression that produces a text value.

To specify a nondata value for a numeric or text control, type a literal value or an expression in the control’s ValueExp property. The value expression can be anything that produces a value of the correct type, such as an arithmetic expression, a parameter the user supplies when they run the report, an Actuate Basic function, or a method.

To let the user enter a value for the control, include a parameter name in the value expression you assign to a control’s ValueExp property. For example, the following expression includes the parameter BiggestOrder:

BiggestOrder - [order.extension]

The user who runs the report supplies a value for each parameter you use in the report design. For more information about parameters, see Chapter 18, “Designing a report parameter.”

Referencing controls in a value expressionWhen writing the value expression for a control, you can use the values of other controls in the same frame. To refer to another control, include its class name in the value expression. For example, the following expression uses the values of three controls to calculate the total amount of an order:

Subtotal - Discount + Tax

Subtotal, Discount, and Tax are the class names of controls in the same frame as the control that uses this expression. You cannot refer to controls in other frames.

338 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Computing aggregates in a value expressionIf you want to summarize data for a set of data rows, use one of the seven aggregate functions in a control’s value expression, or choose Insert➛Total. These functions are also used in other kinds of expressions, such as to specify computed columns in Query Editor. The following table summarizes the aggregate functions.

Aggregate function Description Examples

Max(<ValueExp>) Returns the highest value found for ValueExp in the set of data rows.Max ignores rows where the ValueExp is Null.

Max([order.totalAmt])

Min(<ValueExp>) Returns the lowest value found for ValueExp in the set of data rows.Min ignores rows where the ValueExp is Null.

Min([customer.limit] - [customer.balance])

Sum(<ValueExp>) Returns the total of ValueExp for all data rows.Sum ignores rows where the ValueExp is Null.

Sum([items.quantity] * [items.pricequote])Sum(1, 2, Null)=3

Ave(<ValueExp>) Returns the average value of ValueExp over all data rows.Ave ignores rows where the ValueExp is Null.

Ave([salesperson.ytd_sales])Ave(2, 6, Null)=4

First(<ValueExp>) Returns the value of ValueExp in the first data row.First returns Null if the value of ValueExp in the first data row is Null.

First([customer.name])

C h a p t e r 1 2 , W o r k i n g w i t h f r a m e s a n d c o n t r o l s 339

The ValueExp parameter is any valid value expression. Each aggregate function has a default value. This default value is used if the function processes no data rows. Max( ), Min( ), Ave( ), First( ), and Last( ) use the default value Null. Sum( ) and Count( ) use the default value zero.

Comparing running and lookahead aggregatesYou can compute two types of aggregates in a control’s value expression. Running (or one-pass) aggregates are computed while the report is being built. Lookahead (or two-pass) aggregates are computed before the report is built.

A lookahead aggregate is useful when you want to know the total before you build the report. For example, you might want to use the total to compute a value to appear for each row. The syntax for a lookahead aggregate is as follows:

AggregateFunction(<ValueExp>)[Where(<Condition>)]{Group By(<GroupSectionKey>)|Overall}

Unlike lookahead aggregates, running aggregates are not available for use in row-by-row computations because the aggregate values are not known until after all rows have been processed. Running aggregates are most often used to compute values for controls in Before and After frames. The syntax for a running aggregate is as follows:

AggregateFunction(<ValueExp>)[Where(<Condition>)][Distinct(<Expression>)]

Last(<ValueExp>) Returns the value of ValueExp in the last data row.Last returns Null if the value of the ValueExp in the last data row is Null.

Last([order.shipDate])

Count( ) Returns the number of data rows.Count returns the number of rows, including rows with columns with Null values in them.

Count( )

Aggregate function Description Examples

340 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Specifying lookahead aggregatesTo specify a lookahead aggregate in a value expression, add the keywords Overall or Group By after the aggregate function and its arguments, using one of the following formats:

<AggregateFunction>(<ValueExp>) Overall

<AggregateFunction>(<ValueExp>) Group By(<GroupSectionKey>)

When you use the Overall keyword, the lookahead aggregate is computed over all data rows in the data stream.

When you use the Group By clause, the aggregate is computed over all data rows in a particular group section. GroupSectionKey is a database column name which is the sort key (Key property setting) of a group section in the report design. For example, the following expression, set in the ValueExp property, shows the total orders for a customer:

Sum([items.extension]) Group By([customers.ID])

The following expression, set in the ValueExp property, calculates the percentage of an entire department’s salary represented by one employee’s salary:

[emp.salary] / Sum([emp.salary]) Group By ([emp.dept]) * 100

For more information about group sections and the Key property, see “About group sections” in Chapter 11, “Working with sections.”

Selecting specific rows to include in an aggregateNormally, an aggregate function computes its return value using all the available rows. You can also specify that you want an aggregate computed over only a specific subset of the rows. To select rows for an aggregate function, add one of the following clauses:

■ The Distinct clause is used in running aggregates only.

■ The Where clause can be used in running or lookahead aggregates.

■ The Group By clause is used in lookahead aggregates only. For more information about the Group By clause, see “Specifying lookahead aggregates,” earlier in this chapter.

Using the Distinct clause in a value expressionThe Distinct clause in an Actuate e.Report Designer Professional expression operates so that a row is included in the aggregate only if the key value of that row differs from the key value of the previous row. Use the Distinct clause in running aggregates only, not in lookahead aggregates. The Distinct clause is particularly useful for filtering out duplicate values in groups of rows.

C h a p t e r 1 2 , W o r k i n g w i t h f r a m e s a n d c o n t r o l s 341

To use Distinct to calculate the unique number of items in a column, be sure the data is already ordered by the column that appears in the Distinct clause. The easiest way to sort is to place the column in the first position of the OrderBy page of Query Editor. For more information, see “How to order data for the Distinct clause” and “How to use the Distinct clause with two report sections,” later in this chapter.

For example, suppose the report includes rows sorted by order number and item number. Many of the OrdNum column values repeat row after row until the order number changes. For example, each order has several values for ItemNum but only one associated value for the Balance.

To calculate the sum of all order balances, you need a way to exclude the duplicate values and include only one order balance for each order ID. To accomplish this, use the Distinct clause as shown in the following example:

Sum( [orders.Balance] ) Distinct( [orders.OrderNumber] )

The syntax of the Distinct clause is as follows:

<AggregateFunction>(<ValueExp>) Distinct(<Expression>)

The Expression parameter is a list of one or more expressions. Each expression can include any of the following elements:

■ Reference to a data row column

■ Any Actuate Basic expression

■ Lookahead aggregate

Unlike the Group By clause, the expressions in the Distinct clause need not match any group section keys in the report. Therefore, the Distinct clause is useful for filtering rows, or counting distinct items, in reports that do not include group sections. The Distinct clause is also useful for reports that contain information that lies outside of a group section, such as that in a report created with one sequential section but two report sections.

For an example of building a report using the Distinct clause, see “How to use the Distinct clause with two report sections,” later in this chapter.

OrdNum

010010010020020

ItemNum

305325416229925

(other data)

. . .

. . .

. . .

. . .

. . .

Balance

200200200900900

342 D e v e l o p i n g A d v a n c e d e . R e p o r t s

How to order data for the Distinct clause

The Distinct clause with an aggregate function in a ValueExp calculates correctly when the data on which it is calculating is already in the correct order.

To work with the Distinct clause, the following process is recommended:

1 In Query Editor, Order By page, place the key on which you wish to have the item sorted in the first position. For example, if you are counting a distinct number of cities, place offices.city first in the items on the Order By page.

2 Place other items below this one on the Order By page.

3 Continue to fill out the pages of Query Editor.

4 Examine the SQL statement that is generated by the choices you have made in the pages of Query Editor.

The SQL statement now has, as its first item in the Order By clause, offices.city.

By the time the SQL statement has executed, the data items are correctly sorted and prepared for use by the Distinct clause that then operates on the control.

For an example that uses the Distinct clause in a report, see “How to use the Distinct clause with two report sections,” later in this chapter.

How to use the Distinct clause with two report sections

If the group section key is different from the Distinct( ) clause key, you might need to construct a report with a sequential section that contains two report sections to cause the Distinct( ) clause to correctly calculate.

In the example described below, which is one way of designing your report, the calculation takes place on items.description.

To prevent the group section from silently readjusting the SQL statement, which affects the Distinct( ) calculation, the Distinct( ) calculation must take place outside of the group section.

After you construct the report, the sequential section and two report sections are visible in the Design Editor’s structure and layout panes. The structure pane distinctly shows the order of items.

C h a p t e r 1 2 , W o r k i n g w i t h f r a m e s a n d c o n t r o l s 343

To create the upper section of this report, which has two sections, do the following:

1 Drag a sequential section and drop it into the topmost Content slot, which is just under the top-level AcReport component.

2 Drag a report section and drop it into the next Content slot.

3 Be sure the Connection component is just under the sequential section. This connection brings in your data, and you use the same data for both report sections in this report. This report uses the sfdata database.

4 Place the DataStream and DataRow components below the first report section.

In Query Editor, drag the orders table and the items table and drop them into the upper pane.

Be sure items.description is in the first position on the Order By page. Items.description is the column item that you will count for distinct occurrences. For more information about counting, see “How to order data for the Distinct clause,” earlier in this chapter.

5 Place the group section in the Content slot. In this example, the group section’s key is orders.orderID.

6 Place the Before and Content frames, and any other frames and controls you want below this OrderGroup.

7 In the next Content slot, place a text control.

8 Set ValueExp to items.description.

You have created the top half of your report. This portion contains the group section and the data.

Because you ordered the data by placing it correctly in the Order By page of Query Editor, the Distinct clause correctly calculates the number of distinct items.

344 D e v e l o p i n g A d v a n c e d e . R e p o r t s

In the second portion of your report, add another Report section, DataStream component, and frames to hold the control with the Count()Distinct() value expression.

In the second portion of the report, the Count Distinct takes place. Construct the second half of the report as follows:

1 Drag a report section and drop it on top of the sequential section.

The report section positions itself correctly after the first report section.

2 Drag a DataSource component and drop it into the DataStream slot.

3 Drag a DataRow component and drop it into the DataRow slot.

4 Place frames into the Content slot and After slots to contain the label and text controls for the results of the Count() Distinct() calculation.

5 In the control for the calculated item, which in this example is items.description, type the following in the ValueExp:

Count()Distinct([items.description])

C h a p t e r 1 2 , W o r k i n g w i t h f r a m e s a n d c o n t r o l s 345

The design of your report now includes the appropriate sections, frames, and value expressions.

After you build, run, and view your report design, the resulting report contains the calculation on the distinct number of items in items.description.

The Distinct clause calculation takes place outside the group section, the key of which is orders.orderID. Because the control containing the Distinct() clause is in the second report section, and is outside and after the group section, the calculation of the Distinct() clause correctly operates after the items are already in the correct order.

Though an item such as 32M x 4 Static Ram repeats several times throughout this multi-page report, this item adds to the count only once. The resulting calculation, 82, correctly calculates the number of distinct items in the set of items.description.

346 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Using the Where clause in a value expressionThe Where clause specifies that a row is included in the aggregate only if a specified condition is met. You can use this clause in running aggregates and in lookahead aggregates. The syntax of the Where clause follows:

<AggregateFunction>(<ValueExp>) Where(<Condition>)

The Condition parameter is a Boolean expression that indicates whether a given row is included in the aggregate calculation. For example, the following expression shows the average dollar amount of sales transactions. Payments and other types of transactions are not included in the calculation:

Ave( [trans.amount] ) Where( [trans.type] = "S" )

The WHERE clause is also useful for making sure null values are excluded from an aggregate, as shown in the following example:

Ave( [trans.amount] ) Where( Not IsNull( [trans.amount] ) )

The Condition expression can include any valid element of a value expression, including other aggregate functions. When you use the Where clause with a lookahead aggregate, the Condition parameter cannot include another lookahead aggregate.

For example, the following running aggregate counts the number of orders of more than $10,000. The Group By clause specifies a lookahead aggregate that is part of the Where clause of a running aggregate:

Count( ) Where( Sum( [items.extension] ) Group By( [orders.orderNo] ) > 10000 )

C h a p t e r 1 2 , W o r k i n g w i t h f r a m e s a n d c o n t r o l s 347

If the Count( ) function had been specified as a lookahead aggregate, this Where clause would not be valid. For more information about lookahead aggregates, see “Specifying lookahead aggregates,” earlier in this chapter.

Calculating values efficientlyActuate e.Report Designer Professional provides several techniques to do calculations. The control’s ValueExp property contains the information to calculate the control’s value. The calculation can be performed using Actuate Basic statements or function calls, method calls, or aggregate values computed over a set of data rows.

The performance impact of most calculations is minor. If your report uses a complex Actuate Basic function to calculate a value, converting the Actuate Basic function to call a C++ function might improve report generation performance. Computing aggregate values over a set of data rows might significantly increase report generation time. To calculate aggregate values efficiently, you must know about the following:

■ Computing aggregates

■ Replacing lookahead aggregate calculations

Computing aggregates

There are two types of aggregates, running aggregates and lookahead aggregates. Actuate e.Report Designer Professional can calculate running aggregates using the information from the database columns while the report is being built.

Lookahead aggregates require Actuate e.Report Designer Professional to summarize information from the database rows in memory before the report is built. You use a lookahead aggregate when you need to calculate the value of a control that depends on the values of data row columns that are not yet read.

For example, you need to calculate the value of a control that shows district sales as a percentage of total company sales. Actuate e.Report Designer Professional stores the values of the district sales until all the data rows are read and the total sales for the company are known. Lookahead aggregates increase report generation time because e.Report Designer Professional must go back and review the summarized data in memory to calculate the aggregate values after it has completely read all the data rows.

Replacing lookahead aggregate calculations

You can replace lookahead aggregates by calculating values on the database. Calculating lookahead aggregate values on the database results in better report generation performance. Doing calculations on the database increases the workload on the database server and might adversely affect the

348 D e v e l o p i n g A d v a n c e d e . R e p o r t s

performance of other enterprise applications. The performance objectives of your enterprise’s applications must be evaluated before deciding on your approach to calculating values.

To calculate values on the database, do the following:

■ In Query Editor, define a computed column to represent the calculated value.

A computed column is a field defined in a query that displays the result of an expression rather than stored data. The database engine recalculates the value each time it runs the query. You must add a GROUP BY clause to the SQL statement that makes the database columns needed to evaluate the expression available.

■ Execute SQL statements dynamically on the connection component to calculate the value.

In supported environments, you can alternately write a stored procedure to generate the value and return the result as an output parameter.

■ Create a reporting database that contains tables extracted from the transaction database.

On the reporting database, create special tables that contain the computed values needed for your reports.

Formatting data in a controlYou can format the data in one or more controls by selecting the controls and using the Format toolbar.

The Format toolbar supports setting the following:

■ Font and point size

■ Type face: bold, italic, or underline

■ Justification: left, center, or right; snap to grid

■ Color of the data, border, and background

■ Type of data

Alternatively, you can specify the type face for the labels or data in one or more controls by selecting the controls and using the keyboard:

Format toolbar

C h a p t e r 1 2 , W o r k i n g w i t h f r a m e s a n d c o n t r o l s 349

■ Ctrl+B toggles bold on and off

■ Ctrl+I toggles italic on and off

■ Ctrl+U toggles underline on and off

For date controls, short, medium, and long date and time formats are available. For currency controls, negative amounts, currency symbol, cents, and thousands are available. You can also specify the format for an integer, date/time, or currency control by choosing a format from the drop-down list for the component’s Format property.

You can also change the display format of text or numeric data in a control by using the Format$( ) function. To format a control, type the Format$( ) function in the control’s Format property. For more information about how to use Format$( ), see Actuate Basic Language Reference.

To edit a control in place, click the control twice. If Component Editor appears, wait a bit longer between the first and second clicks. Alternatively, click the control once and press F2.

When you edit a control in place, you can use the following keys:

■ Escape cancels the editing session and discards the changes.

■ Enter accepts the changes and ends the editing session.

■ Ctrl+Enter or Ctrl+J inserts a new line. The TextPlacement➛MultiLine property is set to True.

Formatting frames and controlsA frame provides several properties that you can use to change the frame’s appearance, such as BackgroundColor and Border. For a complete list of frame properties, refer to the entry for AcFrame in the Actuate Foundation Class Reference. The rest of this section describes how to accomplish some of the more common formatting tasks.

For information about how to set a property, see “Setting properties of components” in Chapter 4, “Using Design Editor.”

Moving or resizing a frameYou can use the mouse to change the size of a frame or to move the frame from place to place in the report design. There are some limits to moving or resizing a frame. If you nest a frame by placing it inside another frame, you can move the inner frame in any way you desire. The position of the outer frame, however, is determined when a user runs the report. Actuate e.Report Designer Professional positions the upper edge of each frame flush with the

350 D e v e l o p i n g A d v a n c e d e . R e p o r t s

bottom of the previous frame and puts the left edge at the left side of the flow. You cannot directly move or resize these edges of the frame.

Make sure the frame is not wider than the flow on the page where the frame displays or prints. If the frame is too wide, it is truncated.

For more information about moving and resizing frames, see “Arranging components” in Chapter 4, “Using Design Editor.”

Placing a shadow behind a frameYou can draw a shadow effect behind a frame and specify a color for the shadow. To specify a shadow, set the frame’s Shadow properties: Color, Height, and Width.

When you add a shadow behind a frame, you must also use a margin that is at least as large as the shadow. The shadow appears in the margin area. To set a frame margin, set the frame’s Shadow➛Margins properties.

Specifying page breaks for framesYou can make sure that a frame is the first or last on the page by setting the frame’s Pagination➛PageBreakBefore or Pagination➛PageBreakAfter property. If PageBreakBefore is True, the frame appears at the top of a new page. If PageBreakAfter is True, a new page begins immediately after the frame. These properties affect frames that are placed in Before, Content, or After slots only.

Drawing a border around a frame or controlActuate e.Report Designer Professional provides a variety of border styles to make it easier to outline frames, labels, and data controls. The advantage of using the border instead of drawing a rectangle around the item is that the border changes size when the control changes size. Reducing the number of controls also reduces the report generation time.

To specify a border for a frame or control, set the component’s Border properties: Color, Pen, and Width.

To remove a border, set the Border➛Pen property to NullLine.

Rounding the corners of a frame or controlYou can give a frame or rectangle control rounded corners by using the Windows Viewer Only➛Rounding properties. You must also set the Border➛Pen property to make the border visible, or rounding has no effect.

C h a p t e r 1 2 , W o r k i n g w i t h f r a m e s a n d c o n t r o l s 351

There are two Windows Viewer Only➛Rounding properties, X and Y, which you set to numeric values to specify how round you want the corners. The higher you set X and Y, the rounder the corners.

The corner is curved around an imaginary ellipse. X specifies the horizontal distance of the frame border from the center of the ellipse. Y specifies the vertical distance.

Truncating data in a single-line controlIf a single-line control is not wide enough to accommodate the data it contains, an overflow character appears or the data in the control truncates. You can truncate the data on the left or right and you can display an ellipsis to indicate that the data truncates. The following illustrations show how the settings of a currency control’s TextPlacement➛Clip and Ellipsis properties determine the appearance of the value $12.34 if the currency control is not wide enough to accommodate the value:

■ Display an overflow character.

■ Truncate the data on the left. Do not display an ellipsis.

■ Truncate the data on the left. Display an ellipsis.

■ Truncate the data on the right. Do not display an ellipsis.

■ Truncate the data on the right. Display an ellipsis.

Detail of frame cornerLabelImage

Frame with rounded corners

X

Y

352 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Displaying an overflow characterIn this illustration, the Clip property is set to ShowOverflowChar. ShowOverflowChar is the default value for a currency control, as it is the only setting that gives an unambiguous result. If you set the Clip property to ShowOverflowChar, the setting of Ellipsis has no effect.

Truncate data on the left, no ellipsisIn this illustration, the Clip property is set to ClipLeading and Ellipsis is set to False.

C h a p t e r 1 2 , W o r k i n g w i t h f r a m e s a n d c o n t r o l s 353

Truncate data on the left, display ellipsisIn this illustration, the Clip property setting is ClipLeading and the Ellipsis setting is True.

Truncate data on the right, no ellipsisIn this illustration, the Clip property is set to ClipTrailing and Ellipsis is set to False.

354 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Truncate data on the right, display ellipsisIn this illustration, the Clip property setting is ClipTrailing and the Ellipsis setting is True.

Truncating text in a single-line controlFor a single-line control that is not wide enough to accommodate the text it contains, you can specify whether to truncate the text in a word. The following illustrations show how the settings of a text control’s Clip and WordWrap properties determine the appearance of the text Sample Value if the text control is not wide enough to accommodate the text:

■ Do not truncate text within a word.

■ Truncate text within a word.

Do not truncate text within a wordIn this illustration, the Clip property is set to ClipTrailing and the WordWrap property is set to TextWordWrap. TextWordWrap is the default value.

C h a p t e r 1 2 , W o r k i n g w i t h f r a m e s a n d c o n t r o l s 355

Truncate text within a wordIn this illustration, the Clip property is set to ClipTrailing and the WordWrap property is set to TextCharacterWrap.

356 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Truncating or wrapping text in a multiline controlIf you want to allow the text, numbers, or other data in a control to appear on more than one line, do the following:

■ For controls other than a dynamic text control, make sure that the control is large enough to accommodate multiple lines. Unlike other controls, a dynamic text control increases in height dynamically to accommodate text of varying lengths.

■ Set the MultiLine property to True.

■ Set the WordWrap property to one of the following:■ TextWordWrap, which is the default value■ TextTruncateLines■ TextCharacterWrap

Formatting a frame or control dynamicallyYou might want to design a report that can print the same frame in several styles depending on conditions when the report runs. For example, you can switch a frame’s background color back and forth to print a gray background for every other row in an order.

This kind of dynamic formatting requires that you program a method using Actuate Basic to change the frame’s BackgroundColor property each time a new data row comes into the frame.

For an example of alternating background color, look at the Sales Detail example report in C:\Program Files\Actuate7\Erdpro\Examples\Detail\Detail.roi.

Another way to achieve flexible formatting is to place two different frames in a conditional section. When the report runs, the Factory evaluates a condition and selects one of the frames to include in the report. For more information

C h a p t e r 1 2 , W o r k i n g w i t h f r a m e s a n d c o n t r o l s 357

about conditional sections, see “About conditional sections” in Chapter 11, “Working with sections.”

Providing helpYou can provide two types of help for objects in your report:

■ Context-sensitive help

Context-sensitive help appears when the user selects the Help button or right-clicks and chooses Help from the context menu.

■ Balloon help

Balloon help appears when the user hovers the cursor over an object.

The viewer can display different text for context-sensitive and balloon help.

Providing context-sensitive helpYou can provide context-sensitive help or information for any of the objects on your report. Context-sensitive help appears only in the viewer. It does not appear in DHTML reports. The HelpText property does not support Unicode and cannot display some languages. Using the default setting, the viewer displays help for an object when the user takes one of the following actions:

■ Right-clicks on an object and chooses Help from the context menu.

■ Selects the help button. To select the help button, the user positions the help icon over the object for which they want help, then presses the right mouse button.

How to set context-sensitive help text

1 Double-click a component.

<Component name>—Component Editor—Properties appears.

2 Expand WindowsViewerOnly.

3 In HelpText, type text.

358 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Choose Close.

The following illustration shows how the string you typed in HelpText appears in the viewer.

Providing balloon helpBalloon help text appears when users hover a cursor over a control. The text disappears when the user presses a mouse button or moves the cursor. Balloon help supports Unicode, displaying all supported languages.

The text of balloon help can be any text you specify or a formatted value of a control. You should limit the length of the balloon text help because the text displays only for about five seconds.

You can provide balloon help text in the following ways:

■ Specify the help text to display by typing the string in the BalloonHelp property

■ Override the BalloonHelp( ) method

If you specify the text in BalloonHelp and then override the BalloonHelp( ) method, the return value of the method displays instead of the string of the property.

How to set balloon help text

1 Double-click a component.

<Component name>—Component Editor—Properties appears.

2 In BalloonHelp, type help text.

Status

In EvaluationClosedPending

Default Action

Status of sales Closed, Pending, or in Evaluation

Help

C h a p t e r 1 2 , W o r k i n g w i t h f r a m e s a n d c o n t r o l s 359

Choose Close.

The following illustration shows how the string you typed looks when users hover the cursor over the component.

Hiding frames and controlsUsing default values, frames and controls appear in a report when the report is printed or viewed. To hide a frame or control, in the Visibility properties group, set the ShowInDHTML, ShowInPDF, ShowInReportlet, ShowWhenPrinting, or ShowWhenViewing property to False.

Status

In EvaluationClosedPending

Status of sales

360 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Working with image controlsYou can place the following types of images in a report design:

■ BMP

■ GIF

■ JPEG

■ PCX

■ TGA

■ Certain types of TIFF

Actuate products do not support TIFF format on UNIX.

You can view all these types of images on the web in DHTML reports.

You can view JPEG images using the Actuate Viewer, the End User Desktop, the LRX for Microsoft Internet Explorer and Netscape, and Active X. You cannot view GIF images using these products.

How to place an image control in a report design

1 Choose Insert➛Image.

Image Browser appears, listing all images that exist in directories specified in all search paths. For information about search paths, see “Locating images,” later in this chapter.

2 To select an image, do one of the following:■ Select the file from the list■ Choose the More button to find the file■ Enter the file name in the File Name field

3 Choose Add Image.

4 Choose OK.

Setting the Embedded propertyYou must set an image control’s Embedded property to tell the Factory when to include the image in the report:

■ ImageDesignTime, when e.Report Designer Professional compiles the report object design (.rod) file

■ ImageFactoryTime, when the factory builds the report object instance (.roi) file

■ ImageViewTime, when the viewer or View/Print Server displays the ROI

C h a p t e r 1 2 , W o r k i n g w i t h f r a m e s a n d c o n t r o l s 361

The setting of the Embedded property also determines which directories e.Report Designer Professional searches when locating included images. For information about search paths, see “Locating images,” later in this chapter.

If you distribute a report to users through e-mail or through the Encyclopedia volume, set the image control’s Embedded property to ImageDesignTime or ImageFactoryTime. Otherwise, an X appears in place of the image.

Locating imagesActuate e.Report Designer Professional uses relative file paths to find images. This means that when you add an image control to a report design, you can specify the full path, a partial path, or just the file name. If the image is not found in the directory specified by the full path, Actuate e.Report Designer Professional searches other directories you specify.

The directories Actuate e.Report Designer Professional searches depend on the setting of the Embedded property.

Locating images with Embedded property set to ImageDesignTimeIf you set the Embedded property to ImageDesignTime, Actuate e.Report Designer Professional searches the following directories to locate images:

1 Directory that contains the referring report object design (.rod) file.

2 Design search path.

For information about the design search path, see “Choosing design search paths” in Chapter 5, “Customizing the design environment.”

3 Global search path.

For information about the global search path, see “Choosing design search paths” in Chapter 5, “Customizing the design environment.”

4 Configuration file search path.

For information about the configuration file search path, see “Specifying a search path” in Appendix A, “Using a configuration file.”

5 Current working directory.

If you save a report design to a directory other than the current working directory before the report is compiled and no design search path, global search path, or configuration file search path is set, e.Report Designer Professional might not be able to locate the images in the report. In this case, an X appears in place of each image.

362 D e v e l o p i n g A d v a n c e d e . R e p o r t s

If you use non-English characters in the directory name where you store an image, the image does not appear in the designer’s layout pane. To display the image in the report document, you must set the Embedded property to ImageDesignTime.

Locating images with Embedded property set to ImageFactoryTimeIf you set the Embedded property to ImageFactoryTime, the Factory searches the following directories to locate images:

1 Directory that contains the referring report object instance (.roi) file.

2 If the report object design (.rod) file is open, the design search path.

For information about the design search path, see “Choosing design search paths” in Chapter 5, “Customizing the design environment.”

3 The search path specified in the ExtendSearchPath function when the function is called at factory time.

For information about the ExtendSearchPath function, see Actuate Basic Language Reference.

4 Global search path.

For information about the global search path, see “Choosing design search paths” in Chapter 5, “Customizing the design environment.”

5 Configuration file search path.

For information about the configuration file search path, see “Specifying a search path” Appendix A, “Using a configuration file.”

Locating images with Embedded property set to ImageViewTimeIf you set the Embedded property to ImageViewTime, Actuate e.Report Designer Professional searches the following directories to locate images:

1 Directory that contains the referring report object instance (.roi) file.

2 The search path specified in the ExtendSearchPath function when the function is called at view time.

For information about the ExtendSearchPath function, see Actuate Basic Language Reference.

3 Global search path.

For information about the global search path, see “Choosing design search paths” in Chapter 5, “Customizing the design environment.”

C h a p t e r 1 2 , W o r k i n g w i t h f r a m e s a n d c o n t r o l s 363

4 Configuration file search path.

For information about the configuration file search path, see “Specifying a search path” Appendix A, “Using a configuration file.”

Creating smaller ROX files containing imagesUsers can view smaller report object executable (.rox) files more quickly than large ones. To decrease the size of ROX files that contain images, do the following:

■ Create images with the fewest colors needed.

■ Reference duplicated controls.

■ Store images in bitmap image controls.

Creating images with the fewest colors neededThe size of images in your report design depends on the number of colors in the palette used to create the image. Palettes are usually sized with 2, 16, 256, or more colors. To reduce the number of colors in the image, use a graphics tool such as Paint Shop Pro. In Paint Shop Pro, the Decrease Color Depth option on the Colors menu performs this function.

Referencing duplicated controlsDuplicated controls created by copying components increase the size of your report object executable (.rox) file. If you have the same bitmap image used in multiple places in your report design, publish the image to a library and create a reference to the published component when needed. For information about referencing components, see “Copying, subclassing, and referencing components,” in Chapter 4, “Using Design Editor.”

Storing images in bitmap image controlsUse bitmap image controls instead of OLE container controls to display images in reports viewed in a web browser or PDF viewer, because OLE controls are inactive in a web browser or PDF viewer.

To change an existing report design to use bitmap image controls, you should be familiar with publishing, referencing, and subclassing library components. For information about these features, see “Copying, subclassing, and referencing components,” in Chapter 4, “Using Design Editor,”and “Working with libraries.”

The following procedure describes one way to replace OLE container controls with bitmap image controls in a report design. Also, the procedure eliminates duplicated controls because the bitmap image controls are moved to a component library and then referenced by the report design.

364 D e v e l o p i n g A d v a n c e d e . R e p o r t s

How to replace OLE container controls with bitmap image controls

1 Create a library to contain the bitmap image controls.

2 Change the superclass for each OLE container control that displays images from AcOleContainerControl to AcImageControl:

1 Right-click the OLE container control. From the context menu, choose Properties.

2 In Component Editor, choose Class.

3 Under Super Class, type the following:

AcImageControl

4 Choose Close.

The space in structured storage reserved for the OLE container controls remains. In the next steps, you publish the image controls to the library you created in the previous steps. Then you use these image controls in the report design.

How to free space in structured storage

1 Publish each bitmap image control that was converted from an OLE container control to the library you just created.

1 Right-click the bitmap image control. From the context menu, choose Publish.

2 In Publish Class, type the name of the component library.

3 To publish the component, choose OK.

When you publish a component, e.Report Designer Professional creates a reference to the component in the library.

2 Use the bitmap image control in your report design.

1 In your report design, right-click the bitmap image control component. From the context menu, choose Delete.

2 From the component library, drag the bitmap image control to the report design.

3 Choose File➛Save.

Working with OLE controlsObject linking and embedding (OLE) helps you link information from other graphics or word processing or spreadsheet applications to your Actuate

C h a p t e r 1 2 , W o r k i n g w i t h f r a m e s a n d c o n t r o l s 365

report. Wordpad documents, Excel spreadsheets, Paintshop Pro, and Adobe PDF files are among those that can be placed in an Actuate report.

Storing images in OLE container controls requires more space than in image controls. OLE container controls take up more space because they are kept in OLE structured storage.

When you view the report in the Actuate Viewer, the application information is available to users in the form appropriate to that linked application. If you view the report in a web browser or PDF viewer, the OLE control is inactive.

How to design OLE capability into an Actuate report

1 In e.Report Designer Professional, choose Insert➛Object from the menu bar.

2 Click on your report design where you want to place the image.

3 In Class Name, type a new class name, or accept the default value. Choose OK.

4 In Insert Object, select the OLE image you want to insert. Choose OK.

New Image or another dialog might appear. If so, choose the appropriate options to finish preparing the image for your report.

366 D e v e l o p i n g A d v a n c e d e . R e p o r t s

The image appears in your report design.

.

OLE objects vary in the way they appear because of differences in applications. An image-oriented OLE object, for example, might create a thumbnail or graphic approximation of the real graphic image in the report design if the size of the container does not match that of the image.

After you run your report, the image is fully resolved in the report object instance (.roi) file.

Double-clicking an OLE object in the layout pane or in the viewer enables activate-in-place. For example, if the OLE object is a bitmap, double-clicking the OLE object displays the Microsoft Paint menu bar, tool box, and color box. You can then modify the bitmap using Paint.

For more information about working with OLE objects, see Chapter 17, “Using an object from another application,” and Chapter 18, “Programming an object from another application,” in Programming e.Reports.

Understanding report document searchingUnderstanding how searching works in e.Report Designer Professional helps you design reports to support more successful searches. A user can search on a control object in a report document if the control’s Searchable property value is SearchNoIndex or SearchWithIndex. SearchNoIndex is the default value. If the Searchable property value is NotSearchable, a report user cannot search on the component.

C h a p t e r 1 2 , W o r k i n g w i t h f r a m e s a n d c o n t r o l s 367

For information about how a report user searches for data in a report and how search uses fonts, see Chapter 5, “Working with an information object for Actuate Query,” in Using e.Reports.

About page headers and page footers in searchesA user can search controls in page headers and page footers. If the page header or page footer content changes from page to page, search uses values from the first page header or page footer. For example, in a dictionary, the alphabetical range that appears in the page header changes for each page. To support searching on page headers and page footers in older reports, you must rebuild the reports. Actuate e.Report Designer Professional introduced this functionality in Release 5.

For the report section, if the Pagination➛ShowHeaderOnFirst property value is NoHeaderOnFirst, which is the default setting, a page header does not appear for a report or group section unless it extends beyond a page break. Search uses the invisible page header for that section. The ShowFooterOnLast property determines the visibility of page footers. In searches, page headers and page footers behave similarly.

Hyperlinks in the search results exhibit the following behavior:

■ Hyperlinks link to only the first instance of the page header or page footer.

■ In reports that use page-level security, the hyperlink goes to the first instance of the page header or page footer to which the user has access.

■ If a search result links to the location of an invisible page header, the hyperlink goes to the beginning of the report or group section that contains the invisible page header.

■ If a search result links to the location of an invisible page footer, the hyperlink goes to the beginning of the report or group section that contains the invisible page footer.

368 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Using strategies to design searchable reports Users cannot see details of the report structure that show the containers for the controls. The designer can design the report to support searching. The search generates an error message when the user asks the search analysis to draw an impossible relationship across sections. For more information about report structures that support searching, see “About search analysis,” later in this chapter.

The following suggestions for report designs support more successful searching:

■ Use the Searching➛SearchTag property to identify one or more searchable controls from which users can retrieve data in a search. The SearchTag property is useful in complex reports where structures such as parallel and sequential sections can otherwise prevent successful searches. For more information about the SearchTag property, see “About SearchTag,” later in this chapter.

■ Place searchable controls that the user cannot combine in a search on different pages of the report document where the user is less likely try to combine them in a search. State in the report that a search can only include controls on the same page.

■ Include helpful information in the report to prevent users experiencing problems searching.

For example, include suggestions for searches or display a button to hyperlink to your own Search Help to alert users that they cannot include controls in two nearby sections. If two parallel sections appear next to each other on the same page of the report, they can appear to be conceptually related.

For experienced users, the report’s table of contents contains some visual clues about the structure of the report document. Depending on the level of experience of your report users, complex reports can require that you include additional report-specific Search Help.

About search analysisBefore a report document search begins, Actuate search analyzes the control objects the user adds to the search. Search analysis attempts to ensure that search results relate to each other. Using the default settings, the search analysis includes only those control objects that exist in related structures in the report design.

Report designers can use the SearchTag property to override the default search behavior settings. For more information about the SearchTag property, see “About SearchTag,” later in this chapter.

C h a p t e r 1 2 , W o r k i n g w i t h f r a m e s a n d c o n t r o l s 369

Search works with controls that Actuate search can organize into a flat, two-dimensional table, such as a spreadsheet. If the analysis of the controls that a user chooses for a search contains a hierarchy that Actuate search cannot organize into a flat, two-dimensional table, the search cannot continue.

If a user viewing a report on the web adds multiple controls to the search criteria, then chooses Search Now, the search analysis maps the path to each chosen control in the report structure. If the paths differ, the analysis compares the path differences to determine whether those differences show one-to-one or one-to-many relationships among the control objects. Actuate search can organize both one-to-one and one-to-many relationships into a flat, two-dimensional table. Search supports both.

The analysis of the paths results in one of the following outcomes:

■ If one-to-one or one-to-many relationships exist among the control objects, the search works and search results appear.

■ If the path differences indicate that the search results in many-to-many relationships in the search results or if the paths indicate ambiguity, an error message appears. Searches that result in many-to-many relationships or ambiguous relationships in the search results are not supported. Actuate search cannot organize those relationships into a flat, two-dimensional table.

When you use the Viewer to search reports, search analysis maps the paths to each control in the report structure when you add a control to a search. If the control does not match a supported relationship, an error message appears.

For a successful search, structurally related sections must contain all control objects the user adds to the search. Examples of relationships in report designs that support searching include:

■ A report has a one-to-one relationship with a report section it contains.

■ A report section has a one-to-one relationship with each of the components in its Before, After, PageHeader, and PageFooter slots.

■ A report section and a group section have one-to-many relationships with the components in a Content slot subordinate to them in the hierarchy.

■ A frame has a one-to-one relationship with each component contained in it, except when the controls are dynamically created. In that case, a frame can have a one-to-many relationship with the control. A search on a dynamic control matches only one instance of the control.

■ A parallel section and a sequential section have one-to-one relationships with each component of each Content slot subordinate to them in the hierarchy.

■ A control in an After slot that has only one value, such as an account total for a group section, has a one-to-one relationship with any other control in

370 D e v e l o p i n g A d v a n c e d e . R e p o r t s

the report in a Before, After, PageHeader, or PageFooter slot that also has only one value. The mapped paths to these slots in the report structure do not prevent adding these unique controls to a search.

Examples of relationships in report designs that prevent searching are:

■ Parallel and sequential report sections, which have many-to-many relationships among them. For a search, you cannot combine controls from two parallel or sequential sections, except the controls in Before, After, PageHeader, or PageFooter slots that have only one value.

■ Different Content slots, which have many-to-many relationships among them, if they contain multiple controls that have more than a single value.

■ Page decorations and data controls, which are not related. Page decorations appear outside the flow in the report design. Page decorations appear subordinate to the PageStyle and PageList slots in the structure pane. In a search, you cannot mix page decorations, such as a Date-Time control, with data controls. Choose only page decorations or only data controls for a search.

How to recognize relationships that support searches

To determine which structures in the report design result in one-to-one and one-to-many relationships, examine the report design’s structure pane. Expanding and collapsing the structure indicates the relationships among the components.

1 Open \Program Files\Actuate7\Erdpro\Examples\Detail\Detail.rod.

The Design Editor structure pane shows the report structure expanded to show the first level in the report with a plus sign (+) next to a Content—SalesDetailReport section, as shown in the following illustration.

The SalesDetailReport section has a one-to-one relationship with the SalesDetail report that contains it.

2 Expand SalesDetailReport to display the next level in the report.

The SalesDetailReport section has a one-to-one relationship with ReportTitle, ReportPageHeader, and ReportTotals, which are located in Before, PageHeader, and After slots.

C h a p t e r 1 2 , W o r k i n g w i t h f r a m e s a n d c o n t r o l s 371

A relationship that supports searching exists between components in the report structure that can expand from or collapse into another component.

3 Expand the OfficeGroup section.

The SalesDetailReport section has a one-to-many relationship with the contents of the OfficeGroup group section, because the group section contains many controls that can each have many values.

4 Close Detail.rod.

5 Open \Program Files\Actuate7\Erdpro\Examples\Detail\Forecast.rod.

6 Expand the ForecastReport sequential section.

372 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Each of the report sections the ForecastReport sequential section contains has a one-to-one relationship with the ForecastReport section. The ForecastApp report has a one-to-one relationship with the contents of the ForecastReport sequential report section.

The Issues, TopDeals, NegativeChanges, and PositiveChanges report sections and the Summary parallel section do not expand from or collapse into each other. Most of the components of these sections cannot combine for a search. You can combine controls that have only one value from the Before, After, PageHeader, or PageFooter slots in each of these report sections.

7 Expand the following sections as shown in the following illustration:■ Issues■ IssuesReportBodyContent■ Top Deals■ TopDealsReportContent

Analyzing Issues and TopDeals, you see that their components create many-to-many relationships among them. Actuate’s search does not support many-to-many relationships.

C h a p t e r 1 2 , W o r k i n g w i t h f r a m e s a n d c o n t r o l s 373

8 Close Forecast.rod.

About searches in reports with parallel and sequential sectionsThis section illustrates how the proximity of parallel and sequential report sections can lead a user to think that the searchable control objects should result in a successful search.

374 D e v e l o p i n g A d v a n c e d e . R e p o r t s

For example, you create a report of sales history that contains sequential sections including quarterly forecasts for Boston in one section and customers’ credit ranks sorted by salesreps in another section. The following illustration shows an example of such a report document.

In this report document, you can choose to combine the Sum from the Sales Forecast for Boston and the Number of customers for sales representative Diane Murphy. Both controls appear in After sections and each contains only one value.

Because the sequential sections appear close to each other on the same page of the report, a user viewing the DHTML report document might think that the information is related and choose controls from both sections for a search. When the user chooses Search Now, an error message appears and says that the search cannot execute with the current criteria.

To prevent the error message, the report designer can:

■ Change the design to avoid sequential or parallel sections. The user can add report sections to a search if there is a one-to-one or one-to-many relationship among them.

■ Change the page layout to display only controls from the Sales Forecast for Boston table or only controls from the Customer Name list on a single page.

■ Provide the suggestion to include only controls from the Sales Forecast for Boston table or only controls from the Customer Name list for a search.

You cannot search between these objects in different sequential sections

C h a p t e r 1 2 , W o r k i n g w i t h f r a m e s a n d c o n t r o l s 375

■ Change Searchable to NotSearchable for control objects in one sequential section.

■ Use SearchTag to identify controls to support searches that Actuate search does not otherwise support in complex reports. For more information about SearchTag , see “About SearchTag,” later in this chapter.

For information about how a report user searches for data in a report, see Chapter 5, “Working with an information object for Actuate Query,” in Using e.Reports.

About SearchAliasWhen a user adds a component to a search, the name’s default value is the component’s class name from the report design. You can change the component’s Searching➛SearchAlias property value to display a name different from the component’s class name in the list of searchable components.

The value you specify for SearchAlias does not appear in the list of searchable components for the following cases:

■ The SearchTag value appears in the user interface for a search instead of the SearchAlias value if you supply a value for the component’s SearchTag property and do not supply a value for SearchAlias.

■ If a user adds a component to the user interface for search and its SearchAlias value already appears as a name in the list, Actuate search adds a hyphen (-) and a number to the duplicate name. For example, if the control class name ForecastAmount appears in the list of searchable components and the user adds a control for which SearchAlias is ForecastAmount, the SearchAlias property value appears in the list as ForecastAmount-1.

About SearchTagBecause report designs can contain multiple instances of specific components, some components require the Searching➛SearchTag property to uniquely identify them in report document searches. The SearchTag value is a string for which the default value is an empty string. If you specify a SearchTag value for a report component, search always uses SearchTag to identify the component. If you do not specify a SearchTag value, search uses the report’s structure to determine which search results to retrieve.

For example, a frame can have multiple instances of a control called CalculatedControl. Method overrides set the value that each control displays when you generate the report. Searching on these controls displays values of any CalculatedControl in the frame unless SearchTag differs for each

376 D e v e l o p i n g A d v a n c e d e . R e p o r t s

CalculatedControl. The report designer must override SearchTag to provide search functionality for all CalculatedControl controls.

For another example, a user wants to search on instances of different classes that represent the same kind of data. Using SearchTag to identify the components supports such a search. In the following illustration, you set SearchTag to the same value for the OfficesOfficeIDControl integer controls to retrieve data from all of them if a user adds one to a search.

SearchTag can identify controls to support the following report document searches:

■ Retrieving data from one or more specific instances of a control in a report that contains multiple instances of the control

■ Retrieving data from controls that belong to different classes and displaying the data in the same search results group

■ Retrieving data from controls in different parallel and sequential sections of a report, which overrides the default search behavior setting

Using SearchTagIn Component Editor, you can specify a static value for SearchTag or set the value dynamically.

Recommendations for setting SearchTag are:

Set the SearchTag property to the same value for these integer controls to retrieve data from all in one search

C h a p t e r 1 2 , W o r k i n g w i t h f r a m e s a n d c o n t r o l s 377

■ Always set SearchTag for dynamically created components if they are searchable and might appear in multiple places or multiple times in the same context.

■ Use the same SearchTag value for controls of different classes only if you want a search to include them in the same search results group.

■ Do not set SearchTag for referenced controls because the scoped class name uniquely identifies these controls.

■ If you set the SearchTag value programmatically, you must set it before calling the parent class’ Start( ) method, Super::Start( ). You can set the value in the class’s Start( ) method or elsewhere in the report design before Start( ) executes.

To support using the Searching➛SearchTag property to identify a component in a search, set the component’s Searching➛Searchable property to SearchNoIndex or SearchWithIndex. For more information about Searchable, see “Understanding report document searching,” earlier in this chapter.

Creating an index to improve search performanceFor large report documents, you can improve search performance by creating indexes for the components users search most frequently. To create an index, set Searchable to SearchWithIndex for the component.

The index uses the DataValue attribute. To index an attribute other than DataValue, use the Actuate Basic function AddValueIndex. For more information about Actuate Basic functions, see Chapter 2, “Statements and functions,” in Actuate Basic Language Reference.

Adding an index increases the size of the report document and the report generation time. Report document size and generation time increase more with each additional index. For this reason, limit the number of indexes you create.

378 D e v e l o p i n g A d v a n c e d e . R e p o r t s

If Searchable is set to NotSearchable for a component, a report user cannot search on this component in the report. If Searchable is set to SearchNoIndex, a report user can search on this component in the report, but the Factory does not create an index for the component. SearchNoIndex is the default value.

For information about how a report user searches for data in a report, see Chapter 5, “Working with an information object for Actuate Query,” in Using e.Reports.

About the LinkExp propertyYou define a hyperlink in Actuate e.Report Designer Professional using an object’s LinkExp property. LinkExp contains an extended Universal Resource Locator (URL) that identifies the link’s destination report and defines the hyperlink’s target in the destination report. Because LinkExp is an expression property, you can build expressions that resolve to specific values at run time. The expressions can include references to columns in a data row.

Triggering hyperlinksUsers trigger hyperlinks when they take one of the following actions:

■ Click an object in a web browser.

■ Double-click an object in the standard viewer.

■ Single-click an object in the LRX.

■ Right-click an object, then choose Default Action from the context menu that appears.

When a user places the cursor over a hyperlink, the standard viewer displays the hyperlink’s text in the status line. If a control has help attached to it, the help text appears in the standard viewer’s status line when the user places the cursor over the control.

Understanding LinkExp syntax<Destination URL>[#<Search expression>][?<Dynamic report parameters>]

The destination URL element is required. You must specify elements in the order shown. Otherwise, the syntax is flexible. Depending on the purpose of the hyperlink, you can omit parts of an element, omit an entire element, or combine elements in various ways. The destination URL can be relative to the current environment, or it can be on the web. For more information about the destination URL, see “About destination URL syntax,” later in this chapter.

C h a p t e r 1 2 , W o r k i n g w i t h f r a m e s a n d c o n t r o l s 379

LinkExp is an expression property. You must enclose the link expression in quotation marks. If you reference specific columns in your report’s data rows, after the expression’s closing quotation mark, you concatenate the columns to the link expression string using an ampersand (&).

Specific column values must be enclosed in quotation marks, as well, if they contain spaces at the beginning, spaces at the end, literal quotes, or relational expressions.

To include a quotation mark (") in a link expression, you must use a set of two quotation marks.

The following LinkExp expression specifies a jump to the detailed information for the current office:

"FORECAST.ROI#ForecastDetail::OfficeTitleFrame::OfficeName="""& DataValue""""

DataValue is a column name. Actuate e.Report Designer Professional replaces DataValue with the actual value that the column contains when the user clicks on that column.

How to build a hyperlink expression

To create a simple link using the LinkExp expression property, enclose the link expression in quotation marks when you define it. If you include a reference to a specific column or value in a data row, concatenate the references using ampersands. To include literal double quotation marks in an expression, use two sets of double quotation marks.

The following example describes how to build a hyperlink expression:

1 Start with the desired end result, the link expression you want to build:

FORECAST.ROI#ForecastDetail::OfficeTitleFrame::OfficeName="<office>"

where <office> is the name of the office that you are searching for information about.

2 Enclose the link expression in quotes:

"FORECAST.ROI#ForecastDetail::OfficeTitleFrame::OfficeName="<office>""

<office> is a placeholder for a column name or data control.

3 To include the current value of DataValue in the hyperlink at run time, replace <office> with &DataValue, the current value of DataValue:

"FORECAST.ROI#ForecastDetail::OfficeTitleFrame::OfficeName="&DataValue""

When a user clicks on the office name that appears in the report at run time, Actuate e.Report Designer Professional replaces the placeholder with the current value of the column or data control. In this example, the column name is DataValue.

380 D e v e l o p i n g A d v a n c e d e . R e p o r t s

4 The value we are searching for might contain spaces at the beginning or end, quotation marks, or relational expressions. Therefore, we enclose the value in two sets of quotation marks:

"FORECAST.ROI#ForecastDetail::OfficeTitleFrame::OfficeName="""&DataValue""""

You now have a complete LinkExp expression.

The next sections describe the elements of the LinkExp syntax in more detail.

About destination URL syntaxThe destination URL indicates the location of the destination report. If you do not specify a destination URL, Actuate e.Report Designer Professional assumes the location is internal to the current report.

The destination URL syntax is:

[<protocol>:]//<path>/<report name>

■ <protocol> is the communication protocol to use to reach the destination report. Supported protocols are shown in the following table.

Protocol Description

file The destination is in a file system.

file://C:/Forecasts/Boston/Q3forecast.roi

http The destination is on the web or in an Encyclopedia volume. Goes to the browser.

http://Condor:8700/acweb/viewer/viewframeset.jsp?name=/Revenue/Q1revenue.roi

none Result depends on the environment. If the source and destination are on the same file system, the destination appears in Report Viewer. If the destination is on the web, the destination appears in the browser.The following example specifies a destination report in the folder Boston, one level up from the current report’s folder.

.../Boston/Forecast.roi

The following example specifies a destination report in the current folder.

Q3salesdetails.roi

other The destination appears in the browser. Other protocols include gopher and FTP.

C h a p t e r 1 2 , W o r k i n g w i t h f r a m e s a n d c o n t r o l s 381

<path>/<report name> is the destination report’s path name. Paths can be absolute or relative. You can specify a hyperlink to a report object instance (.roi) file, or to an report object executable (.rox) file or report object values (.rov) file if the hyperlink runs a dynamic report. The reports must be in the same environment, that is, in the same file system, on the same server, or on the web.

The iServer does not support relative paths for temporary reports. To support viewing a temporary report, use an absolute path for a LinkExp setting such as /Folder/Report.roi. Alternatively, the iServer supports tilde (~) syntax for an absolute path on the server, for example:

■ To display Myreport.roi in the current user’s home folder, set LinkExp to:

~/Myreport.roi

■ To display Myreport.roi in user1’s home folder, set LinkExp to:

~user1/Myreport.roi

For a report saved in the Encyclopedia volume, the following path indicates that the destination report is in the Boston folder, one level up from the current report’s folder:

"../Boston/Forecast.roi"

The following path indicates that the destination report is in the current report’s folder:

"Q3salesdetails.roi"

The following path indicates that the destination report is in the file system, in drive C’s Forecasts/Boston folder:

"file:C:/Forecasts/Boston/Q3forecast.roi"

If the current report is on the web, the following path indicates that the hyperlink is to a file on the web server:

"http://gumby:8700/acweb/viewer/viewframeset.jsp?name=/Revenue/Q1revenue.roi"

The following path indicates that the destination report is on the server:

"rotp://gumby/salesserver/forecast.rox"

About search expression syntaxThe search expression defines the hyperlink’s specific destination in the destination report. If you want the first page of the destination report to appear, specify only the report URL; no search expression is needed.

The search expression syntax is:

#<Class[::class...]> [[.<Variable>]=<Value>] [;<...>]

382 D e v e l o p i n g A d v a n c e d e . R e p o r t s

# indicates the beginning of the search expression.

<Class[::class...]> is the fully qualified name of a component class, such as a control class.

<Variable> is the class’ variable on which to search. If you do not specify a variable name, the search is on the default value for the specified class. If you do not specify a value for the class, the search looks for all instances of the class in the report.

<Value> is the value to search for. You must enclose the value to search for in quotation marks when the value falls into one of these categories:

■ Includes one or more spaces at the beginning or end

■ Contains relational expressions, such as <, >, =

■ Contains special characters, such as &, ;, @, #

For example, to search for the literal string “Gumby Special Pack”:

"#ForecastApp::ProductName=""Gumby Special Pack"""

To create a hyperlink to the ForecastApp report’s product name:

"#ForecastApp::ProductName=" & [values.ProdName]

The product name control is called ProductName, and ProdName’s ValueExp is [values.ProdName].

[;<...>] and other special characters are used to add more search criteria. You can specify several search criteria, separated by semicolons. Do not include spaces after the semicolon. Specifying multiple search criteria is like constructing a Boolean AND statement. Controls or data must match all the search criteria to be found by the hyperlink. If the controls or data do not match, the hyperlink does not work. If more than one match exists, the hyperlink goes to the first occurrence.

For example, to search for customers in the NorthEast sales region who have a credit ranking of A:

"#ForecastApp::CustInfo.Region=NE;CustInfo.CreditRank=A"

To search for the Positive Changes report in the Q3Sales report:

"Q3Sales.roi#RevenueDetails::PositiveChanges"

To search for any instance of customer ID in the current report:

"#ForecastApp::CustomerNameControl.CustomerID"

To search for customer ID 1562:

"#DetailReport::CustomerFrame::CustomerID=1562"

C h a p t e r 1 2 , W o r k i n g w i t h f r a m e s a n d c o n t r o l s 383

About dynamic report parameters syntaxYou can create a new dynamic report object instance (.roi) file from the current ROI, using LinkExp to pass specific parameters to the report object executable (.rox) or report object values (.rov) file. You can specify whether to overwrite any previous version of the report or create a new version of the report. You can also search in the dynamic report once it is created.

Creating dynamic reports is useful for short-run reports, those reports that are of interest right now but that are not needed long-term. For example, you can define a dynamic report to allow users to get the details for positive deals on a specific order number, based on the data in the current report. Users can examine the positive deals details, then throw the report away.

The dynamic report parameters syntax follows:

?<param>=<value>;<param>=<value>[;<...>]

? indicates the beginning of the dynamic report parameters section.

<Param> is the name of a parameter in the report or the keyword _ _overwrite.

<Value> is the parameter value. When the parameter is the keyword _ _overwrite, the parameter value is:

old | new

Old and new are case-sensitive; you must specify these values in lowercase. Old causes the generated report to overwrite any previous version. New creates a new version of the generated report. The default setting is to create a new version of the generated report.

[;<...>] and other special characters specify additional parameter value pairs, separated by semicolons.

For example, to examine the details for all customers in the Forecasts report who are located in the Northwest region and who have a credit ranking of C, use:

"FORECAST.ROX?Region=NW;CreditRank=C"

To examine the same details for an ROX that generates a report to display on the web, use:

"rotp://Gumby/ToySales/Forecasts/FORECAST.ROX?Region=NW;CreditRank=C"

To generate the details report and overwrite any existing version of the report, use:

"FORECAST.ROX?Region=NW;CreditRank=C; _ _overwrite=old"

384 D e v e l o p i n g A d v a n c e d e . R e p o r t s

How to create a hyperlink with dynamic report parameters

The following procedure shows how to create a hyperlink that creates a dynamic report. The example is the detail report, available in your \Program Files\Actuate7\Erdpro\Examples\Detail directory. Suppose you want to run a dynamic report showing all the customers who have a credit rank of “C”:

1 Start two e.Report Designer Professional instances, one to display the source report’s report object design (.rod) file and one to display the destination report’s ROD.

2 Open Detail.rod for the destination report.

3 Choose Tools➛Parameters.

4 In Parameter Editor, select the parameter, such as customers_creditrank, with which you want to create the dynamic report.

5 Choose Modify.

Parameter Properties—General appears.

C h a p t e r 1 2 , W o r k i n g w i t h f r a m e s a n d c o n t r o l s 385

6 In Parameter Properties—General:

1 Note the parameter name.

2 Close the destination report ROD.

7 Open the source report. Add a label in which to create the hyperlink.

8 Double-click the object from which you want to link.

9 In Properties, scroll down to LinkExp, and type the following hyperlink expression:

"rotp://<Server>/<Folder>/<RPT>.ROX?<Parameter_name>=<Val>"

Where:■ rotp:// specifies the protocol.■ <Server> is the name of the destination report’s iServer.■ <Folder> is the folder containing the destination report.■ <RPT> is the report name.■ <Parameter_name> is the name of the parameter, taken from the

Parameter Properties—General window.■ <Val> is the parameter value.

Parameter name

386 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Assuming that this example’s report is on the Mustique server, the hyperlink expression is as follows:

"rotp://Mustique/Detail/DETAIL.ROX?customers_creditrank = C"

Calling JavaScript functions with LinkExpYou can call JavaScript functions with the LinkExp property. The syntax is as follows:

javascript:function(parameters)

For example,

javascript:history.back()

The parentheses are passed to the web browser. If the function name or the parameters contain parentheses or certain other characters, however, these characters are escaped. To pass these characters to a function, you must unescape them.

Defining universal hyperlinks Defining universal hyperlinks, or hyperlinks that work in a variety of environments, supports viewing reports in various environments. Suppose users run reports on a variety of systems and view reports on the web, as well as locally and in the Navigator. For example, reports can be in the file system or an encyclopedia folder, with users viewing them in the standard viewer, and reports can be in a directory published by a web server, with users viewing them in the LRX.

To define universal hyperlinks do the following:

■ Ensure that the source and destination reports are in the same environment: they are both in the file system, on an Encyclopedia volume, or on a web server.

■ Ensure that the reports’ locations are fixed and are simple. They should be in the same directory or folder or in the same directory or folder structure.

■ Use a consistent directory or folder structure for each environment. For example, put all the forecast reports in a structure similar to Forecasts\Region\Q2.

■ Use relative links to locate the destination report. You should be able to specify locations such as \Q3\Report.roi to reach the destination report.

C h a p t e r 1 2 , W o r k i n g w i t h f r a m e s a n d c o n t r o l s 387

Designing a hyperlink URLYou can design an Actuate Active Portal URL that links to a report, where the URL is external to the report.

The syntax for this Actuate Active Portal hyperlink URL is:

http://<app server>:<port>/acweb/<path><page>.jsp?<parameter=value>

where

■ <app server> is the name of the machine running the application server or JSP/servlet engine.

■ <port> is the port on which you access the application server or JSP/servlet engine.

■ acweb is the default context root for accessing the Actuate Active Portal JSPs.

■ <path> is the directory containing the JSP to invoke.

■ <page> is the name of the JSP.

■ <parameter=value> specifies the parameters and values that the JSP requires.

For example, to view a report document, Actuate Active Portal uses a URL with the following format:

http://druid:8700/acweb/viewer/viewframeset.jsp?name=/Test%20Folder/condtnl2.roi&format=DHTML

where

■ viewer is the directory containing JSPs that provide viewer functionality.

■ viewframeset.jsp is the JSP that displays the report with the navigation bar.

■ name=/Test%20Folder/condtnl2.roi specifies the path and name of the report object instance (.roi) file.

■ format=DHTML specifies the viewing format.

To be included in a URL, special characters in the search criteria, such as spaces, must be encoded. For example, the encoding for a space is %20. Encoding is not necessary if you use the LinkExp syntax to link among reports and report locations. For more information about LinkExp syntax, see “Understanding LinkExp syntax,” earlier in this chapter.

For more information about Actuate Active Portal, see Part 1, “Customizing Actuate Active Portal” in Creating Custom Web Applications using Actuate Active Portal.

388 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Analyzing report data with e.AnalysisWhen you analyze report data with e.Analysis, e.Analysis determines whether a control is a Dimension or a Measure. The default value for the following controls is type Dimension:

■ Text control

■ Dynamic text control

■ Label control

■ Date or time control

The default value for the following controls is type Measure:

■ Integer control

■ Floating point control

■ Currency control

The default value for AnalysisType is AnalyzeAsAutomatic, which analyzes a search result as type Dimension or Measure based on the control’s type. Launching e.Analysis requires that at least one control’s type is Dimension in the search results. A control of type Dimension appears as a category in the e.Analysis view. For more information about using e.Analysis to analyze report data, see Using e.Analysis.

You can change the default behavior by setting a control’s AnalysisType property to AnalyzeAsDimension or AnalyzeAsMeasure. To support launching e.Analysis using search results that contain only numeric values, you must set at least one numeric control’s AnalysisType property to AnalyzeAsDimension.

For example, if an Integer control contains department_number using the default setting AnalyzeAsAutomatic, e.Analysis analyzes this value as a Measure. If the search result includes department_number and only Measures, e.Analysis does not analyze the search results. If you set the Integer control’s AnalysisType property to AnalyzeAsDimension, e.Analysis uses department_number as a Dimension to analyze the search results.

C h a p t e r 1 3 , W o r k i n g w i t h a d y n a m i c t e x t c o n t r o l 389

C h a p t e r

13Chapter 13Working with a dynamic

text controlThis chapter contains the following topics:

■ About dynamic text controls

■ Understanding how Actuate generates content in a dynamic text control

■ Understanding the effects of Actuate’s generation techniques

■ Placing a dynamic text control in a report design

■ Repositioning and resizing controls in a frame

■ Adjusting text formats for different rendering environments

■ Controlling how a frame and its contents fit in multiple pages

■ Solving common output problems

390 D e v e l o p i n g A d v a n c e d e . R e p o r t s

About dynamic text controlsThe dynamic text control is a data control you use to display data that contains multiple style formats or a large and variable amount of text. For example, a dynamic text control can display text with paragraph styles such as bulleted lists and numbered lists, and character formats such as bold and italic.

A dynamic text control adjusts its size automatically to accommodate varying amounts of data. It can even span multiple pages for very large amounts of text. The frame containing the dynamic text control also adjusts its size and contents automatically to accommodate the control.

Reviewing examples of dynamic text controls in reportsThe following list contains some examples of reports where dynamic text controls are suitable:

■ Investment reports that contain formatted narratives which look more like the contents of a presentation than a standard report

■ Reports that include memos ranging from zero lines to any number of lines

■ Address labels, where address fields can contain a variable number of lines

■ Letters that are constructed from a number of formatted boilerplate paragraphs, where each paragraph is stored in a database row

The following illustrations show two reports. The first report uses text controls for the contact name, address 1, address 2 and customer notes. There are blank lines where a contact name or address 2 information is missing.

The second report uses dynamic text controls for the contact name, address 1, address 2, and customer notes. Notice that there are no blank lines for missing contact names or address 2 information. Notice, too, that the colored background behind the customer notes adjusts to the size of the text block.

C h a p t e r 1 3 , W o r k i n g w i t h a d y n a m i c t e x t c o n t r o l 391

Understanding supported text formatsThe dynamic text control supports the following three text formats:

Customers in California

ComputerWaresLeslie Patterson2654 Valley Drive

Santa Clara, CA 95050

Comtrex SystemsPeter Banks999 Baker WaySuite 100San Mateo, CA 94404

Datatron Corp

46372 Oakwood St.Suite 250

Wants to settle accounts quarterly instead ofmonthly. Per agreement on March 25, 2002, wewill not charge interest. The alternate contact person

Send SKU B100 on the first of every month andSKU C2890 on the first of every quarter. Theyanticipate increasing volume of orders in Q4.

is Tony Myers.

Customer since 1995. Purchases have increasedevery year. Notify Ms. Patterson of special deals.

Palo Alto, CA 94306

page 1

Contact name

Address 1

Address 2

CustomerNotes

Report 1: Uses text controls only

Customers in California

ComputerWaresLeslie Patterson2654 Valley DriveSanta Clara, CA 95050

Comtrex SystemsPeter Banks999 Baker WaySuite 100San Mateo, CA 94404

Datatron Corp46372 Oakwood St.Suite 250

Della Systems Co.800 Washington St.San Jose, CA 95118

Wants to settle accounts quarterly instead ofmonthly. Per agreement on March 25, 2002, wewill not charge interest. The alternate contact person

Send SKU B100 on the first of every month andSKU C2890 on the first of every quarter. Theyanticipate increasing volume of orders in Q4.

is Tony Myers.

Customer since 1995. Purchases have increasedevery year. Notify Ms. Patterson of special deals.

Palo Alto, CA 94306

New customer. Call next week.

page 1

Report 2: Contains dynamic text controls

CustomerNotes

Contact name

Address 1

Address 2

392 D e v e l o p i n g A d v a n c e d e . R e p o r t s

■ Plain text

Plain text has no format tags, but it can contain ASCII control codes for specifying carriage returns, line feeds, tabs, and so on. The dynamic text control supports the “CR,” “LF,” and “TAB” control codes. All others are ignored.

■ HTML

The dynamic text control supports a subset of the HTML 4 standard. For a list of supported tags, see Appendix B, “Working with RTF and HTML tags in a dynamic text control.” Actuate ignores tags it does not recognize.

■ RTF

The dynamic text control supports a subset of the RTF 1.6 standard. For a list of supported RTF tags, see Appendix B, “Working with RTF and HTML tags in a dynamic text control.” Actuate displays a warning at run time when it encounters RTF tags it cannot handle. It displays in the generated report the unrecognized RTF tags as literal text and truncates it at 4000 characters.

A single dynamic text control supports only one text format. A dynamic text control cannot, for example, support both HTML and RTF formats.

Comparing a dynamic text control and a text controlUnlike a dynamic text control, a text control cannot display highly formatted text and its size is set at design time. You can resize it dynamically only by overriding methods.

Because Actuate parses every tag or control code in formatted text and has to compute dynamic frame content layouts, a report that uses dynamic text controls takes longer to generate than a report that does not use them. Use the dynamic text control only if the data to display from the data row contains multiple style formats or a variable amount of text. Otherwise, use the text control.

Understanding how Actuate generates content in a dynamic text control

When Actuate generates a report, the resulting document is device independent; the report is not designed for a particular screen resolution or printer. A report, however, appears or prints differently, depending on the

C h a p t e r 1 3 , W o r k i n g w i t h a d y n a m i c t e x t c o n t r o l 393

rendering environment used to display or print the report. For example, you notice slight differences in the displayed output, depending on the zoom magnification you use to view a report. The rendering environment’s scaling mechanism might condense text more at, for example, 50% than at 120%, and might display more blank space between text and the edge of the page margin.

You might also notice differences in the output, depending on whether a report appears in the DHTML viewer or Acrobat viewer. Similarly, you notice differences in the printed output, depending on the printer you use.

The differences in output can be more pronounced when the original fonts you specify for the report design are not available on the computer on which the report appears or prints. In this case, font substitution occurs and this can lead to significant discrepancies. For more information about font issues, see “Understanding font issues,” in Chapter 16, “Designing a page layout.”

With the addition of dynamic text controls, where lines of text vary in length and text can contain different fonts and font styles, the potential for display and printing differences is even greater. Actuate’s generation process takes these issues into consideration, and attempts to produce consistent output for all its supported rendering environments, which include: Actuate Viewer, DHTML viewer, client-side printing on Windows, server-side printing on Windows and UNIX, and export to PDF.

To achieve this goal, Actuate applies the following techniques when it generates content in a dynamic text control. Understanding these techniques is useful if you want to change some of the default settings to optimize output for a particular rendering environment.

Fixed control width at design time

The width of a dynamic text control is fixed at design time. Actuate does not change the width of the control at run time.

Dynamic control height at run time

The height of a dynamic text control expands at run time to accommodate text of varying length. Because Actuate computes and sets the size of dynamic text controls at run time, the pagination is also set at run time. When you view or print the generated report, the contents of pages are constant regardless of the rendering environment.

Consistent line breaks within text

Line breaks always occur in the same place within text in a dynamic text control, regardless of rendering environment. Actuate determines where to break a line by calculating the available line width for text. To ensure that text does not overflow the width of the control when rendered slightly larger in some environments, Actuate builds in a padded amount of white space when

394 D e v e l o p i n g A d v a n c e d e . R e p o r t s

calculating the available line width. The default padding value is 7.5% of the width of the control. For example, if the control is 200 pt wide, the available line width for text is approximately 186 pt (200/1.075).

You can change the padding value to optimize the available line width for a particular rendering environment. For more information on how to do this, see “Adjusting the space on the right of the text” later in this chapter.

Consistent line height within text

Actuate calculates the line height, at run time, from the font. The following illustration shows how Actuate computes the line height.

For information on where Actuate gets the font information it needs to generate the contents of a dynamic text control, see “How Actuate gets font information” in Chapter 16, “Designing a page layout.”

Understanding the effects of Actuate’s generation techniques

The techniques described in the previous section ensure that the size of generated dynamic text controls, and the pagination of the report, as a whole, are the same for all rendering environments. If line breaks occurred at different places depending on the rendering environment, you might get unpredictable results, as shown in the following illustration.

PadThis is the available line width for text

This value can be adjusted to change the available line width

The shaded area is the control’s margin, if set

Line height calculation line height

Please note that ourSPECIAL PRICES areonly good to the end of March.

Please note that our SPECIALPRICES are only good to the end of March

Output 1 Output 2

Output with inconsistent line breaks

C h a p t e r 1 3 , W o r k i n g w i t h a d y n a m i c t e x t c o n t r o l 395

In the previous example, the different line breaks cause the word SPECIAL to appear on different lines. Because that word is in a larger font, the height of the first line in the second example has increased. This, in turn, increases the total height required for the text, resulting in the last line’s truncation.

Differing line breaks might also cause extra blank lines to appear when the size of text changes in different rendering environments. The following examples illustrate this.

Using Actuate’s technique of fixed line breaks, the results are as shown in the following illustration.

In Output 2 in the previous illustration, the extra space appears to the right of the text, where the discrepancy is more acceptable.

Placing a dynamic text control in a report designYou place a dynamic text control in a report design the same way you place other controls. Because a dynamic text control is a data control that typically uses data from a data row, you almost always place it in a frame.

You can place a dynamic text control directly onto a page or subpage, and assign a literal value with embedded HTML tags, ASCII codes, or RTF tags to format a string. This strategy, however, is not advisable because dynamic text controls take more generation time than other controls. Unless the report absolutely needs static text that contains formatted words, you should use a label control instead to display a literal value.

Part WDG24637 can only be usedwith the following parts: FL667W,FL668W, FL700R, FL701R, FL702RFL800S, FL805S, FL810S, FL100A,

Part WDG24637 can only be used withthe following parts: FL667W, FL668W,FL700R, FL701R, FL702R, FL800S,FL805S, FL810S, FL100A, FL101A

FL101A

Output 1 Output 2

Output with inconsistent line breaks

Part WDG24637 can only be usedwith the following parts: FL667W,FL668W, FL700R, FL701R, FL702R,FL800S, FL805S, FL810S, FL100A,

Part WDG24637 can only be used with the following parts: FL667W, FL668W, FL700R, FL701R, FL702R, FL800S, FL805S, FL810S, FL100A,

FL101A FL101A

Output 1 Output 2

Actuate’s output with consistent line breaks

396 D e v e l o p i n g A d v a n c e d e . R e p o r t s

How to place a dynamic text control in a report design

1 Drag a dynamic text control and drop it onto a frame.

Component Properties appears.

2 Select a value for TextFormat.■ Select TextFormatPlain, the default value, if the text to display is in

ASCII format.■ Select TextFormatHTML if the text to display is in HTML format.■ Select TextFormatRTF if the text to display is in RTF format.

If the TextFormat setting does not correspond to the format of the text, the results probably will not be what you expect. For example, if the TextFormat setting is TextFormatPlain but the text is in HTML or RTF format, the text in the generated report displays all the HTML tags or RTF tags as literal text.

3 Specify a value for ValueExp.

The value you specify is typically a data row variable. You can use Expression Builder to select a data row variable or create a value expression.

4 Choose OK.

You can now customize the properties and behavior of the dynamic text control, if desired.

Repositioning and resizing controls in a frameA report design often includes multiple controls in a frame. Without dynamic text controls, the sizes of frames and controls and their positions relative to one another are set at design time. The layout of content in the generated report reflects the layout in the report design. If you place two controls a quarter inch apart in the report design, the contents of the controls appear a quarter inch apart in the generated report.

Because of their dynamic sizing behavior, dynamic text controls, however, change the way controls in a frame are sized and positioned. As mentioned earlier, the height of a dynamic text control changes to accommodate a single line or multiple lines. Similarly, the frame grows as needed to contain the dynamic text control. Other controls in the frame are repositioned relative to the dynamic text control.

C h a p t e r 1 3 , W o r k i n g w i t h a d y n a m i c t e x t c o n t r o l 397

The following section explains the mechanism that Actuate uses to resize and reposition controls in frames during report generation. Understanding the default behavior will help you decide how and where to place controls, when to change the default size and position property values, and when to override methods.

Understanding how Actuate resizes and repositions controlsThere are countless ways to position dynamic text controls and other controls in a frame. Actuate attempts to resize and reposition them in an intuitive manner when generating the report. The following are key default principles:

■ A dynamic text control remains the same height or grows. It does not shrink. You can, however, set the CanReduceHeight property to change this default value.

■ The container frame remains the same height or grows with the dynamic text control. The distance between the bottom of the lowest control and the bottom of the frame is maintained. You can set the CanReduceHeight property to shrink a frame if its contents shrink.

■ A dynamic text control can only grow vertically. Its width is fixed by its Width property. You cannot change this behavior. The dynamic text control’s Height property value does not fix the control’s final height; its main purpose is to set a relative size that Actuate uses to compute the size and positions of other controls.

■ Controls can only move down. You can set the CanMoveUp property to change this behavior.

■ Only lines and rectangles grow automatically when a dynamic text control grows. Other controls stay the same size unless you change their VerticalSize property to VerticalSizeRelative or VerticalSizeFrameRelative.

The following sections describe how Actuate resizes and repositions controls.

When a control is placed above or below a dynamic text control

In this case, there are no changes to the size of the control. A control above a dynamic text control does not move. A control below a dynamic text control moves to accommodate changes in the height of the dynamic text control. Remember, the width of the dynamic text control is fixed at design time; the dynamic text control only grows vertically.

398 D e v e l o p i n g A d v a n c e d e . R e p o r t s

In the following illustration, B and C are dynamic text controls, A and D are other controls. Control A doesn’t move. Control D does.

When a control is placed to the right or left of a dynamic text control

In this case, the size of the control grows if all the following conditions are met:

■ Its VerticalSize property is set to VerticalSizeRelative or VerticalSizeFrameRelative. The default setting for lines and rectangles is VerticalSizeRelative. The default setting for other controls is VerticalSizeFixed.

■ Its top is at or above the top of the dynamic text control.

■ Its bottom is at or below the bottom of the dynamic text control.

■ The dynamic text control grows.

Whether a control moves or not depends on where its top and bottom line up relative to the dynamic text control in the report design.

■ If the top of the control is located above the center of the dynamic text control, it does not move when the dynamic text control grows.

■ If the top of the control is located at or below the center of the dynamic text control, it moves relative to the bottom of the dynamic text control when the latter grows.

In the following illustration, A is a dynamic text control, B and F are lines, and C, D, E and G are other controls.

■ Line B does not grow because its top is below the top of the dynamic text control, and its bottom is above the bottom of the dynamic text control

■ Control C does not move because its top is located above the center of the dynamic text control

Frame Frame

A A

B BC C

D

D

Design Output

C h a p t e r 1 3 , W o r k i n g w i t h a d y n a m i c t e x t c o n t r o l 399

■ Control D does not move because its top is located above the center of the dynamic text control

■ Control E moves down because its top is below the center of the dynamic text control

■ Line F grows because its top and bottom are aligned with the top and bottom of the dynamic text control

■ Control G does not grow because its VerticalSize property’s default value is VerticalSizeFixed

Changing the default sizing and positioning of controlsYou can change Actuate’s default sizing and positioning actions for individual controls. To do so, set values for the Dynamic Size & Position properties for each control you want to manipulate. In this group of properties, the properties you are likely to work with the most are VerticalPosition and VerticalSize.

As its name suggests, the VerticalPosition property lets you specify how to position a control vertically when a dynamic text control increases in height and changes position. You can reposition a control relative to the dynamic text control (to either its top or bottom) or relative to the frame (to either its top or bottom).

Frame

A

Design Output

F Top

Center

Frame

Bottom

AB C

D

E

FG

C

D

G

E

B

400 D e v e l o p i n g A d v a n c e d e . R e p o r t s

The VerticalSize property lets you specify how a control is resized, if at all, when a dynamic text control increases in height. You can specify the following:

■ The control maintains its original height

■ The control increases in height to match the new size of the dynamic text control

■ The control increases in height relative to the frame’s new size.

For detailed descriptions of each property, see the Actuate Foundation Class Reference.

The following sections describe the common tasks that entail changing a control’s dynamic size and position properties.

Shrinking a dynamic text controlThe default resizing behavior for a dynamic text control is to stay the same size or grow. You can reduce it to ‘shrink-wrap’ the text if you do not want to display any extra space below the text. Extra space appears if the size of the control in the report design is larger than the actual amount of text. Another reason to shrink a dynamic text control is to make it “disappear” if there is no text.

To shrink a dynamic text control, set its CanReduceHeight property to True. If you want to set a limit to how small the control gets, specify a value for MinimumHeight as well. To hide the control when there is no text, leave MinimumHeight set to the default value, zero.

If the control’s initial height—specified by its Height property—is smaller than MinimumHeight, the control will not get taller. Instead, the behavior will be as if MinimumHeight is set to the initial height.

Moving a control up when a dynamic text control above it shrinksWhen a dynamic text control shrinks from its initial size, there is an increased gap between it and the control directly below it. To maintain a constant space between the two controls, set the lower control’s CanMoveUp property to True.

To decrease the frame’s height so there is no extra space below the lower control, set the frame’s CanReduceHeight property to True.

C h a p t e r 1 3 , W o r k i n g w i t h a d y n a m i c t e x t c o n t r o l 401

Setting the maximum height of a dynamic text controlThe default behavior for a dynamic text control is to expand to contain all the data. You can set a limit to how large it gets by setting a value for MaximumHeight. This setting is useful if you do not want a dynamic text control to expand to multiple pages, or if you want to keep its bottom aligned with another control, or group of controls, of a fixed size.

If the control’s initial height—specified by the height property—is greater than MaximumHeight, the control will not shrink. Instead, the behavior will be as if MaximumHeight is set to the initial height.

Resizing a control to match the size of a dynamic text controlWhen a dynamic text control resizes, the default behavior for only lines and rectangles is to resize automatically. You can specify that other controls increase in size to match the size of the dynamic text control. To do so:

1 Place the control in the layout pane with the following characteristics:■ Its top is at or above the top of the dynamic text control■ Its bottom is at or below the bottom of the dynamic text control

2 Set the control’s VerticalSize property to VerticalSizeRelative.

3 Set the control’s IsFrameDecoration property to True. This setting is required to allow the control to split across multiple pages.

Frame

A

B

Design Output 1

Frame

A

B

Frame

A

B

B’s CanMoveUp = False (default value)

B’s CanMoveUp = TrueFrame’s CanReduceHeight = True

Output 2

402 D e v e l o p i n g A d v a n c e d e . R e p o r t s

The following illustration shows how a control increases in height to match the height of the dynamic text control. A is the dynamic text control.

For a comparison of how Actuate resizes a control when you set its VerticalSize property to the different values, see the illustration in the next section.

Resizing a control relative to the size of the frameYou can specify that a control should increase in height relative to the frame’s height increase, or relative to a dynamic text control’s height increase. To accomplish the former:

1 Set the control’s VerticalSize property to VerticalSizeFrameRelative.

If the frame’s height increases, the control’s height increases by the same amount. The distance between the top of the control and the top of the frame is constant, as is the distance between the bottom of the control and the bottom of the frame.

2 Set the control’s IsFrameDecoration property to True. This setting is required to allow the control to split across multiple pages.

The following illustrations compare the different results when the VerticalSize property is set to each of the three values. A, B, and C are dynamic text controls. D is another control.

Frame

Design

A B

Output

A’s and B’s tops and bottoms are aligned.B’s VerticalSize = VerticalSizeRelative

Frame

A B

C h a p t e r 1 3 , W o r k i n g w i t h a d y n a m i c t e x t c o n t r o l 403

Positioning a control relative to the frameThe default setting for a control’s position is to adjust it relative to the position of a dynamic text control, as described in “Understanding how Actuate resizes and repositions controls” earlier in this chapter. You can, however, position a control relative to the frame instead. To do so, set the control’s VerticalPosition property to one of the following values:

Frame

A

B

Design

D’s VerticalSize = VerticalSizeRelative

Output 2

Frame

C D

Output 3

D’s VerticalSize = VerticalSizeFrameRelative

Frame

h1

h2

Output 1

D’s VerticalSize = VerticalSizeFixed

Frame

SizeFixed

A

B

C D

A

B

C D

A

B

C

D

SizeRelative

h2

h1

SizeFrameRelative

D’s size does not change D’s size increases relative to dynamic text control C

D’s size increases relative to the frame. Its top and bottom maintain the same distance from the frame’s top and bottom.

C’s and D’s tops and bottoms are aligned

404 D e v e l o p i n g A d v a n c e d e . R e p o r t s

■ VerticalPositionFrameTop

The control’s vertical position is fixed. The control will not move.

■ VerticalPositionFrameBottom

The control will be repositioned vertically to keep the distance between its bottom and the bottom of the frame constant.

The following illustrations compare the different results when the VerticalPosition property is set to each of the five values.

Frame

A

B

Design

D and E VerticalPosition = VerticalPositionFrameTop

Output 2

Frame

C

D

E

A

B

C

D

E

FrameTop

FrameTop

Output 3

D and E VerticalPosition = VerticalPositionFrameBottom

Frame

A

B

C

D

E

FrameBottom

FrameBottom

x x

y

y

Output 4

D and E VerticalPosition = VerticalPositionTop

Frame

A

B

C

D

E

Top

Top

Output 5

D and E VerticalPosition = VerticalPositionBottom

Frame

A

B

C

D

E

Bottom

Bottom

Output 1

D and E VerticalPosition = VerticalPositionDefault

Frame

A

B

C

D

E

Default

Default

C h a p t e r 1 3 , W o r k i n g w i t h a d y n a m i c t e x t c o n t r o l 405

Using dynamic text controls in nested framesActuate uses the same positioning and sizing principles for nested frames as it does for controls in a frame. If a nested frame contains a dynamic text control and it is resized to accommodate the control, the nested frame’s parent frame is also resized. In this case, the resizing and repositioning behavior of the parent frame is the same as if the nested frame is a dynamic text control. You can, therefore, manipulate the nested frame the same way you can a dynamic text control. For example, you can shrink it, set its minimum and maximum height, and so on.

If a nested frame does not contain a dynamic text control, it is treated like a normal control.

The following illustrations show examples of how Actuate resizes and repositions controls, nested frames, and parent frames. A and B are dynamic text controls, C and D are other controls.

Frame 1

A

Design

Frame 2

B

C

Frame 1

Output 1: Default property values used in design

Frame 2

C

AB

406 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Using dynamic text controls in different types of framesYou can place a frame in the following slots of a section component:

■ Content

■ Before

■ After

■ PageHeader

■ PageFooter

The way a frame is resized to accommodate dynamic text controls is different, depending on where the frame is placed.

Using dynamic text controls in Content, Before, and After framesFrames in the Content, Before, and After slots are automatically resized to accommodate dynamic text controls. If their contents exceed a page, the frames and contents are split across multiple pages. For information on how frames are split, see “Controlling how a frame and its contents fit in multiple pages” later in this chapter.

Using dynamic text controls in PageHeader framesFrames in the PageHeader slot are automatically resized to accommodate dynamic text controls in the same way as a content, before, and after frame. Unlike these other frames, however, a run-time exception occurs if a page header frame is too large to fit in a flow.

Frame 1

A

Output 2: Property values changed in design

Frame 2 VerticalSize = VerticalSizeFrameRelative

C VerticalPosition = VerticalPositionFrameBottom

D VerticalPosition = VerticalPositionFrameBottom

Frame 2

B

C

C h a p t e r 1 3 , W o r k i n g w i t h a d y n a m i c t e x t c o n t r o l 407

If you use dynamic text controls in a page header frame, set the frame’s MaximumHeight property to prevent the frame from getting too large.

Using dynamic text controls in PageFooter framesUnlike frames in the other slots, page footer frames do not change in size. At run time, Actuate places the page footer frame in the page before processing its contents; the frame’s position and size is set before a dynamic text control gets its data.

If you use a dynamic text control in a page footer frame, set the control’s MaximumHeight property appropriately so that the control fits in the frame. Alternatively, you can specify a ‘static’ height for the dynamic text control by setting its initial height, then setting its CanIncreaseHeight property to False.

Using the first technique, the dynamic text control grows dynamically up to the specified maximum height. Using the second technique, the dynamic text control’s height is fixed at design time.

Adjusting text formats for different rendering environments

Earlier in this chapter, the “Understanding how Actuate generates content in a dynamic text control” section described the techniques Actuate uses to generate output that is as consistent as possible for all its supported rendering environments, which include Actuate Viewer, DHTML viewer, PDF, client-side printing on Windows, and server-side printing on Windows and UNIX. Actuate’s generation technique takes measures to prevent truncation and overlapping of text, and to substitute fonts when it encounters unrecognized fonts.

If the report you design only appears or prints on a specific device, you can optimize the dynamic text output for that particular rendering environment. You can change the dynamic text control’s default Text Layout property values to adjust line and paragraph formats, and tab positions as needed. For example, by changing the LineWidthPadding property value, you can increase or decrease the amount of space on the right of the text, if the rendering environment displays too little or too much blank space there.

The following sections describe some of the common tasks that entail changing a dynamic text control’s Text Layout properties. To get the best output results for a rendering environment or environments, you will probably have to adjust property values through trial and error. Remember to always check the resulting output, especially if the report appears or prints on multiple rendering environments.

408 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Adjusting the space on the right of the textWhen Actuate generates the text contents of a dynamic text control, it uses fixed line breaks in a fixed control width, so that all rendering environments display the same number of lines of text. As a result, the amount of blank space at the end of lines differs, depending on the rendering environment, as shown in the following illustration.

If the report appears or prints to the second rendering environment in the example above, you can choose to reduce the space on the right of the text. To do so, decrease the default padding value by setting the dynamic text control’s LineWidthPadding property to a lower value. Note, though, that by reducing the LineWidthPadding value to optimize for the second rendering environment, text appearing on the first rendering environment might overflow or truncate.

The following illustration shows the effect of reducing LineWidthPadding for the previous examples. By decreasing the padding, more words fit on a line. The text layout improves for the second rendering environment, but text is now truncated in the first rendering environment.

For more information on the default padding value and how Actuate computes line breaks, see “Understanding how Actuate generates content in a dynamic text control” earlier in this chapter.

Adjusting the space between lines of textThe vertical space between lines is controlled by the following factors:

Part WDG24637 can only be usedwith the following parts: FL667W,FL668W, FL700R, FL701R, FL702R,FL800S, FL805S, FL810S, FL1000A,

Part WDG24637 can only be used with the following parts: FL667W, FL668W, FL700R, FL701R, FL702R, FL800S, FL805S, FL810S, FL1000A,

FL1010A FL1010A

Output in rendering environment 1 Output in rendering environment 2

fixed width x fixed width x

Part WDG24637 can only be used wthe following parts: FL667W, FL668FL700R, FL701R, FL702R, FL800S,FL805S, FL810S, FL1000A, FL1010A

Part WDG24637 can only be used withthe following parts: FL667W, FL668W,FL700R, FL701R, FL702R, FL800S,FL805S, FL810S, FL1000A, FL1010A

Changed output in rendering environment 1 Changed output in rendering environment 2

fixed width x fixed width x

C h a p t e r 1 3 , W o r k i n g w i t h a d y n a m i c t e x t c o n t r o l 409

■ The line height. Actuate computes the line height from the font at run time. The line height accommodates the largest font in the line, plus a small amount of extra space (the amount of space varies depending on the font used.)

■ The line spacing (single line, 1.5 line, double line). This value is multiplied by the line height value to calculate the vertical space between lines.

■ The space between lines in a paragraph. This is a fixed amount of space that is added between the lines of a paragraph.

For example, if the first line’s vertical position is 8.8", its line height is 0.175", the line spacing is 1.5, and the fixed space between lines is 0.05", the second line’s vertical position is calculated as follows:

8.8" + (0.175" x 1.5) + 0.05" = 9.112"

The following illustrations show how Actuate calculates the second line’s vertical position given the values above. Example 1 shows the results with a line spacing of 1.5, and example 2, with a line spacing of 1.

To increase or decrease the vertical space between lines, you can set the following Text Layout properties:

■ LineSpacing

This property is similar to line spacing (single line, 1.5 line, double line) properties in word processors, such as Microsoft Word. The value you specify is multiplied by the line height value to calculate the actual line spacing.

Line 1 sample 1

Line 2 sample 1

8.8"

9.112"

1.5 line spacing

0.175" line height

0.05" space between lines

Example 1: 1.5 line spacing

Line 1 sample 2Line 2 sample 2

8.8"

9.025"

1.0 line spacing0.175" line height

0.05" space between lines

Example 2: 1.0 line spacing

410 D e v e l o p i n g A d v a n c e d e . R e p o r t s

■ SpaceBetweenLines

Specify the space between lines in a paragraph. This is a fixed amount of space that is added between lines. This value is not affected by the LineSpacing value.

The LineSpacing and SpaceBetweenLines properties are used mainly to control text layout for plain text and HTML output. RTF text typically contains tags that specify line spacing and line leading. If used, these RTF tag values have precedence over the control’s LineSpacing and SpaceBetweenLines property values.

Adjusting the space between paragraphsThe space between paragraphs for plain text and HTML output is controlled by the following factors:

■ The line spacing, specified by the LineSpacing property, as described in the previous section.

■ The SpaceBetweenParagraphs property value. This value specifies a fixed amount of space to add between paragraphs. The default value is 0.08".

RTF text typically contains tags that specify line and paragraph spacing. These tag values have precedence over the control’s LineSpacing and SpaceBetweenParagraphs property values.

To increase the space between paragraphs, specify a value higher than 0.08" for the SpaceBetweenParagraphs property. To decrease the space between paragraphs, specify a value lower than 0.08".

The following illustrations show the effects of changing the SpaceBetweenParagraphs property value.

C h a p t e r 1 3 , W o r k i n g w i t h a d y n a m i c t e x t c o n t r o l 411

Adjusting the space between tabbed textThe space between tabbed chunks of text is determined by the following factors:

■ The width between tab stops. The default value is 0.5". The first tab stop is at 0.5", the second is at 1", the third is at 1.5", and so on.

■ The calculated width of each text chunk. This width includes the width of the actual text plus a padded amount of space. When generating the content of a dynamic text control, Actuate adds extra space when it calculates the text chunk’s end position. The default padding value is 7.5% of the width of the actual text. This technique prevents tabbed text from overlapping when rendered in environments whose font metrics differ from those used to compute tabs at generation time.

For example, if the text chunk’s start position is 2.5", its width is 1.45", and the padding value is 7.5%, the end position of the text chunk is calculated as follows:

2.5" + (1.45" x 1.075) = 4.059"

Output 1 Output 2

LineSpacing = 1SpaceBetweenParagraphs = 6 pt or ~ 0.08" (default)

LineSpacing = 1SpaceBetweenParagraphs = 0"

Output 4

LineSpacing = 1.2SpaceBetweenParagraphs = 0.08" (default)

To increase the space between paragraphs,specify a value higher than 0.08" for theSpaceBetweenParagraphs property. To decrease the space between paragraphs, specify a value lower than 0.08".

The following illustrations show theeffects of changing this property value.

To increase the space between paragraphs,specify a value higher than 0.08" for theSpaceBetweenParagraphs property. To decrease the space between paragraphs,specify a value lower than 0.08".The following illustrations show theeffects of changing this property value.

To increase the space between paragraphs,specify a value higher than 0.08" for theSpaceBetweenParagraphs property. To decrease the space between paragraphs, specify a value lower than 0.08".

The following illustrations show theeffects of changing this property value.

Output 3

LineSpacing = 1SpaceBetweenParagraphs = 0.15"

To increase the space between paragraphs,specify a value higher than 0.08" for theSpaceBetweenParagraphs property. To decrease the space between paragraphs, specify a value lower than 0.08".

The following illustrations show theeffects of changing this property value.

412 D e v e l o p i n g A d v a n c e d e . R e p o r t s

The following illustration shows the calculation. For legibility, the actual widths are not to scale.

If there are tab stops at 4" and 4.5", the 4.5" tab stop is used as the start position of the next text chunk. Without the padding, the end of the current text chunk would be 3.95" (2.5" + 1.45"), and the 4.0" tab stop would be used. With only 0.05" separating the two text chunks, there might be text overlap in some rendering environments.

The following illustrations show the results when no padding is used, and when it is. For legibility, the actual widths are not to scale.

To increase or decrease the amount of space in and between tabbed text, you can set the following Text Layout properties:

■ TabPadding

This property specifies the percentage by which the width of the text chunk is to be increased when Actuate calculates the text chunk’s end position. To reduce the amount of space between the text and the end of the text chunk, set TabPadding to a value less than the default value of 7.5%. To increase

Sample text chunk***11.45"

Pad =0.109"

Start position = 2.5"

End position = 4.059"

Sample text chunk***11.45"

Pad 0.109"

Start position = 2.5"

End position = 4.059"

2.5" 3.0" 3.5" 4.0"2.0"

Tab stops4.5" 5.0"

Text chunk 2

Start position = 4.5"

Example 2: With padding

Sample text chunk***11.45"

Start position = 2.5"

End position = 3.95"

2.5" 3.0" 3.5" 4.0"2.0"

Tab stops4.5" 5.0"

Text chunk 2

Start position = 4.0"

Example 1: Without padding

{

C h a p t e r 1 3 , W o r k i n g w i t h a d y n a m i c t e x t c o n t r o l 413

the amount of space (if text is overlapping), set TabPadding to a value higher than 7.5%.

■ TabSpacing

This property specifies the width between tab stops. This value is also used to determine the automatic indentation of bulleted and numbered lists. To decrease the amount of space between text chunks, set TabSpacing to a value less than the default value of 0.5". To increase the amount of space, set TabSpacing to a value higher than 0.5".

Controlling how a frame and its contents fit in multiple pages

When a frame increases in height to accommodate one or more dynamic text controls that have increased in height, it is sometimes necessary to split the contents of the frame over multiple flows or pages. Actuate computes logical places to split a frame and its contents.

You can fine-tune how and where splits occur by changing the default values of the frame or dynamic text control’s Pagination properties. For descriptions of each property, see the Actuate Foundation Class Reference.

The following sections describe some common tasks that entail changing a frame’s or dynamic text control’s Pagination properties.

Specifying how a frame and its contents should splitActuate splits a frame and its contents only if the frame contains at least one dynamic text control, as the default behavior. It splits the frame contents and places the segments in the most space-efficient manner, while presenting a reasonable layout. For example, Actuate ensures there are no segments that are too small at the top and bottom of pages when it splits a frame over multiple pages.

You can change how Actuate splits a frame or a dynamic text control by setting the AutoSplitVertical property under Pagination properties. You can specify that Actuate takes one of the following split actions:

■ Do not split the frame or control. To specify this action, set AutoSplitVertical to DoNotSplit. Only data that fits in the flow appears. The remaining data truncates. Use this setting to limit data to one page only.

414 D e v e l o p i n g A d v a n c e d e . R e p o r t s

■ Split the frame (excluding header and footers) only if it is the first one in the flow. Subsequent frames are placed on the next page, where again only the first frame is split, if necessary. To specify this action, set AutoSplitVertical to SplitIfNecessary. Use this setting to minimize the number of split frames. The trade-off is an increase in the amount of empty space on pages and, therefore, the number of pages.

■ Split the frame and its contents to maximize the use of space in the flow. To specify this action, set AutoSplitVertical to SplitIfPossible. For frames that contain dynamic text controls, the default setting—DefaultSplitting—yields the same results as SplitIfPossible. Use this setting to minimize the number of pages. The trade-off is more data will be split up across pages.

For more information about the AutoSplitVertical property and its different values, see Actuate Foundation Class Reference.

Splitting frames that contain dynamic text controlsThe following illustrations show the different results when:

■ You set the frame’s AutoSplitVertical property to DefaultSplitting (the default), SplitIfNecessary, and DoNotSplit, respectively.

■ The frames contain at least one dynamic text control.

In the illustrations, Frame 1 and Frame 2 might be in the following configurations:

■ Both frames might be in the same Content slot.

■ Frame 1 might be in a Before slot, and Frame 2, in a Content slot.

■ Frame 1 might be in a Content slot, and Frame 2, in an After slot.

Frame 1

DTC 1

Design Output 1

Frames and dynamic text controlsAutoSplitVertical = DefaultSplitting (default)/SplitIfPossible

Text 1

Label

Frame 2

Currency

DTC 2

Text

Label

DTC 1

DTC 1

DTC 2

DTC 2

Currency

Page 1 Page 2 Page 3

Frame 1

Frame 2

flow

C h a p t e r 1 3 , W o r k i n g w i t h a d y n a m i c t e x t c o n t r o l 415

Splitting frames that do not contain dynamic text controlsThe following illustrations show examples of results when frames do not contain dynamic text controls, and when the AutoSplitVertical property is set to SplitIfPossible, SplitIfNecessary, and DoNotSplit, respectively. The default value of DefaultSplitting has no effect on frames that do not contain dynamic text controls.

In the illustrations, Frame 1 and Frame 2 might be in the following configurations:

■ Both frames might be in the same Content slot

■ Frame 1 might be in a Before slot, and Frame 2, in a Content slot

■ Frame 1 might be in a Content slot, and Frame 2, in an After slot.

Output 2Frames’ AutoSplitVertical = SplitIfNecessary

Text

Label

DTC 1

DTC 1DTC 2

Currency

Page 1 Page 2 Page 3

Frame 1 Frame 2

DTC 2 can fit here, but SplitIfNecessary splits only the first frame in a flow.

Output 3Frames’ AutoSplitVertical = DoNotSplit

Text

Label

DTC 1

DTC 2

Currency

Page 1 Page 2

Frame 1 Frame 2

Frames and their contents are truncated.

416 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Frame 1

Text 2

Design Output 1Frame AutoSplitVertical = SplitIfPossible

Text 1

Label 1

Text 1

Label

Page 1 Page 2

Text 2 CurrencyFrame 1

Frame 2

flowPage 3

Currency

Label 2

Frame 2

Label 2

Text 1

Label

Output 2Frame AutoSplitVertical = SplitIfNecessary

Page 1 Page 2

Frame 1

Label 2 can fit here, but SplitIfNecessary splits only the first frame in a flow.

Text 2 Frame 2

Currency

Page 3

Label 2

Output 3Frames’ AutoSplitVertical = DoNotSplit

Page 1 Page 2Frames and their contents are truncated

Frame 1

Text 2

Text 1

Label 1

Frame 2

Currency

Label 2

C h a p t e r 1 3 , W o r k i n g w i t h a d y n a m i c t e x t c o n t r o l 417

Specifying an area of the frame that should not be splitTo present a reasonable layout when splitting frames and their contents, Actuate ensures that the first and last segments of a split frame are at least one inch in height. This prevents segments from being too small.

You can change this default behavior. To do so, change the values of the frame’s NoSplitTop and NoSplitBottom properties. NoSplitTop specifies the height of the area that must not be split at the top of the frame, or the minimum height of the first segment. NoSplitBottom specifies the height of the area that must not be split at the bottom of the frame, or the minimum height of the last segment.

Compare the layouts in the following illustrations; the first shows the results of using the default NoSplitTop and NoSplitBottom setting, the second shows the results of using a smaller NoSplitTop and NoSplitBottom value. In output 2, the smaller NoSplitTop value enables the first frame segment of the second frame to fit in the small space at the bottom of page one, and the smaller NoSplitBottom value results in a smaller last segment on page three. However, output 1 looks better than output 2.

Output 1

Frame NoSplitTop = 1" and NoSplitBottom = 1" (default values)

Text 1

LabelDTC DTC

Page 1 Page 2 Page 3

flowText 2

The last frame segment is at least one inch

Frame 1

Output 2Frame NoSplitTop < 1" and NoSplitBottom < 1"

DTC

DTC DTC

Page 1 Page 2 Page 3

Text 1

Label

Text 2

Frame 1

418 D e v e l o p i n g A d v a n c e d e . R e p o r t s

You can also use the NoSplitTop and NoSplitBottom properties to keep a group of related controls together at the top or bottom of the frame, that is, prevent them from being split across two pages.

If the frame’s height is less than the sum of NoSplitTop and NoSplitBottom, the frame is not split.

Setting margins for the segments of a split dynamic text controlThere are two types of margins you can set for a dynamic text control:

■ Margins: Bottom, Left, Right, and Top

The Margin properties specify a blank area between the content and the border of the dynamic text control. The default setting for the margin values is zero. Margins are useful if you set a background color or border for the dynamic text control and want some space between the text and the edges of the control.

Compare the following illustrations. The first shows the default setting of no margins, the second shows equal margins set on four sides of the control. The rectangle in dotted lines does not appear in the output; it is used in the illustration to show the margins.

■ SplitMarginBottom and SplitMarginTop

These properties are relevant only if the dynamic text control is split to fit on multiple pages. SplitMarginBottom specifies a blank area between the bottom edge of each segment (except the last) and its contents. SplitMarginTop specifies a blank area between the top edge of each segment (except the first) and its contents.

SplitMarginBottom and SplitMarginTop are set to zero as the default value.

Text content

Margin

Text fits within the control. Specifymargins if you use a background color for the control and you want some spacebetween the text and the control’s edges.

Text fits within the control. Specify marginsif you use a background color for the control and you want some space betweenthe text and the control’s edges.

Output 1

Output 2

C h a p t e r 1 3 , W o r k i n g w i t h a d y n a m i c t e x t c o n t r o l 419

The difference between the Margins property and the SplitMarginBottom/Top properties is evident when a dynamic text control is split into multiple segments. The top and bottom margins set through Margins-Top and Margins- Bottom appear at the top and the bottom of the control. When the control is split, the top of the control is in the first segment, and the bottom of the control is in the last segment.

The following illustration shows the effects of margins on a split dynamic text control:

Notice there is no space between the content and the bottom edge of the first segment. In the second segment, there is no blank space on either the top or bottom of the segment. In the third segment, there is no blank space at the top.

If you want space on the tops and bottoms of the segments, change the values of SplitMarginTop and SplitMarginBottom. Typically, you set SplitMarginTop to the same value as Margins➛Top, and SplitMarginBottom to the same value as Margins➛Bottom. This gives the segments of the dynamic text control consistent top and bottom margins.

Top margin of dynamic text control

Bottom margin

Page 1

Page 2

Page 3

A dynamic text control is split into three segments...

... and each segment is placed on a separate page

420 D e v e l o p i n g A d v a n c e d e . R e p o r t s

The following illustration shows the effects of the Margin and SplitMarginTop/Bottom properties on a dynamic text control that is split.

Setting margins for the segments of a split frameWhen a frame and its contents are split over multiple pages, each content segment occupying as much of the flow as possible is the default behavior. The frame resizes to fit each content segment. You can, however, add space between the top of each frame segment and the top of its contents, and between the bottom of each frame segment and the bottom if its contents.

To do so, change the values of the frame’s SplitMarginTop and SplitMarginBottom properties. The default setting is zero.

SplitMarginTop specifies the margin between the top edges of all frame segments (except the first) and their contents. The space between the top edges of the first frame segment and the top-most content is equal to the space specified in the report design.

SplitMarginBottom specifies a margin between the bottom edges of all frame segments (except the last) and their contents. The space between the bottom edges of the last frame segment and the lowest content is equal to the space specified in the report design.

Page 1

Page 2

Page 3

Margins Top, Bottom, Left, and Right = 0.1"SplitMarginTop = 0 (default)SplitMarginBottom = 0 (default)

Output 1 Output 2

Margins Top, Bottom, Left, and Right = 0.1"SplitMarginTop = 0.1"SplitMarginBottom = 0.1"

Page 1

Page 2

Page 3

C h a p t e r 1 3 , W o r k i n g w i t h a d y n a m i c t e x t c o n t r o l 421

The following illustration shows the difference between the output using the default values and the output when the frame’s SplitMarginBottom and SplitMarginTop properties are set to 0.1".

Controlling how lines in a paragraph breakThe default behavior, when Actuate splits a dynamic text control over multiple pages, is to prevent the last line of a paragraph from appearing by itself on the top of a page (such a line is called a widow), and the first line of a paragraph from appearing by itself on the bottom of a page (such a line is called an orphan). It does so by moving lines as needed between pages.

If you do not mind widow and orphan lines in your report, or want to use as much of the available space as possible, change the WidowAndOrphanControl value to False.

Page 1

Page 2

Page 3

Output 1 Output 2

Page 1

Page 2

Page 3

Design

Frame

DTC

h1

h2

0.1"SplitMarginTop

Frame SplitMarginTop and SplitMarginBottom = 0 (default)

Frame SplitMarginTop and SplitMarginBottom = 0.1"

0.1"SplitMarginBottom

0.1"SplitMarginBottom

0.1"SplitMarginTop

h1 h1

h2

h2

422 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Solving common output problemsThis section describes a few common output problems, their probable causes, and ways to solve them.

Problem 1

Controls in a frame are truncated at the bottom and only one page is generated, as shown in the following illustration.

Solution 1a

Check the AutoSplitVertical properties of the frame and the dynamic text control. If either one of them is set to DoNotSplit, the frame and its contents are truncated if they exceed a page.

Solution 1b

If you have multiple controls—dynamic text controls and other controls—in the frame, check the VerticalSize setting of the other controls. If set to VerticalSizeRelative, ensure that IsFrameDecoration = True. This setting is required to properly display the contents of the controls if they exceed one page. In the example shown in the previous illustration, the text control’s VerticalSize is set to VerticalSizeRelative, and its IsFrameDecoration property should be set to True.

Problem 2

Text in a dynamic text control overflows or is truncated at the end of lines in some rendering environments, as shown in the following illustration.

Customer Letters

To whom it may concern:

I’m writing this letter concerning the problems with

Action TakenDatatron Corp

the 3/1/02 shipment. The following are the problemswe had:

▲ Parts MR1005 missing

▲ Parts WR100100 broken

Dynamic text control text is truncated

Text control is truncated at the bottom

C h a p t e r 1 3 , W o r k i n g w i t h a d y n a m i c t e x t c o n t r o l 423

Solution 2

Increase the dynamic text control’s LineWidthPadding property value. For information about how Actuate uses this property value, see “Consistent line breaks within text” in “Understanding how Actuate generates content in a dynamic text control.”

Problem 3

Text in a dynamic text control contains extraneous characters, as shown in the following illustration.

Solution 3

Check the dynamic text control’s TextFormat property value. If set to TextFormatPlain, Actuate interprets HTML or RTF tags as literal text. Set TextFormat to the correct text format.

Customer Letters

To whom it may concern:

I’m writing this letter concerning the problems with

Datatron Corp

the 3/1/02 shipment. The following are the problemswe had:

▲ Parts MR1005 missing

▲ Parts WR100100 broken

Dynamic text control text overflows or is truncated on the right

Customer Letters

Datatron Corp

Dynamic text control displays HTML tags

<html><body><p>To whom it may concern:</p><p>I’m writing this letter concerning the problemswith the 3/1/02 shipment. The following are theproblems we had:</p><ul><li>Parts MR1005 missing</li><li>Parts WR100100 broken</li></ul>

424 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Problem 4

Overlapping controls, as shown in the following illustration. A and B are dynamic text controls, C is another control.

Solution 4

When a dynamic text control increases in height and overlaps another control, it usually means that the other control’s vertical position is set relative to the frame instead of the dynamic text control. In this example, C’s VerticalPosition is set to VerticalPositionFrameBottom, which means its bottom maintains the same distance from the bottom of the frame. If you do not know if, or how much, a dynamic text control above a control will increase in height, set the control’s VerticalPosition property to VerticalPositionDefault (the default value). When the dynamic text control increases in height, the control moves down accordingly.

Problem 5

Truncated controls in a nested frame, as shown in the following illustration. A and B are dynamic text controls, C is another control, Frame 2 is a nested frame.

Frame

A B

C

Frame 1

A Frame 2

B C

Output

C h a p t e r 1 3 , W o r k i n g w i t h a d y n a m i c t e x t c o n t r o l 425

The following illustration shows the report design and property values that resulted in the output above.

Solution 5

When controls in a nested frame are truncated, this typically indicates that a dynamic text control has increased in height but its parent frame has not. Check the parent frame’s VerticalSize property value. In this example, Frame 2’s VerticalSize property is set to VerticalSizeRelative, which means it is resized relative to dynamic control text A. In addition, Frame 2’s CanReduceHeight property is set to True. This property value combined with the VerticalSize property value means that Frame 2 will shrink if dynamic control A shrinks, as shown in the example.

To fix the problem in this example, you can do one of the following:

■ Set Frame 2’s CanReduceHeight value to False (the default value)

■ Set Frame 2’s VerticalSize property to VerticalSizeFixed (the default value)

Frame 1

A Frame 2

CB

Design

Frame 2 VerticalSize = VerticalSizeRelativeFrame 2 CanReduceHeight = True

426 D e v e l o p i n g A d v a n c e d e . R e p o r t s

C h a p t e r 1 4 , U n d e r s t a n d i n g c h a r t i n g c o n c e p t s 427

C h a p t e r

14Chapter 14Understanding charting

conceptsThis chapter contains the following topics:

■ About Actuate charts

■ Recognizing the elements of a chart

■ Understanding types of charts

■ Using a pie chart

■ Using a bar, line, or tape chart

■ Using an area chart

■ Using a scatter chart

■ Using a high-low-close, open-high-low-close, or candlestick chart

■ Working with time series in a chart

■ Using a dual y-axis chart

■ Understanding a hyperchart

■ Accessing data for a chart

428 D e v e l o p i n g A d v a n c e d e . R e p o r t s

About Actuate chartsYou create and update Actuate charts using the AcChart parent class. A chart is a graphic layout that displays data or the relationships between sets of data. Charts support the display of complex data in an easy-to-assimilate format.

Actuate charts are Unicode compliant, supporting data display in multiple languages and across locales. Charts render identically on Windows and UNIX platforms. An Actuate chart is a control that collects data and displays it in specific formats. Like other controls, you set properties for charts using Component Editor. Unlike other controls, which collect data from just one database row, a chart can collect data from one or more rows.

Actuate charts support links from a chart element to the report data from which that element generated. For example, a user chooses a data point in a line chart to go to the report content that contains the data for that point. Report designers can customize links to specific data internal or external to the report.

For compatibility with earlier releases, Actuate 7 continues to support the AcGraph class, the class from which all graphs derive. For information about AcGraph class, refer to the documentation from releases preceding Actuate 7. For information about accessing documentation from an earlier release, see:

http://support.actuate.com/es/products/releasenotes.asp

About the classes of chartsActuate 7 supports three general classes of charts. The chart class determines the source of your data and how it appears.

■ Detail charts plot one data point per database row. You can use detail charts to create pie, bar, line, tape, and scatter charts.

■ Summary charts sum data values from a data source and display the consolidated values as data points. You can use summary charts to create pie, bar, line, tape, and area charts.

■ High-low-close charts plot stock data. In this type of chart, a database column refers to a series. The chart plots one data point per database row. You can use AcHLCChart class to create high-low-close, open-high-low-close, and candlestick charts.

C h a p t e r 1 4 , U n d e r s t a n d i n g c h a r t i n g c o n c e p t s 429

Recognizing the elements of a chartCharts display data as data points, data categories, and data series. A data point is a coordinate in a chart that joins an x-axis value and a y-axis value. A data category is a data grouping. For example, on a bar chart showing automobile sales volumes for the year, the categories might be vehicle models. A data series is a subgroup of a category.

The following illustration shows the elements of a chart. This example shows a bar chart, one of the most commonly used types of charts. Not all Actuate charts use all of the elements shown here. Pie charts, for example, do not use series or properties from the y-axis. For more information about the elements that are available in a specific type of chart, refer to the section that describes each type of chart, such as high-low-close, open-high-low-close, and candlestick charts.

Sales by Region

Title

Category title

Category labels

Chips

Boards

Value or y-axis

Category or x-axis

40,000

30,000

20,000

10,000

0

Regions

North South East West

Value labels

Sal

es $

Value title

Legend

Series labels

Tick marks

430 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Understanding types of chartsActuate 7 supports the following nine types of charts:

■ Area

■ Bar

Part of chart Description

Category axis, often the x-axis

The category axis is the horizontal line along which the categories of data are represented. In area, bar, line, tape, scatter, and high-low-close charts, the category axis is the x-axis.

Category labels The optional category labels identify each category. In this illustration, North, South, East, and West are category labels.

Category title An optional label describes the meaning of the categories. In this illustration, Regions is the category title.

Legend The optional explanation displays the use of color in the chart. In this illustration, the legend tells which color indicates chips and which color indicates boards.

Series labels A set of descriptive labels that identify the series of data in the chart. A series is a set of data values with one value for each category in the chart.

Tick marks The optional lines correspond to the category and value labels’ positions on the axes.

Title The optional title appears above the chart. In this illustration, the title is Sales by Region.

Value axis, often the y-axis

The vertical line, or height, indicates the data values. In most area, bar, line, tape, scatter, and high-low-close charts, the y-axis displays values. A pie chart does not use any properties in the y-axis.

Value labels The value labels indicate the data values. In this illustration, the value labels are those on the y-axis, such as 10,000, 20,000, and 30,000.

Value title An optional label displays the meaning of the values. In this illustration the value title is Sales $.

C h a p t e r 1 4 , U n d e r s t a n d i n g c h a r t i n g c o n c e p t s 431

■ Candlestick

■ High-low-close

■ Line

■ Open-high-low-close

■ Pie

■ Scatter

■ Tape

The following illustrations show each type of chart. Note that area, bar, and pie charts can appear in two-dimensional format or in depth. The format in depth displays 3-dimensional visual effects for 2-dimensional data. AcChart class does not support true 3-dimensional charts, using x, y, and z axes.

Area chart Area chart in depth

Tape chart

Bar chart Bar chart in depth

Line chart

Pie chart Pie chart in depth

Scatter chartPie chart

432 D e v e l o p i n g A d v a n c e d e . R e p o r t s

The kind of information you want to present in the chart determines the chart type appropriate for your report. The following sections detail the factors to consider in selecting a chart type:

■ Using a pie chart

■ Using a bar, line, or tape chart

■ Using a scatter chart

Using a pie chartTo display percentages and compare segments, a pie chart is the optimal chart to design and read. A pie chart shows data values as a set of categories that comprise the whole. For example, a pie chart can display price quote totals for a range of inventory items, such as DSP, Driver, Dynamic Ram, and so on. The entire pie displays the total of price quotes for all categories. Each category appears as a percentage of the sum of all price quotes. You can express the display values for each category as numbers or percentages.

There are tasks for which pie charts are not suitable. A pie chart is not the best choice for showing numbers over a time or value continuum. Other types of charts such as line and bar charts are especially suited for these purposes. Pie charts cannot show negative values.

The following illustration displays a pie chart with six categories. Depending on the class of chart used, detail or summary, the percentages can be based on single data values or consolidated values.

Candlestick chartOpen-High-Low-Closechart

High-Low-Closechart

C h a p t e r 1 4 , U n d e r s t a n d i n g c h a r t i n g c o n c e p t s 433

The following illustration displays the same pie chart generated from a localized Japanese version of the database. The category labels in the legend appear as they are listed in the columns in the database. The chart appears identically when generated on Windows or UNIX systems.

To use a pie chart, choose from the following Actuate classes depending on how you want to retrieve and display your data:

■ AcSummaryChart

■ AcDetailChart

For more information about creating a chart, see “Creating a chart in a report design,” in Chapter 15, “Presenting data in a chart.”

434 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Using a bar, line, or tape chartIf you want to display data that requires both horizontal and vertical axes, especially over a time continuum, use a bar, line, or tape chart. You cannot use bar, line, or tape charts for detail charts with times series. For information about times series charts, see “Working with time series in a chart,” later in this chapter.

Displaying data in a bar chartA bar chart displays data values as a set of standing rectangular bars. The height of each bar represents a data value. A chart legend explains what those values are.

A bar chart can illustrate summary data, combinations of totals for various items or groups. For example, you want to show data about how processor chips and circuit boards are selling across the North, South, East, and West regions. As shown in the illustration that follows, you can create a bar chart consisting of four paired groups of bars, one pair per region. One bar in the pair indicates the dollar value of chips sold and the other indicates the dollar value of boards sold.

In this example, the chips and boards are the series, illustrated in the chart legend by different colors. A series is a set of data values that includes one value for each category. In this example, the North, South, East, and West regions are the categories. When you include several series in a chart, the chart displays several bars in each category. The x-axis displays the categories and the y-axis displays dollar values for the series.

Sales by RegionChips

Boards40,000

30,000

20,000

10,000

0

Regions

North South East West

Sal

es $

C h a p t e r 1 4 , U n d e r s t a n d i n g c h a r t i n g c o n c e p t s 435

Bar charts can display detail or summary data from the data source. If you use a detail chart, the dollar values are single data values. If you use a summary chart, the data values are consolidated, or summed. For more information about detail and summary data, see “Accessing data for a chart,” later in this chapter.

To use a bar chart, choose from the following Actuate classes depending on how you want to retrieve and display your data:

■ AcDetailChart

■ AcSummaryChart

For more information about bar charts using AcChart class, see “Creating a bar chart” in Chapter 15, “Presenting data in a chart.”

Displaying data in a line or tape chartA line chart displays data values as a dot-to-dot sequence of points that represent values connected by a line. A tape chart is a 3-dimensional visual representation of a line chart. The height of each point represents the values for one category of data. The chart legend displays the item represented by each line’s color.

Line and tape charts are useful to show a time continuum on the x-axis. Both are useful for displaying, for example, the movement of several mutual funds over time. A line chart could display, for example, outdoor temperatures recorded in a city at different times of the day.

Line and tape charts can show several series of data. A series includes one data value for each category. When you include several series in a chart, the chart shows several lines. Line and tape chart charts can display detail or summary data from the data source.

The following illustration shows a line chart created using the AcSummaryChart class, rendered on a Windows operating system. This example displays two series and four categories. The series are the numbers that represent the dollar value of sales of chips and boards. The categories are North, South, East, and West. The dollar values of the sales of chips and boards in the category North are the two points above the category label North. Based on the type of chart used, detail or summary, the dollar values for the sales of chips and boards can be single data values or consolidated values.

436 D e v e l o p i n g A d v a n c e d e . R e p o r t s

The following illustration shows the same chart created using the AcSummaryChart class and a data source localized in Korean. The chart was rendered on a UNIX operating system.

To create a line or tape chart, choose from the following Actuate classes depending on how you want to retrieve and display your data:

■ AcDetailChart

■ AcSummaryChart

For more information about line and tape charts using AcChart class, see “Creating a line or tape chart” in Chapter 15, “Presenting data in a chart.”

Sales by Region Chips

Boards40,000

30,000

20,000

10,000

0

Regions

North South East West

Sal

es $

40,000,000

30,000,000

20,000,000

10,000,000

0

C h a p t e r 1 4 , U n d e r s t a n d i n g c h a r t i n g c o n c e p t s 437

Using an area chartAn area chart shows data values as a set of high and low points connected by lines. The areas under those data values are filled in with colors. The height of each point on a line is the value that is important—the height represents the value of one category of data.

An area chart can show several series of data. A series includes one value for each category. If you include several series in a chart, the chart can display filled areas that overlap each other.

In the 2-D area chart shown in the following illustration, the North, South, and East regions are the categories. The dollar value of the sales of CPUs, boards, and chips are the series.

If you want to display an area chart, select the AcSummaryChart class.

For more information about area charts using AcChart class, see “Creating an area chart,” in Chapter 15, “Presenting data in a chart.”

Using a scatter chartA scatter chart shows data values as scattered points. Choose a scatter chart if you want to show points where the x- and y-axis are both numerical values but where a time continuum is not necessary. You can use scatter charts for detail charts with time series.

438 D e v e l o p i n g A d v a n c e d e . R e p o r t s

The following illustration shows a scatter chart that compares two sets of numerical data. The x-axis here displays numerical values of top speed. The y-axis displays prices in dollar amounts.

If you want to display a scatter chart, select the AcDetailChart class. In scatter charts, unlike the charts using the AcSummaryChart class, the x-axis plots numeric values rather than categories.

For more information about scatter charts using AcChart, see “Creating a scatter chart,” in Chapter 15, “Presenting data in a chart.”

Using a high-low-close, open-high-low-close, or candlestick chart

The high-low-close, open-high-low-close, and candlestick charts are most useful for showing points along a relatively short and contained time continuum, such as a business day. For example, stock quotes or temperatures that start the day at one point, and have a high point, a low point, and a final point, make good use of these types of charts. The open-high-low-close chart is the same as a high-low-close chart except that it shows one additional data value, the opening or starting value in the range.

A high-low-close chart shows ranges of values. Each range is represented as a vertical line with three optional horizontal bars to mark specific values. The position of each bar represents the top of the range, or high value, the bottom of the range, or low value, and a value in between, or close value.

Sportscar Speed vs. Price

70,000

60,000

50,000

40,000

30,000

Top speed (km/h)

200 300 400 500

Pric

e $

C h a p t e r 1 4 , U n d e r s t a n d i n g c h a r t i n g c o n c e p t s 439

The following illustration shows a high-low-close chart.

A candlestick chart is a variation on the high-low-close chart. Candlestick and open-high-low-close charts display the type of data that can be represented in sets of four values.

The candlestick chart uses a different set of symbols to represent the values. Instead of a vertical line marked with horizontal bars, the candlestick chart consists of a series of boxes with lines extending up and down from the ends. If the open value is higher than the close value, the box is filled with a color. Otherwise, the box is filled with white.

The following illustration shows a candlestick chart.

AcHLCChart class does not support charts with time series. For information about plotting time-related data using AcChart class, see “Creating a chart with time series,” in Chapter 15, “Presenting data in a chart.”

Record High, Record Low, and Today’s Average Temperature

80

60

40

20

0

Weekday

Mon Tue Wed Thu

Deg

rees

Fri

High bar

Low bar

Close bar

Stock Price Summary

80

60

40

20

0

Pric

e $

High value

Low value

Close value

Open value

Weekday

Mon Tue Wed Thu Fri

440 D e v e l o p i n g A d v a n c e d e . R e p o r t s

For more information about HLC, OHLC, and candlestick charts using AcChart class, see “Creating a high-low-close, open-high-low-close, or candlestick chart,” in Chapter 15, “Presenting data in a chart.”

Working with time series in a chartCharts with time series are most useful for showing how one or more values change over time. The labels on the x-axis can be dates, times, or numbers. Plot time along the x-axis and values along the y-axis.

For example, you could use a scatter chart with time series to plot the price per share for a security over the course of a trading day as shown in the following illustration.

You could use a scatter chart with time series to plot the price per share for several securities over the course of a trading day.

C h a p t e r 1 4 , U n d e r s t a n d i n g c h a r t i n g c o n c e p t s 441

You could also use a summary chart for a bar chart with time series to plot the sales for three sales offices over a three-month period as shown in the following illustration.

For a chart with time series, Actuate does the following based on the settings of certain properties and the data plotted on the chart:

■ Calculates a starting value for the x-axis

■ Calculates an ending value for the x-axis

■ Creates labels for the x-axis

Select one of the following Actuate chart classes:

■ For charts with time series, AcDetailChart supports only scatter charts.

■ AcSummaryChart

For information about creating charts with time series using the AcChart classes, see “Creating a chart with time series,” in Chapter 15, “Presenting data in a chart.”

Using a dual y-axis chartA dual y-axis chart is most useful for comparing related sets of values that have different units. A dual y-axis chart has a y-axis on the left and on the right. In general, the units for the base chart appear on the y-axis on the left, and the units for the dual y-axis chart appear on the y-axis on the right.

442 D e v e l o p i n g A d v a n c e d e . R e p o r t s

In the following illustration, the y-axis for the base chart, the bar chart, is on the left. The y-axis for the line chart is on the right.

The base chart can be any one of the following types:

■ 2DArea

■ 2DBar

■ High-low-close

■ Line

■ Scatter

For all base chart types except scatter charts, you must use a line chart with the second y-axis. For a scatter chart as the base chart, the second y-axis also uses a scatter chart. Actuate e.Report Designer Professional does not support multiple overlay lines.

For more information about dual y-axis charts using AcChart, see “Creating a dual y-axis chart,” in Chapter 15, “Presenting data in a chart.”

Understanding a hyperchartA hyperchart supports links to report data from the following chart elements:

■ Chart

■ Data point

Y-axis for base chart Y-axis for dual y-axis chart

Base chart Dual y-axis chart

C h a p t e r 1 4 , U n d e r s t a n d i n g c h a r t i n g c o n c e p t s 443

■ Series

■ Category

If you enable a hyperchart, you choose a chart element to navigate to data or a report section that contains details about the chart’s data. For example, in the chart that appears in the following illustration, Chips and Boards are the series. In the report design, you can create a link from the chart’s Chips bars to the report section that contains the data in the Chips series. When a user chooses a Chips bar, the details about the data in the Chips series appears.

For more information about linking chart elements to report data, see “Creating a hyperchart,” in Chapter 15, “Presenting data in a chart.”

Accessing data for a chartUnderstanding how the data stream works for each chart type helps you choose which class of chart is best for your application. When you choose a class, you are telling the factory processes to gather data from the data stream and format the chart in a certain way.

Use Query Editor to edit the query, which determines the data that the chart processes use. For information about using Query Editor, see Chapter 7, “Using a query data stream.”

The following three subclasses of AcChart of AcChart each handle the data stream, data collection, and mathematical processes differently.

Sales by Region Chips

Boards40,000

30,000

20,000

10,000

0

Regions

North South East West

Sal

es $

Choosing a Chips bar links to Chips series data

Series

444 D e v e l o p i n g A d v a n c e d e . R e p o r t s

■ AcDetailChart

■ AcSummaryChart

■ AcHLCChart

About the data stream for an AcDetailChartFor a chart in the AcDetailChart class, which is a detailed line or scatter chart, the factory processes format the chart as follows:

■ For every row that the data stream collects, it calls the method BuildFromRow( ) in the chart class. BuildFromRow( ) gathers the x and y values from the data row as specified in the chart’s Expression group properties.

■ In turn, the subroutine/method AddPoint( ) is called.■ AddPoint( ) adds this new point to the array of existing points for this

instance of the chart. A point is a structure that contains members x and y.

■ The point count increments and the subroutine/method returns.

About the data stream for an AcHLCChartThe high-low-close charts collect data the same way a detail chart does. Instead of gathering the x and y values, however, BuildFromRow( ) gathers the open, high, low, and close values. A point is the structure that contains the open, high, low, and close values.

The chart factory processes populate the chart using the following AcHLCChart subclasses:

■ ChartCandlestick

■ ChartHLC

■ ChartOHLC

C h a p t e r 1 4 , U n d e r s t a n d i n g c h a r t i n g c o n c e p t s 445

About the data stream for an AcSummaryChartIn broad terms, for charts in the AcSummaryChart classes, the factory processes make two passes through the data.

■ The first pass gathers the data rows. Once the data rows are gathered, the internal representation of the chart is built, using the data for the categories.

■ In the second pass, the processes find all the series. For each row, the processes create a unique list of series objects.

The factory processes then create the chart from the data collected. In the following illustration, the bar chart displays categories and series data.

.

In this example, the series includes the sales amounts for products a and b for the years 1997 and 1998. For each region, a different colored bar, represents the sales amount for the year and the product. The legend displays the color keys for year-product, 1997-a, 1997-b, 1998-a, and 1998-b.

The following table shows the data source rows and columns used to create the bar chart shown in the preceding illustration.

Region Year Product YearProduct Amount

North 1997 a 1997-a 100

North 1997 b 1997-b 100

North 1997 a 1997-a 150

North 1997 b 1997-b 150

North 1997 b 1997-b 110

446 D e v e l o p i n g A d v a n c e d e . R e p o r t s

In this example, the first pass through the data collected the category information, which appears on the category axis as the regions North and South.

The next pass through the data gathered and summed the series to create a unique summary for each item in the series as shown in the following table.

The charting processes then produced the summary chart, which displays the unique summary value for each item in the series as the bars representing 1997-a, 1997-b, 1998-a, and 1998-b for each of the years.

North 1998 a 1998-a 120

North 1998 b 1998-b 90

North 1998 a 1998-a 150

North 1998 a 1998-a 110

South 1997 a 1997-a 150

South 1997 b 1997-b 100

South 1997 a 1997-a 120

South 1997 a 1997-a 80

South 1998 a 1998-a 150

South 1998 b 1998-b 100

South 1998 a 1998-a 95

South 1998 a 1998-a 80

Region Year Product YearProduct Amount

Region Year Product YearProduct Amount

North 1997 a 1997-a 250

North 1997 b 1997-b 360

North 1998 a 1998-a 380

North 1998 b 1998-b 90

South 1997 a 1997-a 350

South 1997 b 1997-b 100

South 1998 a 1998-a 325

South 1998 b 1998-b 100

C h a p t e r 1 5 , P r e s e n t i n g d a t a i n a c h a r t 447

C h a p t e r

15Chapter 15Presenting data in a

chartThis chapter contains the following topics:

■ About charts

■ Creating a chart in a report design

■ About the category axis in a chart

■ About the value axis in a chart

■ Creating a pie chart

■ Creating a bar chart

■ Creating a line or tape chart

■ Creating an area chart

■ Creating a scatter chart

■ Creating a high-low-close, open-high-low-close, or candlestick chart

■ Creating a dual y-axis chart

■ Creating a chart with time series

■ Creating a hyperchart

■ Rendering charts on Windows and UNIX

448 D e v e l o p i n g A d v a n c e d e . R e p o r t s

About chartsActuate 6 introduced charts using the AcChart superclass, which is the class from which all charts derive. The Actuate charting engine that renders charts created using the AcChart superclass produces identical output for Windows and UNIX platforms.

This chapter provides information about creating:

■ Pie charts

■ Bar charts

■ Line and tape charts

■ Area charts

■ Scatter charts

■ High-low-close, open-high-low-close, and candlestick charts

■ Dual y-axis charts

■ Charts with time series

■ Hypercharts

For information about the available types of charts, see Chapter 14, “Understanding charting concepts.”

For more information about the AcChart class, see Class AcChart in Actuate Foundation Class Reference.

Creating a chart in a report designUse the following general procedure to insert a chart control in your report design.

For information about chart types, see “Understanding types of charts,” in Chapter 14, “Understanding charting concepts.”Understanding types of charts.

How to create and insert a chart in a report design

1 Place a frame anywhere in your report design where you want to display a chart.

For information about inserting frames in a report design, see “Placing frames in a report design,” in Chapter 12, “Working with frames and controls.”

C h a p t e r 1 5 , P r e s e n t i n g d a t a i n a c h a r t 449

2 Choose Insert➛Chart. Position the chart control in the frame and click to drop it.

Select Chart Class appears.

3 In Select Chart Class, select one of the three chart classes, depending on the type of chart you want to display.

The following are general guidelines:■ Use AcDetailChart for scatter and line charts and for some pie charts,

when you want to plot one data point per database row.■ Use AcSummaryChart for pie, bar, line, and area charts, which plot one

data point based on many database rows summed across categories.■ Use AcHLCChart for high-low-close, open-high-low-close, and

candlestick charts, which plot multiple data points individual categories.

If you choose AcSummaryChart, the chart control appears in the layout pane as shown in the following illustration.

4 Drag the handles on the chart control to resize it.

Increasing the size displays more details of the control’s sample data.

450 D e v e l o p i n g A d v a n c e d e . R e p o r t s

5 In the layout pane, right-click the chart control and choose Properties.

Component Editor appears.

6 Set the ChartType-Specific➛ChartType property.

For information about how to set the properties for a component, see “Setting properties of components,” in Chapter 4, “Using Design Editor.”

The following table lists the property values available for each type of chart.

Type of chart Chart type properties

Pie Chart2DPie Chart3DPie

Bar Chart2DBar Chart3DBar

Line or Tape ChartLine

Tape ChartTape

Area Chart2DArea Chart3DArea

High-low-close ChartHLC

Open-high-low-close ChartOHLC

Candlestick ChartCandleStick

Scatter ChartScatter

C h a p t e r 1 5 , P r e s e n t i n g d a t a i n a c h a r t 451

7 Format the chart using the properties available to the type of chart you chose. For information about setting properties for the chart, see the following topics, later in this chapter:■ Creating a pie chart■ Creating a bar chart■ Creating a line or tape chart■ Creating an area chart■ Creating a scatter chart■ Creating a high-low-close, open-high-low-close, or candlestick chart■ Creating a dual y-axis chart■ Creating a chart with time series

For all chart types, the height and width of the chart control affects the visual appearance of the chart and the chart legend. If the chart control is too small to display all items in the legend, the number of items that appear in the legend is determined by the following:

■ The size of the chart control

If the chart control is too small, some items do not appear or are truncated. Increasing the size of the chart control enables more items to appear in the legend.

■ The font size used in the legend

Decreasing the legend’s font size enables more items to appear in the legend.

About the category axis in a chartAll types of charts except pie charts have a category axis, or x axis, which is the line along which the major divisions of data are represented. The following illustration shows the parts of the category axis you can format.

10.00 20.00 30.00 40.00

Price of Product

Major and minor ticks

Grid lines

Labels, origin, and maximum

Title

452 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Use the X-Axis group properties to format the category axis. The following illustration shows Component Editor displaying the default values for the X-Axis group properties for a detail chart.

For more information about these properties, see Class AcChart in Actuate Foundation Class Reference.

How to format category axis labels

The category axis is the x-axis. To format category axis labels, set the following properties in the X-Axis group:

1 Set the XMajorTickCount property to a value greater than or equal to one.

2 Set the XLabelStyle property to ChartCustomXLabels.

3 Set the XLabelFormat property to the appropriate format, for example $#,##0.

C h a p t e r 1 5 , P r e s e n t i n g d a t a i n a c h a r t 453

How to display gridlines for the category axis

To display gridlines for the category axis, set the following properties in the X-Axis group:

1 Set the XMajorGridStyle property to a value other than NullLine, for example DotLine.

2 Set the XMajorTickStyle property to ChartCustomTicks or ChartAutoTicks.

3 Set the XMajorTickCount property to a value greater than zero.

For information about formatting the x-axis for a chart, see “Creating a chart with time series,” later in this chapter.

About the value axis in a chartAll types of charts except pie charts have a value axis, or y axis, which is the line along which the data values are represented. The following illustration shows the parts of the value axis you can format.

Major and minor ticks

Grid lines

Labels, origin, and maximum

Title

0

10

20

30

Num

ber

Sol

d

454 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Formatting the value axisUse the Y-Axis group properties to format the value axis. The following illustration shows Component Editor displaying the default values for the Y-Axis group properties for a detail chart.

For more information about these properties, see Class AcChart in Actuate Foundation Class Reference.

How to format value axis labels

The value axis is the y-axis. To format value axis labels, set the following properties in the Y-Axis group:

1 Set the YMajorTickCount property to a value greater than or equal to one.

2 Set the YLabelStyle property to ChartCustomYLabels.

3 Set the YLabelFormat property to the appropriate format, for example $#,##0.

C h a p t e r 1 5 , P r e s e n t i n g d a t a i n a c h a r t 455

How to format value axis YMax and YMin properties

To apply YMax and YMin settings, you must do the following in the Y-Axis group properties:

1 Set the YAxisOrigin property to ChartZeroOrigin.

2 Set the YLabelStyle property to ChartCustomYLabels.

3 Set the YMajorTickStyle property to ChartCustomTicks.

If the data points lie above and below the x-axis, then YMax and YMin are set to the greater of the two absolute values. For example, if

YMax = 500YMin = -1000

then YMax is set to 1000, and YMin is set to -1000. Similarly, if

YMax = 1000YMin = -500

then YMax is set to 1000, and YMin is set to -1000.

How to display gridlines for the value axis

To display gridlines for the value axis, do the following in the Y-Axis group properties:

1 Set the YMajorGridStyle property to a value other than NullLine, for example ChartDotLine.

2 Set the YMajorTickStyle property to ChartCustomTicks or ChartAutoTicks.

3 Set the YMajorTickCount property to a value greater than zero.

Specifying a tick interval for the value axisIf you specify a tick interval, or the distance between tick marks, for the y-axis or the dual y-axis, Actuate does the following:

■ Calculates a starting value for the y-axis or the dual y-axis

■ Calculates an ending value for the y-axis or the dual y-axis

■ Creates labels for the y-axis or the dual y-axis

How to specify a tick interval for the y-axis

To specify a tick interval for the y-axis, set the following properties in the Y-Axis group:

1 Set YLabelStyle to ChartIntervalYLabels.

2 Set YTickInterval to the appropriate value.

456 D e v e l o p i n g A d v a n c e d e . R e p o r t s

How to specify a tick interval for the dual y-axis

To specify a tick interval for the y-axis, set the following properties in the DualY-Axis group:

1 Set DualYLabelStyle to ChartIntervalYLabels.

2 Set DualYTickInterval to the appropriate value.

If Actuate creates more than 50 labels for the y-axis or the dual y-axis, labels do not appear on that axis. You must increase the value of YTickInterval or DualYTickInterval so that fewer labels are created.

For an example of a detail chart in which tick intervals are specified for both the y-axis and the dual y-axis, see “Creating a dual y-axis scatter chart example,” later in this chapter. For more information about these properties, see Class AcChart in Actuate Foundation Class Reference.

Creating a pie chartPie charts use AcSummaryChart or AcDetailChart class. Pie charts show data values as categories that are parts of a whole, such as the sales figures that are divided by geographical region in the following illustration.

How to set pie chart properties

After you place the pie chart in your design, use Component Editor to designate how the pie chart gathers data and to format the chart.

C h a p t e r 1 5 , P r e s e n t i n g d a t a i n a c h a r t 457

1 In the Expressions group, choose a property to set its value expression as shown in the following table.

2 In the Legend group, set the values for the legend display properties, which appear in the following table.

For pie charts, you must specify values for the CategoryExp and CategoryLabelExp properties in order to display category labels in the legend.

Expressions group property

Description

CategoryExp Specifies the category variable in the data stream for AcSummaryChart.

CategoryLabelExp Specifies the category variable that appears in the legend for AcSummaryChart. This value can be different from the value for CategoryExp. If you do not set this property, the values returned by CategoryExp appear in the legend.

SeriesExp Does not apply for pie charts because pie charts cannot contain series data.

SeriesLabelExp Does not apply for pie charts because pie charts cannot contain series data.

YValueExp Specifies the equation to use for the categories and series. You can formulate the expression just as you would for a data control. The expression must evaluate to the Double data type. The following expression charts the total number of products sold:Sum([items.quantity])

Legend group property Description

LegendBackgroundColor Choose a background color from the list or choose Builder to display Color, which contains more options. TransparentColor enables the chart’s General➛BackgroundColor property to appear.

LegendBorderStyle Choose a border style.

LegendColorText Choose True or False to apply color to text.

458 D e v e l o p i n g A d v a n c e d e . R e p o r t s

3 In the General group, set the values for the chart’s display properties, which appear in the following table.

LegendFont group properties

Expand the LegendFont group to choose values for font properties.

LegendMinFontSize Set a minimum font size in points. The default value is 6. To fit multiple items in the legend, the font size decreases. If all items cannot fit in the legend for this chart control size using this minimum font size, some items do not appear in the legend. The legend drops the item with the lowest value first. To indicate that not all items appear, an ellipsis (…) follows the last visible item in the legend. To ensure the legend font does not shrink, set the LegendMinFontSize to the same value as Legend➛LegendFont➛Size.

LegendPosition Choose where the legend appears relative to the chart. ChartLegendRight is the default value. Setting the value to ChartLegendNone hides the pie chart legend.

Legend group property Description

General group property Description

BackgroundColor Choose a background color for the entire chart control from the list or choose Builder to display Color, which contains more options.

ChartBackgroundColor Choose a background color for the pie chart portion of the control.

PointLabelFont group properties

Set the properties that apply to the point labels. If the pie chart control is too small to display all point labels, set PointLabelMinFontSize and PointLabelVariableFontSize to support reducing the font size to display the point labels.

C h a p t e r 1 5 , P r e s e n t i n g d a t a i n a c h a r t 459

PointLabelMinFontSize Set a minimum font size in points. The default value is 6. Use this property to set the minimum font size to which data labels shrink when the chart control size is not large enough to display all data labels. For this property to apply, you must set PointLabelVariableFontSize to True. This property applies only to pie charts. If all data labels cannot fit in the chart control using this minimum font size, some items do not appear in the chart. The chart drops the item with the lowest value first.

PointLabelStyle Choose a style for the point labels for each segment.

PointLabelVariableFontSize

Set this value to True to support reducing the size of the pie chart’s data label font to the value of PointLabelMinFontSize if the chart control is too small to display all data labels. Setting this property to True displays data labels in two columns in the chart control with lines connecting to the pie segments. Setting this property to False ignores the PointLabelMinFontSize setting and displays data point labels around the pie chart without lines to the pie segments. This property applies only to pie charts.

ValuesColorList Type a comma-separated list of colors to apply to the segments. If you do not enter a list, default color values apply. If you supply a list and more segments appear than in the color list, the colors repeat for the segments.

General group property Description

460 D e v e l o p i n g A d v a n c e d e . R e p o r t s

4 You can set the remaining properties listed in the following table. If a property is not listed, this type of chart ignores it.

The ValuesColorList property is a comma-separated list of color names or RGB values to color the bars or lines. For a pie, each color corresponds to one category. For other charts, each color corresponds to a series. If the number of series exceeds the number of colors in the list, the system reuses colors starting at the beginning of the list. If you do not set this property, the system uses default color values.

For more information about these properties, see Class AcSummaryChart and AcDetailChart in Actuate Foundation Class Reference.

How to create an exploding pie chart

You can extract a segment of the pie, displaying the segment separately but near the rest of the pie as shown in the following illustration. This is called exploding the pie.

Property group Property

ChartType-Specific ChartTypeLineStyleLineStylesListLineThicknessPointsArePercentShowAsPercentShowLinesShowSymbols

Expressions CategoryExp (AcSummaryChart only)CategoryLabelExp (AcSummaryChart only)SeriesExpYValueExp

General BackgroundColorChartBackgroundColorChartBorderStyle PointLabelFontPointLabelOrientationPointLabelStyleValuesColorList

Legend All

Position All

Size All

Titles All

C h a p t e r 1 5 , P r e s e n t i n g d a t a i n a c h a r t 461

To explode a pie segment:

1 Select AcDetailChart when you choose the chart type.

2 For each segment, set the x expression to 1 or 0 in the Finish method. Choose 1 to explode the segment and 0 to not explode the segment.

Alternatively, you can choose to use a Summary Chart:

1 Select AcSummaryChart when you choose the chart type.

2 Override the Finish method.

3 Iterate through the chart points setting. Set the x value for each point to either 1 or 0. Set the x value to 1 to explode the segment. Set the value to 0 to not explode the segment.

Examples To loop through all the points and explode all pie segments, place the following code in the Finish method after the Super::Finish( ) call:

Dim i As Integer

FOR i = 0 to PointCount Step 1 Points(0,i).X = 1NEXT

To loop through all the points and explode every other pie segment, place the following code in the Finish method after the Super::Finish( ) call:

Dim i As Integer

FOR i = 0 to PointCount Step 2 Points(0,i).X = 1NEXT

462 D e v e l o p i n g A d v a n c e d e . R e p o r t s

To explode the last pie segment, place the following code in the Finish method after the Super::Finish( ) call:

Dim i As Integer

FOR i = 0 to PointCount Step 1Points(0,PointCount - 1).X = 1

NEXT

The last pie segment is one less than the point count because the point count is padded with a blank point.

To loop through all the points and explode all but the last pie segment, place the following code in the Finish method after the Super::Finish( ) call:

Dim i As Integer

FOR i = 1 to PointCountIF i <> PointCount THEN

Points(0,i).X = 1END IF

NEXT

For more information about expressions in data controls, see “Setting display values for controls,” in Chapter 12, “Working with frames and controls.”

Reviewing properties of a pie chart exampleThe pie chart shown in the following illustration displays the revenue generated by each of three offices, Boston, NYC, and Philadelphia, as a percentage of the total revenue generated by all three offices. In the report design, the class name of the pie chart is SummaryChart. SummaryChart is a subclass of AcSummaryChart.

C h a p t e r 1 5 , P r e s e n t i n g d a t a i n a c h a r t 463

The query for a pie chart exampleThis report design uses the sfdata data source. The SQL statement appears in the following illustration.

The computed column totalsales is equal to:

SUM(items.pricequote * items.quantity)

SummaryChart properties for a pie chart exampleSummaryChart’s properties specify the appearance of the chart in the report. The following table displays the properties you set specifically for this example pie chart.

Property group

Property Value Description

ChartType-Specific

ChartType Chart2DPie Specifies the chart type.

LineStyle ChartSolidPattern

Specifies that a solid line appears around each pie segment.

LineThickness 1 Specifies the line thickness around each pie segment.

ShowAsPercent True Specifies that the pie segments appear as relative percentages of the pie.

ShowLines True Specifies that lines appear around the pie segments.

464 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Expressions CategoryExp [offices.city] Specifies that each segment represents the revenue generated by an office.

CategoryLabelExp Specifies the value that appears in the legend. If CategoryLabelExp is not specified, the CategoryLabelExp uses the default value, the CategoryExp value, as in this example.

SeriesExp 1 Must contain a constant string value for the legend to appear in the chart.

YValueExp Sum([totalsales])

For any chart that is a subclass of AcSummaryChart, YValueExp must be an aggregate function. YValueExp specifies the expression to use to calculate the size of each pie segment, the revenue generated by an office.

General PointLabelStyle ChartNumericLabels

This value must be set for point labels to appear as percentages.

Legend LegendPosition ChartLegendBottom

Specify where the legend appears.

Titles TitleText Percentage Revenue by Office

Specifies the chart’s title.

Property group

Property Value Description

C h a p t e r 1 5 , P r e s e n t i n g d a t a i n a c h a r t 465

Reviewing properties of an exploded pie chart exampleThis exploded pie chart appears identical to the pie chart in the previous example, except that one segment is detached from the rest of the pie. In the report design, however, the class name of the pie chart is DetailChart. DetailChart is a subclass of AcDetailChart.

The query for an exploded pie chart exampleThis report design uses the sfdata data source. The SQL statement appears in the following illustration.

The computed column totalsales is equal to:

SUM(items.pricequote * items.quantity)

466 D e v e l o p i n g A d v a n c e d e . R e p o r t s

DetailChart properties for an exploded pie chart exampleDetailChart’s properties specify the appearance of the chart in the report. Most of these properties have the same values as in the previous example. The following table displays the properties you set specifically for this example exploded pie chart.

Property group

Property DefaultValue

Description

ChartType-Specific

ChartType Chart2DPie Specifies the chart type.

LineStyle ChartSolidPattern

Specifies that a solid line appears around each pie segment.

LineThickness 1 Specifies the line thickness around each pie segment.

ShowAsPercent True Specifies that the pie segments appear as relative percentages of the pie.

ShowLines True Specifies that lines appear around the pie segments.

Expressions SeriesExp 1 Must contain a constant string value for the legend to appear in the chart.

XLabelExp [offices.city] Specifies the label that appears in the Legend for each segment of the pie.

XValueExp [offices.city] Specifies what each segment of pie represents. In this example, each segment of the pie represents the revenue generated by an office.

C h a p t e r 1 5 , P r e s e n t i n g d a t a i n a c h a r t 467

DetailChart methods for an exploded pie chart exampleDetailChart’s Finish method is overridden as shown in the following illustration. The Finish method enables the legend and explodes one segment of the pie.

YValueExp [totalsales] For any chart that is a subclass of AcDetailChart, YValueExp cannot be an aggregate function. In this example, the size of each pie segment represents the revenue generated by an office.

General PointLabelStyle ChartNumericLabels

Must be set for point labels to appear as percentages.

Legend LegendPosition ChartLegendBottom

Specify where the legend appears.

Titles TitleText Percentage Revenue by Office

Specifies the chart’s title.

Property group

Property DefaultValue

Description

468 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Creating a bar chartBar charts use AcSummaryChart or AcDetailChart class.

The following illustration shows four categories, the regions, on the x-axis. Each region contains two series, chips and boards sold in that region. The height of the bars represents the sales in dollars for each series item in each category.

How to set bar chart properties

After you place the bar chart in your design, use Component Editor to set the properties to designate how the bar chart gathers data. Use the properties to format the chart.

Sales by Region Chips

Boards40,000

30,000

20,000

10,000

0

Regions

North South East West

Sal

es $

C h a p t e r 1 5 , P r e s e n t i n g d a t a i n a c h a r t 469

1 In the Expressions group, choose a property to set its value expression as shown in the following table.

2 You can set the remaining properties listed in the following table. If a property is not listed, this type of chart ignores it.

Expressions group property

Description

CategoryExp Specifies the category variable in the data stream.

CategoryLabelExp Specifies the variable that appears in the legend.These labels can appear on the x-axis if the X-Axis➛XLabelStyle property is set to ChartExpressionXLabel. For the default value of the XLabelStyle property, ChartAutoXLabels, the system calculates values and displays integers for the category labels on the x-axis. If you do not set the CategoryLabelExp property, the values returned by CategoryExp appear in the legend.

SeriesExp Specifies the series variable in the data stream.

SeriesLabelExp Specifies the series labels that appear in the legend.

YValueExp Specifies the expression you want the processes to use for the categories and series. e.Report Designer Professional plots the value of the expression on the y-axis. You can use the same kind of expression as you would for a data control. The expression must evaluate to the Double data type. The following expression charts the total number of products sold:Sum([items.quantity])

Property group Property

ChartType-Specific ChartTypeBarGroupingBarOrientation

Expressions CategoryExp CategoryLabelExp SeriesExp SeriesLabelExp YValueExp

General All

Legend All

470 D e v e l o p i n g A d v a n c e d e . R e p o r t s

You cannot use AcDetailChart for bar charts with time series. For more information about charts with times series, see “Working with time series in a chart,” in Chapter 14, “Understanding charting concepts.”

For information about formatting the x- and y-axes, see “About the category axis in a chart” and “About the value axis in a chart,” earlier in this chapter.

For more information about these properties, see Class AcChart in Actuate Foundation Class Reference.

Reviewing properties of a bar chart exampleThis bar chart example shows the revenue generated by three offices, Boston, NYC, and Philadelphia, for each of four items, MV1632, MV1664, MVL1632, and MVL1664 as shown in the following illustration. In the report design, the class name of the bar chart is SummaryChart. SummaryChart is a subclass of AcSummaryChart.

Position All

Size All

TimeSeries All for charts with time series

Titles All

X-Axis All

Y-Axis All

Property group Property

C h a p t e r 1 5 , P r e s e n t i n g d a t a i n a c h a r t 471

The query for an example bar chartThis report design uses the sfdata data source. The SQL statement appears in the following illustration.

The WHERE clause restricts items.itemcode to values greater than MV.

SummaryChart properties for an example bar chartThe chart’s properties specify the appearance of the chart in the report. The following table lists the properties you set specifically for this bar chart example.

Property group

Property Value Description

ChartType-Specific

ChartType Chart2DBar Specifies the chart type.

Expressions CategoryExp [offices.city] Specifies the value each set of vertical bars represents. In this example, each set of vertical bars represents the revenue generated by an office for each of four items.

CategoryLabelExp [offices.city] Specifies the expression that appears on the category axis to label each set of bars.

DualYValueExp This property does not apply for this chart, which uses a single y-axis.

472 D e v e l o p i n g A d v a n c e d e . R e p o r t s

SeriesExp [items.itemcode]

Specifies what each vertical bar in the series represents. In this example, each bar represents a different itemcode.

SeriesLabelExp [items.itemcode]

Specifies the label that appears in the legend.

YValueExp Sum([items.pricequote] * [items.quantity])

Specifies the height of each vertical bar. The height of each vertical bar represents the revenue generated by an office for an item.YValueExp must be an aggregate function for any chart that is a subclass of AcSummaryChart.

Legend LegendBackgroundColor

LightGray Specifies the legend’s background color.

LegendBorderStyle ChartSolidBorder

Specifies the legend has a solid border.

LegendPosition ChartLegendTopRight

Specifies the legend’s position.

Position X 0.15” Specifies the horizontal position of the chart control in the upper left corner of the frame that contains it.

Property group

Property Value Description

C h a p t e r 1 5 , P r e s e n t i n g d a t a i n a c h a r t 473

Y 0” Specifies the vertical position of the chart control in the upper left corner of the frame that contains it.

Size Height 4.45” Specifies the vertical size of the chart control in the units specified in Options—Units.

Width 7.8” Specifies the horizontal size of the chart control in the units specified in Options—Units.

Titles TitleText AcSummaryChart Bar Chart

The title for the chart.

X-Axis XLabelStyle ChartExpressionXLabels

Specifies the labels that appear on the x-axis.

XTitle Items sold by office

Specifies the x-axis title label.

Y-Axis YAxisOrigin ChartCustomOrigin

Specifies the y-axis origin value.

YLabelFormat $#,##0 Specifies the y-axis label format.

YLabelStyle ChartCustomYLabels

Specifies the y-axis label style.

YMajorGridStyle ChartDotLine Specifies the y-axis grid line style.

YMajorTickStyle ChartCustomTicks

Specifies the ticks on the y-axis.

YMajorTickCount 5 Specifies the y-axis tick separation value.

YTitle Revenue. Specifies the y-axis title.

Property group

Property Value Description

474 D e v e l o p i n g A d v a n c e d e . R e p o r t s

SummaryChart methods for an example bar chartYou can override SummaryChart’s ComputeMinMax method as shown in the following illustration. In this method, YMin and YMax specify the minimum and maximum values on the y-axis. If you override ComputeMinMax, you must set YAxisOrigin to ChartCustomOrigin for the specified values of YMin and YMax to take effect.

Creating a line or tape chartLine and tape charts use AcSummaryChart or AcDetailChart class.

How to set line and tape charts properties for summary charts

After you place the line or tape chart in your design for a summary chart, use Component Editor to designate how the chart gathers data and to format the chart.

40,000

30,000

20,000

10,000

0

Sales by Region Chips

Boards

Regions

North South East West

Sal

es $

C h a p t e r 1 5 , P r e s e n t i n g d a t a i n a c h a r t 475

1 In the Expressions group, choose a property to set its value expression as described in the following table.

2 In the Legend group of properties, set the values for the legend display properties, which appear in the following table.

Expressions group property

Description

CategoryExp Specifies the category variable in the data stream.

CategoryLabelExp Specifies the variable that appears in the legend.These labels appear on the x-axis if the expression labels property is set. If this property is not set, the values displayed can be calculated internally, depending on the XLabelStyle property.If the CategoryLabelExp property is not set, the values returned by CategoryExp appear in the legend.

SeriesExp Specifies the series variable in the data stream.

SeriesLabelExp Specifies the series labels that appear in the legend.

YValueExp Specifies the equation you want the processes to use to work with the categories and series.You can use the same kind of expression as you use for a data control. The expression must evaluate to the Double data type. The following expression charts the total number of products sold:Sum([items.quantity])

Legend group property Description

LegendBackgroundColor

Choose a background color from the list or choose Builder to display Color, which contains more options. TransparentColor enables the chart’s General➛BackgroundColor property to appear.

LegendBorderStyle Choose a border style.

LegendColorText Choose True or False to apply color to text.

LegendFont group properties

Expand the LegendFont group to choose values for font properties.

476 D e v e l o p i n g A d v a n c e d e . R e p o r t s

3 You can set the remaining properties listed in the following table. If a property is not listed, this type of chart ignores it.

LegendMinFontSize Set a minimum font size in points. The default value is 6. To fit multiple items in the legend, the font size decreases. If all items cannot fit in the legend for this chart control size using this minimum font size, some items do not appear in the legend. The legend drops the item with the lowest value first. To indicate that not all items appear, an ellipsis (…) follows the last visible item in the legend. To ensure the legend font does not shrink, set the LegendMinFontSize to the same value as Legend➛LegendFont➛Size.

LegendPosition Choose where the legend appears relative to the chart. ChartLegendRight is the default value. Setting the value to ChartLegendNone hides the legend.

Legend group property Description

Property group Property

ChartType-Specific LineStyle LineStylesList LineThickness ShowLines ShowSticks ShowSymbols

Expressions CategoryExp CategoryLabelExp SeriesExp SeriesLabelExp YValueExp

General All

Legend All

Position All

Size All

TimesSeries All for charts with time series

Titles All

X-Axis All

Y-Axis All

C h a p t e r 1 5 , P r e s e n t i n g d a t a i n a c h a r t 477

For more information about charts with times series, see “Working with time series in a chart,” in Chapter 14, “Understanding charting concepts.” For more information about properties that affect line and tape charts, see “How to set line and tape charts properties for a detail charts,” later in this chapter.

For more information about these properties, see Class AcChart in Actuate Foundation Class Reference.

How to set line and tape charts properties for a detail charts

After you place the line or tape chart in your design for a detail chart, use Component Editor to designate how the chart gathers data and to format the chart.

1 In the Expressions group, choose a property to set its value expression as described in the following table.

Expressions group property

Description

CategoryExp Specifies the category variable in the data stream.

CategoryLabelExp Specifies the variable that appears in the legend.These labels appear on the x-axis if the expression labels property is set. If this property is not set, the values displayed can be calculated internally, depending on the XLabelStyle property.If the CategoryLabelExp property is not set, the values returned by CategoryExp appear in the legend.

SeriesExp Specifies the series variable in the data stream.

SeriesLabelExp Specifies the series labels that appear in the legend.

YValueExp Specifies the equation you want the processes to use to work with the categories and series.You can use the same kind of expression as you use for a data control. The expression must evaluate to the Double data type. The following expression charts the total number of products sold:Sum([items.quantity])

478 D e v e l o p i n g A d v a n c e d e . R e p o r t s

2 In the Legend group properties, set the values for the legend display properties, which appear in the following table.

Legend group property

Description

LegendBackgroundColor

Choose a background color from the list or choose Builder to display Color, which contains more options. TransparentColor enables the chart’s General➛BackgroundColor property to appear.

LegendBorderStyle Choose a border style.

LegendColorText Choose True or False to apply color to text.

LegendFont group properties

Expand the LegendFont group to choose values for font properties.

LegendMinFontSize Set a minimum font size in points. The default value is 6. To fit multiple items in the legend, the font size decreases. If all items cannot fit in the legend for this chart control size using this minimum font size, some items do not appear in the legend. The legend drops the item with the lowest value first. To indicate that not all items appear, an ellipsis (…) follows the last visible item in the legend. To ensure the legend font does not shrink, set the LegendMinFontSize to the same value as Legend➛LegendFont➛Size.

LegendPosition Choose where the legend appears relative to the chart. ChartLegendRight is the default value. Setting the value to ChartLegendNone hides the legend.

C h a p t e r 1 5 , P r e s e n t i n g d a t a i n a c h a r t 479

3 You can set the remaining properties listed in the following table. If a property is not listed, this type of chart ignores it.

You cannot use AcDetailChart for line and tape charts with time series. For more information about charts with times series, see “Creating a chart with time series,” later in this chapter.

To create a line or tape chart in which the x and y values might not appear at regular intervals, see “Creating a chart with time series,” later in this chapter.

For information about formatting the x and y axes, see “About the category axis in a chart,” and “About the value axis in a chart,” earlier in this chapter.

Property group Property

ChartType-Specific LineStyle LineStylesList LineThickness ShowLines ShowSticks ShowSymbols

Expressions CategoryExp CategoryLabelExpSeriesExpSeriesLabelExpYValueExp

General All

Legend All

Position All

Size All

TimeSeries All for charts with time series

Titles All

X-Axis All

Y-Axis All

480 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Creating an area chartArea charts use AcSummaryChart class.

How to set area chart properties

After you place the area chart in your design, use Component Editor to designate how the chart gathers data and to format the chart.

1 In the Expressions group, choose a property to set its value expression as shown in the following table.

Expressions group property

Description

CategoryExp Specifies the category variable in the data stream.

CategoryLabelExp Specifies the variable that appears in the legend for the x-axis.If you do not set this property, the values returned by CategoryExp appear in the legend. These calculations depend on the X-Axis➛LabelStyle property.

SeriesExp Specifies the series variable in the data stream.

C h a p t e r 1 5 , P r e s e n t i n g d a t a i n a c h a r t 481

2 In the Legend group properties, set the values for the legend display properties, which appear in the following table.

SeriesLabelExp Specifies the series labels that appear in the legend.

YValueExp Specifies the equation the processes use to work with the categories and series.You can use the same kind of expression as you use for a data control. The expression must evaluate to the Double data type. The following expression charts the total number of products sold:Sum([items.quantity])

Expressions group property

Description

Legend group property Description

LegendBackgroundColor

Choose a background color from the list or choose Builder to display Color, which contains more options. TransparentColor enables the chart’s General➛BackgroundColor property to appear.

LegendBorderStyle Choose a border style.

LegendColorText Choose True or False to apply color to text.

LegendFont group properties

Expand the LegendFont group to choose values for font properties.

LegendMinFontSize Set a minimum font size in points. The default value is 6. To fit multiple items in the legend, the font size decreases. If all items cannot fit in the legend for this chart control size using this minimum font size, some items do not appear in the legend. The legend drops the item with the lowest value first. To indicate that not all items appear, an ellipsis (…) follows the last visible item in the legend. To ensure the legend font does not shrink, set the LegendMinFontSize to the same value as Legend➛LegendFont➛Size.

LegendPosition Choose where the legend appears relative to the chart. ChartLegendRight is the default value. Setting the value to ChartLegendNone hides the legend.

482 D e v e l o p i n g A d v a n c e d e . R e p o r t s

3 You can set the remaining properties listed in the following table. If a property is not listed, this type of chart ignores it.

For information about creating charts with times series, see “Creating a chart with time series,” later in this chapter.

To create an area chart in which the x and y values might not appear at regular intervals, see “Creating a chart with time series,” later in this chapter.

For information about formatting the x- and y-axes, see “About the category axis in a chart,” and “About the value axis in a chart,” later in this chapter.

For more information about these properties, see Class AcChart in Actuate Foundation Class Reference.

Creating a scatter chartScatter charts use AcDetailChart class. In scatter charts, unlike the charts in the AcSummaryChart class, the category, or x-axis, plots numeric values rather than categories. With a scatter chart, you are plotting the result of the values at the intersections of the x- and y-axis. For example, you can compare the top speed of a sports car to its price as shown in the following illustration.

Property group Property

ChartType-Specific ShowAsPercentShowLinesShowSymbols

General All

Legend All

Position All

Size All

TimeSeries All for charts with time series

Titles All

X-Axis All

Y-Axis All

C h a p t e r 1 5 , P r e s e n t i n g d a t a i n a c h a r t 483

How to set scatter chart properties

After you place the area chart in your design, use Component Editor to designate how the scatter chart gathers data and to format the chart.

1 In the Expressions group, choose a property to set its value expression as described in the following table.

Sportscar Speed vs. Price

70,000

60,000

50,000

40,000

30,000

Top speed (km/h)

200 300 400 500

Pric

e $

Expressions group property

Description

SeriesExp Specifies the series variable in the data stream.

SeriesLabelExp Specifies the series labels that appear in the legend.

XValueExp Specifies the equation the processes use to work with the series.You can use the same kind of expression as you use for a data control. The expression must evaluate to the Double data type. The following expression charts the total number of products sold:Sum([items.quantity])

YValueExp Specifies the equation the processes use to work with the series.You can use the same kind of expression as you use for a data control. The expression must evaluate to the Double data type.

484 D e v e l o p i n g A d v a n c e d e . R e p o r t s

2 You can set the remaining properties listed in the following table. If a property is not listed, this type of chart ignores it.

To create a scatter chart in which the x and y values might not appear at regular intervals, see “Creating a chart with time series,” later in this chapter.

For more information about value expressions, see “Setting display values for controls,” in Chapter 12, “Working with frames and controls.”

For information about formatting the x- and y-axes, see “About the category axis in a chart,”and “About the value axis in a chart,” later in this chapter.

For more information about these properties, see Class AcDetailChart in Actuate Foundation Class Reference.

Creating a high-low-close, open-high-low-close, or candlestick chart

High-low-close (HLC), open-high-low-close (OHLC), and candlestick charts use AcHLCChart class, which does not support time series. The following illustration shows a high-low-close chart.

Property group Property

ChartType-Specific LineStyleLineStylesListLineThicknessShowLines. When set to True, connects the scattered points of the chart.

General All

Legend All

Position All

Size All

TimeSeries All for charts with time series

Titles All

X-Axis All except XLabelsList

Y-Axis All except YLabelsList

C h a p t e r 1 5 , P r e s e n t i n g d a t a i n a c h a r t 485

The following illustration shows an open-high-low-close chart.

How to set high-low-close, open-high-low-close, and candlestick charts properties

1 Set each property in the Expressions group to an expression, such as a database column name. You can use the same kind of expression as you would for a data control. OpenValueExp, HighValueExp, LowValueExp, and CloseValueExp must evaluate to the Double data type.

Record High, Record Low, and Today’s Average Temperature

80

60

40

20

0

Weekday

Mon Tue Wed Thu

Deg

rees

Fri

High bar

Low bar

Close bar

Stock Price Summary

80

60

40

20

0

Weekday

Mon Tue Wed Thu

Pric

e $

Fri

HighValue

LowValue

CloseValue

OpenValue

486 D e v e l o p i n g A d v a n c e d e . R e p o r t s

The following table lists the properties in the Expressions group.

For example, a chart of stock prices might use the following expressions:

OpenValue = [ prices.openPrice ]HighValue = [ prices.highPrice ]LowValue = [ prices.lowPrice ]CloseValue = [ prices.closePrice ]

2 Use the following table to determine the property groups and properties to set to format a HLC, OHLC, or candlestick chart. If a property is not listed, this type of chart ignores it.

For more information about value expressions, see “Setting display values for controls,” in Chapter 12, “Working with frames and controls.”

For information about formatting the x- and y-axes, see “About the category axis in a chart,” and “About the value axis in a chart,” earlier in this chapter.

For more information about these properties, see Class AcHLCChart in Actuate Foundation Class Reference.

Expressions group property

Description

CloseValueExp Determines the height of the close mark.

DateExp Determines the labels along the category axis for a time series chart.

DualYValueExp Determines the value expression for an dual y-axis chart.

HighValueExp Determines the height of the high mark.

LowValueExp Determines the height of the low mark.

OpenValueExp Determines the height of the open mark (bar or edge of box) for OHLC and candlestick charts

Property group Property

ChartType-Specific HLCBarStyle LineStyleLineThickness

General All

Position All

Size All

Titles All

X-Axis All except XLabelsList

Y-Axis All except YLabelsList

C h a p t e r 1 5 , P r e s e n t i n g d a t a i n a c h a r t 487

Creating a dual y-axis chartUse Component Editor to set required and optional properties to create dual y-axis charts. For dual y-axis charts, the second y-axis chart is a line chart except for scatter charts. If the base chart is a scatter chart, the second y-axis is also a scatter chart.

Setting required properties for a dual y-axis chartTo create a dual y-axis chart, you must set the following properties:

■ ChartType

■ DualYDisplay

■ SeriesExp

Set the required properties as listed in the following table.

For more information about the properties listed in the preceding table, see Class AcChart in Actuate Foundation Class Reference.

Propertygroup

Property Description

ChartType-Specific

ChartType Set to one of the following:Chart2DAreaChart2DBarChartHLCChartLineChartScatter

DualY-Axis DualYDisplay Set to True to tell Actuate to display the dual y-axis chart.

Expressions SeriesExp A dual y-axis chart always has more than one series. Use the SeriesExp to identify each series. For example, for the chart Top Five Stocks shown in the topic “Working with time series in a chart,” in Chapter 14, “Understanding charting concepts,” the SeriesExp is the stock’s ticker symbol.The dual y-axis chart plots the last series as the default behavior.

488 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Setting optional properties for a dual y-axis chartSetting the following properties is optional for a dual y-axis chart:

■ DualYValueExp

■ DualY-Axis group properties

■ SeriesLabelExp

Set the optional properties as listed in the following tables.

For the DualY-Axis group properties, with the exception of the required DualYDisplay property, use the information in the following table to set the values for the optional properties. Use these properties as you would use their counterparts in the Y-Axis group.

Propertygroup

Property Description

Expressions DualYValueExp If the value expression for the dual y-axis chart is different from the value expression for the base chart, use DualYValueExp to specify the value expression for the dual y-axis chart.

SeriesLabelExp The SeriesLabelExp appears in the legend. If you do not enter a value for SeriesLabelExp, the SeriesExp is used.

DualY-Axis group property

Description

DualYAxisOrigin Specifies the value for the origin:For ChartAutoOrigin, the system calculates the origin.For ChartCustomOrigin, the chart design specifies the origin.For ChartZeroOrigin, the origin is 0. ChartZeroOrigin is the default value.

DualYKeyValue Specifies the value of the series key for the dual y-axis chart. If not specified, the dual y-axis chart plots the last series.

DualYLabelFormat Specifies the format of the dual y-axis chart label.

DualYLabelOrientation Specifies the orientation of the dual y-axis chart label.

DualYLabelStyle Specifies the style of the dual y-axis chart label. The default value is ChartAutoYLabels.

C h a p t e r 1 5 , P r e s e n t i n g d a t a i n a c h a r t 489

DualYLineColor Specifies the color of the dual y-axis line. The default value is Black.

DualYLinePattern Specifies the pattern for the dual y-axis line. The default value is ChartSingleLine.

DualYLineThickness Specifies the thickness of the dual y-axis line. The default value is 1.

DualYMajorTickCount Specifies the number of ticks to display on the dual y-axis. If the chart displays grid lines, set DualYMajorTickCount and YMajorTickCount to the same value for optimal display.

DualYMajorTickStyle Specifies the type of tick marks to display on the dual y-axis. ChartNoTicks is the default value.

DualYMax Specifies the maximum y-axis limit of the dual y-axis chart. The default value is 100.

DualYMin Specifies the minimum y-axis limit of the dual y-axis chart. The default value is 0.

DualYShowLine Specifies displaying lines connecting the points of the dual y-axis chart. The default value is True.

DualYShowSymbols Specifies whether points are represented by a symbol on the dual y-axis chart. The default value is True.

DualYTickInterval Specifies the number of units between the tick marks on the dual y-axis. The default value is 1.

DualYTitle Specifies the title of the dual y-axis label.

DualYTitleBackgroundColor

Specifies the background color of the title of the dual y-axis. The default value is TransparentColor.

DualYTitleBorderStyle Specifies the style of the border rectangle that encloses the title of the dual y-axis. The default value is ChartNoBorder.

DualYTitleOrientation Specifies the orientation of the dual y-axis title. The default value is ChartYLabelUp.

DualY-Axis group property

Description

490 D e v e l o p i n g A d v a n c e d e . R e p o r t s

If the base chart is a line chart:

■ The dual y-axis chart uses the line thickness specified with the DualY-Axis➛DualYLineThickness property.

■ If the ChartType-Specific➛LineStyle property is set to ChartCustomPatterns and no line styles appear in the LineStylesList property, the default patterns are used for the base chart.

■ If the ChartType-Specific➛LineStyle property is set to ChartCustomPatterns and the LineStylesList property contains values, the chart cycles through all of the specified patterns. To specify the values of the LineStylesList property, enter values from the LineStyle property as a comma-separated list.

■ Colors behave the same as patterned lines.

For more information about the chart’s properties, see Class AcChart in Actuate Foundation Class Reference.

Understanding limitations of a dual y-axis chartDual y-axis charts have the following limitations:

■ You can specify point labels for the base chart but not for the dual y-axis chart.

■ You cannot specify the symbol for an dual y-axis chart. The symbol for the dual y-axis chart depends on the number of series in the base chart.

■ You cannot specify grid lines for a dual y-axis chart.

■ If you set the BarOrientation property to ChartBarHorizontal, the dual y-axis chart does not appear.

■ If a dual y-axis chart has data points that appear before the base chart and the base chart is an area chart, the chart does not appear correctly.

■ If the data contains only one series, the DualYDisplay property is implicitly set to False.

Creating a dual y-axis scatter chart exampleThe following illustration shows a detail chart that compares the NASDAQ index to the price per share for five securities over the first five hours of a trading day. This chart shows how to use a time series. The base chart shows the price per share for each security at various times throughout the five-hour period. The base chart uses the y-axis on the left. The dual y-axis chart shows the NASDAQ index at various times throughout the same five-hour period. The dual y-axis chart uses the y-axis on the right and the line connecting the scatter chart points is thicker than the other lines.

C h a p t e r 1 5 , P r e s e n t i n g d a t a i n a c h a r t 491

This example report design is located in \Program Files\Actuate7\Erdpro\Examples\Charts\MultiSetTimeSeries\Multisettimeseries.rod.

The query for a dual y-axis scatter chart exampleThis report design uses the stocktrades data source. The SQL statement appears in the following illustration.

The WHERE clause restricts trades.Code to 2 because this value indicates that the value in the column trades.Val is a price per share.

Chart properties for a dual y-axis scatter chart exampleThe chart’s properties specify the appearance of the chart in the report. The following table lists the properties you set specifically for this dual y-axis scatter chart example.

Property group

Property Value Description

ChartType-Specific

ChartType ChartScatter Specifies the chart type.

LineStyle ChartSolidPattern

Specifies that solid lines connect the points on the chart.

492 D e v e l o p i n g A d v a n c e d e . R e p o r t s

LineThickness 1 Specifies the thickness of the lines connect the points on the chart using the left y-axis.

ShowLines True Specifies that lines connect the points on the chart.

ShowSymbols True Specifies that a symbol represents each point on the chart.

DualY-Axis DualYDisplay True Specifies displaying the dual y-axis chart.

DualYKeyValue NASDAQ Specifies the value of the SeriesExp for the dualy-axis chart is NASDAQ.

DualYLabelFormat

#,### Specifies the format string for the labels of the dualy-axis chart.

DualYLabelStyle

ChartIntervalYLabels

Use this value because DualYTickInterval specifies a tick interval.For more information about the DualYLabelStyle and DualYTickInterval properties, see “Specifying a tick interval for the value axis,” earlier in this chapter.

DualYLineColor Red Specifies the dual y-axis line is red.

DualYLinePattern

ChartSingleLine

Specifies the dual y-axis line pattern.

DualYLineThickness

3 Specifies the dual y-axis line is thicker than the lines in the base chart.

DualYTickInterval

25 Specifies placing tick marks for the dual y-axis chart at intervals of 25.

DualYTitle Points Specifies the dual y-axis title.

DualYTitleOrientation

ChartYLabelDown

Specifies the DualYTitle reads from top to bottom.

Property group

Property Value Description

C h a p t e r 1 5 , P r e s e n t i n g d a t a i n a c h a r t 493

DualYShowLine True Specifies that a line connects the points for the right y-axis.

Expressions SeriesExp [trades.Symbol]

This chart plots a time series for each security. [trades.Symbol] is the security’s ticker symbol. Because no SeriesLabelExp is specified, the system uses SeriesExp in the legend.

XValueExp [trades.TransactionTime]

Specifies the transaction time, which appears as the x value for each point.

YValueExp [trades.Val] Specifies the security’s price per share, which appears as the y value for each point.

General ValuesColorList Black, Blue,Green, Cyan, Purple, Red

Specifies the point color sequence used in the chart and legend.

Legend LegendBorderStyle

ChartSolidBorder

Specifies that the legend appears enclosed by a solid border.

LegendPosition ChartLegendRight

Specifies that the legend appears to the right of the chart.

TimesSeries Range 5 Specifies that the chart plots data for a five-hour period.

RangeUnit ChartHourUnit

Specifies measuring the times series range in hours.

TickInterval 30 Specifies placing tick marks along the x-axis at 30-minute intervals.

TickIntervalUnit ChartMinuteUnit

Specifies displaying ticks for minute intervals.

TimesSeries True Specifies the chart uses time series.

Titles TitleText Top Stocks vs NASDAQ before 2pm

Specifies the chart’s title.

Property group

Property Value Description

494 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Creating a dual y-axis bar chart exampleThe following illustration shows a summary chart that compares the average deal size with the sales revenue for three sales offices over a three-month period. The base chart shows the sales revenue for the offices, Boston, NYC, and Philadelphia, over a three-month period, using the y-axis on the left. The dual y-axis chart shows the average deal size over the same three months, using the y-axis on the right.

X-Axis XLabelFormat hh:nn Specifies displaying x-axis labels in hours:minutes format, for example 11:30.

XMajorGridStyle

ChartDotLine

Specifies displaying vertical grid lines as dotted lines.

XLabelOrientation

ChartVertical

Specifies displaying x-axis labels vertically.

XTitle Trade for 2/9/00

Specifies the x-axis title.

Y-Axis YLabelFormat #,### Specifies the format string used to format the y-axis labels.

YLabelStyle ChartIntervalYLabels

Use this value because YTickInterval specifies a tick interval.For more information about the YLabelStyle and YTickInterval properties, see “Specifying a tick interval for the value axis,” earlier in this chapter.

YMajorGridStyle

ChartDotLine

Specifies displaying horizontal grid lines as dotted lines.

YTickInterval 10 Specifies placing tick marks along the y-axis at intervals of 10.

YTitle Price in $ Specifies the y-axis title.

Property group

Property Value Description

C h a p t e r 1 5 , P r e s e n t i n g d a t a i n a c h a r t 495

This example uses the sfdata data source. The report design for this chart is located in \Program Files\Actuate7\Erdpro\Examples\Charts\SummaryTimeSeries\Summarytimeseries.rod.

The multiple input data filter for a dual y-axis bar chart exampleBecause the query for the base chart and the query for the dual y-axis chart are different, the report design uses a multiple input data filter to create a data row called GraphDataRow that is used by the chart.

For more information about multiple input data filters, see Chapter 6, “Customizing a report,” in Programming e.Reports.

Multiple input data filterConnection to sfdata

Query for base chart

Query for dual y-axis chart

Data row used by chart

496 D e v e l o p i n g A d v a n c e d e . R e p o r t s

The variables for a dual y-axis bar chart exampleThe report design uses several variables. Actuate creates the variables for the data rows for the base query and the dual y-axis query. Each of these variables corresponds to a column in the query’s SQL SELECT statement. The variables defined for ChartDataRow are used in the chart’s Expressions group properties. The variable WhichQuery is used in MultipleInputFilter’s Fetch( ) method.

The Fetch( ) method for a dual y-axis bar chart exampleThe Fetch() method populates GraphDataRow, the data row used by the chart, with data from the base query and the dual y-axis query. Notice the following lines of code in the OverlayDataRow case:

Variables created fordata row for base query

Variables created for data row for dual y-axis query

Variables used in chart’sExpressions group properties

Variable used in MultipleInputFilter’s Fetch() method

C h a p t e r 1 5 , P r e s e n t i n g d a t a i n a c h a r t 497

aGraphDataRow.City = "Average Deal Size"aGraphDataRow.OfficeID = 4

For the dual y-axis chart, [City] = "Average Deal Size" and [OfficeID] = 4.

Chart properties for a dual y-axis bar chart exampleThe chart’s properties specify the appearance of the chart in the report. The properties for this chart are similar to the properties for the summary chart with time series described in “Setting properties for a summary chart with times series,” later in this chapter.

For dual y-axis chart:[City] = "Average Deal Size"[OfficeID] = 4

498 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Expressions group properties for a dual y-axis bar chart example

The chart’s Expressions group properties use the variables defined for GraphDataRow. The Expressions group properties for this chart appear in the following illustration.

DualY-Axis group properties for a dual y-axis bar chart example

Because the SeriesExp is [OfficeID] and the Fetch() method sets [OfficeID] to 4 for the dual y-axis chart, the DualYKeyValue is set to 4. Likewise, because the SeriesLabelExp is [City] and the Fetch() method sets [City] to Average Deal Size for the dual y-axis chart, this label is used in the chart’s legend.

The Finish() method for a dual y-axis bar chart exampleThe Finish() method for this chart is similar to the Finish() method for the summary chart with time series described in “Setting properties for a summary chart with times series,” later in this chapter.

C h a p t e r 1 5 , P r e s e n t i n g d a t a i n a c h a r t 499

Creating a chart with time seriesCharts with time series are useful for showing a change in value over a time range. The following illustration shows a scatter chart with time series that compares the price per share of five securities over the course of a trading day.

This section contains information about the following:

■ Setting properties for a scatter chart using AcDetailChart class with times series

■ Creating scatter charts using AcDetailChart class with time series examples

■ Setting properties for a summary chart with times series

■ Comparing properties of detail and summary charts with time series

■ Limitations of charts with time series

Several of the examples described in the following topics use the stocktrades data source. The stocktrades data source is a Microsoft Access database. This database is located in \Program Files\Actuate7\Erdpro\Examples\Database\Stocktrades.mdb. For more information about setting up a Microsoft Access database, see “How to set up the data source manually,” in Chapter 1, “Designing an e.report with the report wizard.”

The database lists five securities, ABCD, EFGH, IJKL, MNOP, and QRST. Each row describes a transaction and every transaction occurs on the same trading day. The database also lists the value of the NASDAQ index at 15-minute intervals throughout the day.

500 D e v e l o p i n g A d v a n c e d e . R e p o r t s

The database consists of a single table, trades, with five columns.

The following table describes the data in each column.

Setting properties for a scatter chart using AcDetailChart class with times seriesTo design detail charts with time series you work with certain required properties. The following sections explain which properties are required and which are optional. You cannot use AcDetailChart class for line, bar, and area charts with times series.

Setting required properties for a scatter chart using AcDetailChart with time seriesTo create a detail chart with time series, you must set the following properties:

■ XValueExp

■ YValueExp

■ ChartType

■ TimeSeries

Column Data

Symbol The security’s ticker symbol.

TransactionTime The time of day at which a transaction occurred.

Val The price per share or the volume of shares traded, depending on the value in the Code column.

Code 1 or 2. 1 indicates that the Val column contains a volume. 2 indicates that the Val column contains a price per share.

ID The primary key.

C h a p t e r 1 5 , P r e s e n t i n g d a t a i n a c h a r t 501

For a scatter chart using AcDetailChart class with time series, the following table lists the property groups, properties, and values for the required properties

For a detail chart with time series, setting the TimeSeries property to True tells Actuate to do the following:

■ Calculate a starting value for the x-axis

■ Calculate an ending value for the x-axis

■ Create labels for the x-axis

■ Set XAxisOrigin to ChartCustomOrigin

■ Set XLabelStyle to ChartCustomXLabels

■ Set XMajorTickCount to XLabelCount - 1

■ Set XMajorTickStyle to ChartCustomTicks

■ Set XValueSet to ChartXValuePerPoint

Actuate also calculates values for XMax and XMin. Setting any of these properties explicitly in Component Editor has no effect.

Propertygroup

Property Description

ChartType-Specific

ChartType ChartScatter

Expressions XValueExp Specifies a point’s x value

YValueExp Specifies a point’s y value

TimeSeries TimeSeries Set to True. Setting this value to True changes the default settings for the X-Axis➛XLabelFormat property based on the value of the TimeSeries➛TickIntervalUnit property.For information about the default format for the X-Axis➛XLabelFormat property, see “Setting the X-Axis group XLabelFormat property for times series detail charts,” later in this section.

502 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Setting optional properties for a scatter chart using AcDetailChart with time seriesSetting the following properties is optional for a scatter chart using AcDetailChart class with time series:

■ SeriesExp and SeriesLabelExp

■ Range and RangeUnit

■ RoundTo

■ TickInterval and TickIntervalUnit

■ XLabelFormat

For detail charts with time series, the following table lists the property groups, properties, and values for the optional properties.

Propertygroup

Property Description

Expressions SeriesExp For a chart with multiple time series, specify to identify each series. For example, for the chart Top Five Stocks shown in the topic “Working with time series in a chart,” in Chapter 14, “Understanding charting concepts,” the SeriesExp is the stock’s ticker symbol.

SeriesLabelExp Appears in the legend. If you do not enter a value, the SeriesExp is used.

TimeSeries Range Sets the range, or the amount of time for which points are plotted, as shown in the following illustration. Points outside the range are not plotted on the chart. The Range and RangeUnit properties do not specify the starting value for the x-axis. For information about how the starting value is calculated, see “Calculating the x-axis starting and ending values,” later in this chapter.

C h a p t e r 1 5 , P r e s e n t i n g d a t a i n a c h a r t 503

RangeUnit Specifies the unit for the Range property. Set to one of the following:ChartDayUnitChartDefaultUnit. For this value, Actuate disregards the Range property and calculates a range for the chart.ChartHourUnitChartMinuteUnitChartMonthUnitChartNumberUnit. For this value, Actuate sets TickIntervalUnit to ChartNumberUnit.ChartQuarterUnitChartWeekUnitChartYearUnit

RoundTo Specifies the unit to use when Actuate calculates and rounds the x-axis’s starting value. Set to one of the following:ChartRoundToInterval. The default value.ChartRoundToRangeFor more information, see “Using the RoundTo property in an example,” later in this section.

TickInterval Specifies the tick interval or the distance between tick marks on the x-axis.Actuate uses the TickInterval and TickIntervalUnit properties to calculate the starting value for the x-axis and the distance between tick marks. For information about how Actuate calculates the starting value, see “Calculating the x-axis starting and ending values,” later in this chapter.

Propertygroup

Property Description

504 D e v e l o p i n g A d v a n c e d e . R e p o r t s

In the TimeSeries group, the Range and RangeUnit properties specify the range, or the amount of time for which points are plotted. The TickInterval and TickIntervalUnit properties specify the interval and units for the ticks, as shown in the following illustration.

TickIntervalUnit Specifies the unit for the TickInterval. Set TickIntervalUnit to one of the following:ChartDayUnitChartDefaultUnit. For this value, Actuate disregards the TickInterval property and calculates a tick interval for the chart based on the data.ChartHourUnitChartMinuteUnitChartMonthUnitChartNumberUnit. Use if the x-axis labels are numbers rather than dates or times. Actuate sets RangeUnit to ChartNumberUnit.ChartQuarterUnitChartWeekUnitChartYearUnit

X-Axis XLabelFormat If the TimeSeries➛TimeSeries property is set to True, the default format for x-axis labels depends on the value of the TimeSeries➛TickIntervalUnit property.For information about the default format for x-axis labels, see “Setting the X-Axis group XLabelFormat property for times series detail charts,” later in this section.

Propertygroup

Property Description

C h a p t e r 1 5 , P r e s e n t i n g d a t a i n a c h a r t 505

Using the RoundTo property in an example

Assume that the earliest date in the data set is 01/15/2000. To plot data for the period from 01/15/2000 to 02/15/2000, set TickIntervalUnit to ChartDayUnit and RangeUnit to ChartMonthUnit. Range is set to 1, the default value. If RoundTo is set to ChartRoundToInterval, Actuate rounds the x-axis’s starting value down to the nearest day, 01/15/2000, and data is plotted for the entire period. If RoundTo is set to ChartRoundToRange, Actuate rounds the x-axis’s starting value down to the nearest month, 01/01/2000. Because the Range is set to 1 and RangeUnit is set to ChartMonthUnit, however, data is plotted only for January. Data is not plotted for February.

For more information about how Actuate calculates the x-axis’s starting value, see “Calculating the x-axis starting and ending values,” later in this chapter.

Setting the X-Axis group XLabelFormat property for times series detail charts

If the TimesSeries➛TimeSeries property is set to True, the default format for x-axis labels depends on the value of the TimeSeries➛TickIntervalUnit. The following table lists the default format for x-axis labels based on the value of the TimeSeries➛TickIntervalUnit.

TickInterval = 1

Range = 7

TickIntervalUnit = ChartHourUnit

RangeUnit = ChartHourUnit

Value of TickIntervalUnit property Default format for x-axis labels

ChartDayUnit mm/dd/yy

ChartHourUnit hh:nn

506 D e v e l o p i n g A d v a n c e d e . R e p o r t s

To change the default format, set the XLabelFormat property to the appropriate format string. For more information about format strings, see Actuate Foundation Class Reference.

Calculating the x-axis starting and ending valuesActuate calculates the starting value for the x-axis based on the x values for the data to plot and the settings of the following properties in the TimeSeries group:

■ Range

■ RangeUnit

■ RoundTo

■ TickInterval

■ TickIntervalUnit

Depending on the settings of these properties, the x-axis’s starting value can be much earlier than the earliest x value. For example, assume the earliest x value is 9:01 and the following is also true:

■ RangeUnit is set to ChartDefaultUnit

■ RoundTo is set to ChartRoundToInterval.

■ TickInterval is set to 5

■ TickIntervalUnit is set to ChartHourUnit

The starting value for the x-axis is 5:00 rather than 9:00 because the earliest x value, 9:01, is rounded down based on the settings of TickInterval and TickIntervalUnit. Also, the starting value must be evenly divisible by the TickInterval.

Overriding the CalculateStartingValue() method

For a detail chart, the starting value for the x-axis is calculated in the CalculateStartingValue() method. You can change the starting value by

ChartMinuteUnit hh:nn:ss

ChartMonthUnit mm/yy

ChartNumberUnit No format

ChartQuarterUnit \Qq yy

ChartWeekUnit mm/dd

ChartYearUnit yy

Value of TickIntervalUnit property Default format for x-axis labels

C h a p t e r 1 5 , P r e s e n t i n g d a t a i n a c h a r t 507

overriding this method. For example, to specify a starting value of 1/15/00, override CalculateStartingValue() as follows:

Function CalculateStartingValue() As VariantCalculateStartingValue = Super::CalculateStartingValue()Dim MyDate As DateMyDate = DateSerial(2000,1,15,0,0,0)CalculateStartingValue = MyDateXMin = MyDate

EndFunction

Overriding the CalculateEndingValue() method

For a detail chart, the ending value for the x-axis is calculated in the CalculateEndingValue() method. You can change the ending value by overriding this method. For example, to specify an ending value of 2/15/00, override CalculateEndingValue() as follows:

Function CalculateEndingValue() As VariantCalculateEndingValue = Super::CalculateEndingValue()Dim MyDate As DateMyDate = DateSerial(2000,2,15,0,0,0)CalculateEndingValue = MyDateXMax = MyDate

EndFunction

Creating scatter charts using AcDetailChart class with time series examplesUsing the stocktrades data source, this section explains the query and property settings used to create examples of scatter charts using AcDetailChart class with single and multiple time series.

For information about times series charts, see “Creating a chart with time series,” and “Setting properties for a scatter chart using AcDetailChart class with times series,” earlier in this chapter.

508 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Creating a scatter chart using AcDetailChart class with a single time series exampleThe following illustration shows a scatter chart using AcDetailChart class with a single time series. This chart plots the price per share for security ABCD over the course of a trading day.

The query for a scatter chart using AcDetailChart class with a single time series example

The report design uses the stocktrades data source. In Query Editor, the SQL statement appears as shown in the following illustration.

The WHERE clause restricts trades.Code to 2 because this value indicates that the value in the column trades.Val is a price per share. The WHERE clause restricts trades.Symbol to ABCD because ABCD is the symbol for the security whose price per share is plotted on the chart.

C h a p t e r 1 5 , P r e s e n t i n g d a t a i n a c h a r t 509

Chart properties for a scatter chart using AcDetailChart class with a single time series example

The chart’s properties specify the appearance of the chart in the report. The following table lists the properties you set specifically for this scatter chart with a single time series example.

Property group

Property Value Description

ChartType-Specific

ChartType ChartScatter Specifies the chart type.

LineStyle ChartSolidPattern

Specifies the line pattern that connects the points on the chart.

LineThickness 1 Specifies the thickness of the line that connects the points on the chart.

ShowLines True Specifies that lines connect the points on the chart.

ShowSymbols True Specifies that a symbol represents each point on the chart.

Expressions XValueExp [trades.TransactionTime]

Specifies the x value for each point. In this example, the value is the transaction time.

YValueExp [trades.Val] Specifies the y value for each point. In this example, the value is the security’s price per share.

SeriesExp In this example, SeriesExp is not needed, because the chart plots a single series.

510 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Creating a scatter chart using AcDetailChart class with multiple time series exampleThe following illustration shows a scatter chart using AcDetailChart class with multiple time series. This chart plots the price per share for securities ABCD, IJKL, EFGH, QRST, and MNOP over the course of a trading day.

TimeSeries TickInterval 1 Specifies one-hour tick intervals, the default value. If TickInterval were set to 2, tick marks would appear along thex-axis at two-hour intervals.

TickIntervalUnit ChartHourUnit

Specifies that tick marks appear along the x-axis in intervals of hours.

TimeSeries True Specifies this is a chart with time series.

Titles TitleText Chart of ABCD price over time

Title of the chart.

X-Axis XTitle Transaction Time

Specifies the x-axis title.

Y-Axis YAxisOrigin ChartAutoOrigin

Specifies that Actuate determines the origin for the y-axis based on the data. For an example in which YAxisOrigin is set to ChartCustomOrigin, see “Understanding limitations of a dual y-axis chart,” earlier in this chapter.

YTitle Price in $ Specifies the y-axis title.

Property group

Property Value Description

C h a p t e r 1 5 , P r e s e n t i n g d a t a i n a c h a r t 511

The query for a scatter chart using AcDetailChart class with multiple time series example

The report design uses the stocktrades data source. In Query Editor, the SQL statement appears as shown in the following illustration.

The WHERE clause restricts trades.Code to 2 because this indicates the value in the column trades.Val is a price per share. The WHERE clause restricts trades.Symbol to ABCD, IJKL, EFGH, QRST, or MNOP because these are the symbols for the securities whose prices are plotted on the chart.

Chart properties for a scatter chart using AcDetailChart class with multiple time series example

The chart’s properties specify the appearance of the chart in the report. The following table lists the properties you set specifically for this detail chart with multiple time series example.

Property group

Property Value Description

ChartType-Specific

ChartType ChartScatter Specifies the chart type.

ShowLines True Specifies that lines connect the points on the chart.

512 D e v e l o p i n g A d v a n c e d e . R e p o r t s

ShowSymbols True Specifies that a symbol represents each point on the chart.

Expressions SeriesExp [trades.Symbol] This chart plots a time series for each security using the security’s ticker symbol. Because no SeriesLabelExp is specified, the SeriesExp is used in the legend.

XValueExp [trades.TransactionTime]

This value is the transaction time, which appears as the x value for each point.

YValueExp [trades.Val] This value is the security’s price per share, which appears as the y value for each point.

Legend LegendPosition ChartLegendRight

Specifies that the legend appears to the right of the chart.

Titles TitleText Top Five Stocks Specifies the chart’s title.

X-Axis XTitle Trade for 2/9/00

Specifies the x-axis title.

Y-Axis YAxisOrigin ChartAutoOrigin Specifies that Actuate determines the origin for the y-axis based on the data. For an example in which YAxisOrigin is set to ChartCustomOrigin, see “Understanding limitations of a dual y-axis chart,” earlier in this chapter.

YTitle Price in $ Specifies the y-axis title.

Property group

Property Value Description

C h a p t e r 1 5 , P r e s e n t i n g d a t a i n a c h a r t 513

Setting properties for a summary chart with times seriesTo design a summary chart with time series requires setting some properties. Other properties are optional. The following sections explain which properties are required and which are optional.

Setting required properties for a summary chart with time seriesTo create a summary chart with time series, you must set the following properties:

■ CategoryExp

■ YValueExp

■ ChartType

■ TimeSeries

For summary charts with time series, the following table lists the property groups, properties, and values for the required properties.

For more information about the properties listed in the preceding table, see Class AcSummaryChart in Actuate Foundation Class Reference.

Propertygroup

Property Description

ChartType-Specific

ChartType Choose one of the following types:Chart2DAreaChart2DBarChart3DAreaChart3DBarChartLineChartTape

Expressions CategoryExp Specifies the x values for each series. If the chart has more than one series, the same x values are used for every series.

YValueExp Specifies the y values for each series. For a summary chart, YValueExp must be an aggregate expression.

TimeSeries TimeSeries True. Setting this value to True changes the default settings for the properties in the X-Axis group.

514 D e v e l o p i n g A d v a n c e d e . R e p o r t s

For summary charts with time series, setting the TimeSeries➛TimeSeries property to True tells Actuate to do the following:

■ Calculate a starting value for the x-axis

■ Calculate an ending value for the x-axis

■ Create labels for the x-axis

■ Set XAxisOrigin to ChartCustomOrigin

■ Set XLabelStyle to ChartCustomXLabels

■ Set XMajorTickStyle to ChartCustomTicks

■ Set XValueSet to ChartXValuePerPoint

Actuate also calculates values for XMax and XMin. Setting any of these properties explicitly in Component Editor has no effect.

Setting optional properties for a summary chart with time seriesSetting the following properties is optional for a summary chart with time series:

■ SeriesExp and Series Label

■ Range and RangeUnit

■ TickInterval and TickIntervalUnit

■ RoundTo

■ XLabelFormat

In the following illustration, the chart displays examples of how the TickInterval, TickIntervalUnit, Range and RangeUnit properties appear.

C h a p t e r 1 5 , P r e s e n t i n g d a t a i n a c h a r t 515

For summary charts with time series, the following table lists the property groups, properties, and values for the optional properties.

Range = 3RangeUnit = ChartMonthUnit

TickInterval = 1TickIntervalUnit = ChartMonthUnit

Propertygroup

Property Description

Expressions SeriesExp For a chart with multiple time series, specify to identify each series.

SeriesLabelExp Appears in the legend. If you do not enter a value, the SeriesExp is used.

TimeSeries RangeRangeUnitRoundTo

For information about the Range, RangeUnit, and RoundTo properties, see “Setting optional properties for a scatter chart using AcDetailChart with time series,” earlier in this chapter.

516 D e v e l o p i n g A d v a n c e d e . R e p o r t s

For more information about the properties listed in the preceding table, see Class AcSummaryChart in Actuate Foundation Class Reference.

TickInterval For a summary chart with time series, TickInterval and TickIntervalUnit are used to calculate the starting value for the x-axis and specify the type of category that is created. As shown in the preceding illustration, for example, if the TickInterval is 1, the default value, and the TickIntervalUnit is ChartMonthUnit, a category is created for every month in the range whether or not data is available for that month. If TickIntervalUnit is set to ChartDefaultUnit, Actuate disregards the TickInterval property and calculates a tick interval for the chart based on the data.For information about how Actuate calculates the starting value, see “Calculating the x-axis starting and ending values,” earlier in this chapter.

TickIntervalUnit Specifies the unit for the TickInterval. Set TickIntervalUnit to one of the following:ChartDayUnitChartDefaultUnit. For this value, e.Report Designer Professional disregards the TickInterval property and calculates a tick interval for the chart based on the data.ChartHourUnitChartMinuteUnitChartMonthUnitChartNumberUnit. Use if the x-axis labels are numbers rather than dates or times. e.Report Designer Professional sets RangeUnit to ChartNumberUnit.ChartQuarterUnitChartWeekUnitChartYearUnit

X-Axis XLabelFormat For information about the XLabelFormat property, see “Setting optional properties for a scatter chart using AcDetailChart with time series,” earlier in this chapter.

Propertygroup

Property Description

C h a p t e r 1 5 , P r e s e n t i n g d a t a i n a c h a r t 517

Creating a summary chart with time series exampleThe following illustration shows a summary chart with time series. This chart plots the sales revenue for three sales offices over a three-month period.

For more information about charts with time series and summary charts, see “Working with time series in a chart,” in Chapter 14, “Understanding charting concepts” and “Creating a chart with time series,” earlier in this chapter.

The query for a summary chart with time series example

This report design uses the sfdata data source. The SQL statement appears in the following illustration.

518 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Chart properties for a summary chart with time series example

The chart’s properties specify the appearance of the chart in the report. The following table lists the properties you set specifically for this summary chart with time series example.

Propertygroup

Property Value Description

ChartType-Specific

ChartType Chart2DBar Specifies the chart type.

Expressions CategoryExp [orders.forecastOrderDate]

Specifies the x value for each set of bars, each series. In this example, CategoryExp is the order date. Because no CategoryLabelExp is specified, the CategoryExp is used to label the x-axis.

SeriesExp [salesreps.officeID]

Specifies the office ID, which plots a series for each office.

SeriesLabelExp [offices.city] Specifies the value used in the legend.

YValueExp Sum([items.pricequote] * [items.quantity])

Specifies the y value, or the height of the bar. In this example, YValueExp is the total sales revenue for the office.

Legend LegendPosition ChartLegendRight

Specifies that the legend appears to the right of the chart.

TimeSeries Range 3 Specifies that the chart plots data for a three-month period.

RangeUnit ChartMonthUnit Specifies that the range unit is one month.

C h a p t e r 1 5 , P r e s e n t i n g d a t a i n a c h a r t 519

TickInterval 1 The default value specifies that each set of bars represents data for a one-month period.

TickIntervalUnit ChartMonthUnit Specifies the tick interval.

TimeSeries True This property must be set for times series charts.

Titles TitleText Sales Per City Specifies the chart’s title.

X-Axis XLabelFormat mmmm yyyy Specifies that x-axis labels display the unabbreviated month name and the four-digit year, such as April 1999.

Y-Axis YAxisOrigin ChartCustomOrigin

This value is used because the origin for the y-axis is specified in the chart’s Finish() method. for information about the Finish() method, see “The Finish() method for a summary chart with time series example,” later in this section.

YLabelFormat $#,##0M Specifies the format string used to format the y-axis labels.

YLabelStyle ChartCustomYLabels

This value is used because YLabelFormat specifies a format string.

Propertygroup

Property Value Description

520 D e v e l o p i n g A d v a n c e d e . R e p o r t s

For more information about the properties listed in the preceding table, see Class AcSummaryChart in Actuate Foundation Class Reference.

The Finish() method for a summary chart with time series example

The chart’s Finish() method specifies the origin and the labels for the y-axis.

Sub Finish( )Dim YMaxTmp As DoubleSuper::Finish( )ComputeYMinMax()YMin = 0

YMax = (Int(YMax/4000000)+1)*4000000YMaxTmp = YMaxYMax = YMax/1000000ComputeLabels( )YMax = YMaxTmp

End Sub

Comparing properties of detail and summary charts with time seriesYou use many of the same properties to create a summary chart with time series that you use to create a detail chart with time series. The tick interval specified by the TickInterval and TickIntervalUnit properties, however, has a different meaning for summary charts than for detail charts. For detail charts, the tick interval is the distance between tick marks on the x-axis. For summary charts, the tick interval is the type of category that is created.

YMajorTickCount

4 Specifies that four major tick marks appear along they-axis.

YMajorTickStyle ChartCustomTicks

This value is used because YMajorTickCount specifies the number of major tick marks.

YTitle Sales Specifies the y-axis title.

Propertygroup

Property Value Description

C h a p t e r 1 5 , P r e s e n t i n g d a t a i n a c h a r t 521

For more information about using the TickInterval and TickIntervalUnit properties to create a summary chart with time series, see “Setting optional properties for a summary chart with time series,” earlier in this chapter.

Limitations of charts with time seriesCharts with time series have the following limitations:

■ Actuate does not support line, bar, and area charts with time series using AcDetailChart class.

■ If the number of labels Actuate creates for the x-axis is more than 250,x-axis labels do not appear.

■ For detail charts, if RangeUnit and TickIntervalUnit are both set to ChartDefaultUnit, Actuate calculates the range and the tick interval based on the data. These values might not be exact.

■ Area detail charts with a hole, or missing data points, do not display correctly.

Creating a hyperchartIn Actuate e.Report Designer Professional and Actuate Viewer, a hyperchart supports double-clicking a chart element to link to report data. In DHTML reports, a hyperchart supports choosing a chart element to link to report data. Chart elements that support links appear in the following table.

For overview information about hypercharts, see “Understanding a hyperchart,” in Chapter 15, “Presenting data in a chart.”

In Component Editor for a chart control, to enable or disable a hyperchart, set its Linking➛HyperChart property to one of the values in the following table.

Chart element Description

Chart control Full chart display area, surrounding, but not including, the specific data point, series, and category elements

Category Category data, such as a bar in a bar chart and a pie segment in a pie chart

Data point Specific point on line chart, section in pie chart, bar in bar chart where a data value appears

Series Series data, such as a line in a line chart and a bar in a bar chart

522 D e v e l o p i n g A d v a n c e d e . R e p o r t s

These settings do not affect a link for the chart control itself for which you set the Linking➛LinkExp property. These settings affect only the elements in the chart control.

Depending on the type of chart and its data values, to create a link from a specific chart element, use the Linking group properties, which appear in the following table.

Property value Description

AutoHyperChart This value is the default setting for a chart control, which enables creating a link from a chart element to report data. This setting enables a hyperchart by detecting if any one of the following properties contains a link expression. If none of these properties contains a link expression, the hyperchart is disabled:■ CategoryLinkExp■ PointLinkExp■ SeriesLinkExp

HyperChartDisabled Disables links from chart elements to report data

HyperChartEnabled Enables hyperchart behavior without creating link expressions in CategoryLinkExp, PointLinkExp, or SeriesLinkExp. Use this setting if you overwrite Actuate Basic functions to programmatically specify a link’s destination for CategoryLinkExp, PointLinkExp, or SeriesLinkExp.

Property Description

CategoryLinkExp Specifies the link expression to which a category element links

LinkExp Specifies the link expression to which a chart control links

PointLinkExp Specifies the link expression to which a data point element links

SeriesLinkExp Specifies the link expression to which a series element links

C h a p t e r 1 5 , P r e s e n t i n g d a t a i n a c h a r t 523

A link expression for a hyperchart can contain the keywords described in the following table, which support specific linking behavior.

An example of the syntax for a CategoryLinkExp link expression is:

"detail.roi;1#SalesDetail::OfficeTitleFrame::txtOfficeName="""& Category & " Office"& """"

where the txtOfficeName text control’s value, such as Boston, substitutes for Category if the user chooses a category chart element with the value Boston.

For more information about hyperlinks and link expression syntax, see “About the LinkExp property,” in Chapter 12, “Working with frames and controls.”

A report developer can override the Actuate Basic functions, Category and Series, to change the linking behavior for these keywords. For more information about Category and Series functions and methods GetCategoryLink( ) and GetSeriesLink( ) in Class AcChart, see Actuate Foundation Class Reference.

How to set link expression properties for a hyperchart

1 In a report design, double-click a chart control.

<Chart name>—Component Editor appears.

2 Set Linking➛HyperChart to AutoHyperChart.

3 To enable a hyperchart, in the Linking group, create a link expression for at least one of the following properties:■ CategoryLinkExp■ PointLinkExp■ SeriesLinkExp

Keyword Description

Category Retrieves the Expressions➛CategoryLabelExp value for a category chart element to support linking to that data value in a report

Series Retrieves the Expressions➛SeriesLabelExp value for a series chart element to support linking to that data value in a report

Category & Series If you use both keywords, Actuate retrieves the data value at the intersection of the Expressions➛CategoryLabelExp and the Expressions➛SeriesLabelExp, which is the value for a data point element, to support linking to that data point in a report.

524 D e v e l o p i n g A d v a n c e d e . R e p o r t s

To create a link expression:

1 Select a property.

2 Choose Builder.

Hyperlink Builder appears.

3 In URL, type a link expression to connect to a link, external or internal to the report, as shown in the following illustration.

Choose OK.

The link expression appears in <Chart name>—Component Editor.

4 In <Chart name>—Component Editor, choose Close.

Rendering charts on Windows and UNIXIf you use both Windows and UNIX platforms to deploy reports, choose fonts that are available on both Windows and UNIX when you design the report. Unavailable fonts can adversely affect the appearance of report documents.

For the charting engine to render the fonts, the referenced fonts must be available to the JVM used for the chart classes. Making the fonts available differs by platform:

■ On Windows, referenced fonts should be installed in the standard fonts folder for the operating system such as \Winnt\Fonts.

■ On UNIX, referenced fonts should be installed in the $JAVA_HOME/jre/jre/lib/fonts directory.

Actuate uses default fonts for those chart elements that use a font not found on the operating system. The default font that Actuate uses is dependent on the

C h a p t e r 1 5 , P r e s e n t i n g d a t a i n a c h a r t 525

locale specified when loading the chart classes. For each locale, you must have at least one font. For UNIX and Windows output to look identical, the fonts listed in the following table must be available to the UNIX JVM.

To view charts on UNIX, you need an x-server. You can use the virtual x-server Xvfb that Actuate ships. Xvfb supports a number of fonts. Alternatively, you might need to install your own fonts.

If a specific font is not available, you can use one of the fonts listed in the following table.

Locale specified Default fonts

For all languages not specified later in this table

arial.ttfarialbd.ttfarialbi.ttfariali.ttf

Japanese msgothic.ttcmsmincho.ttc

Korean gulim.ttcbatang.ttc

Chinese, simplified simsun.ttc

Chinese, traditional mingliu.ttc

526 D e v e l o p i n g A d v a n c e d e . R e p o r t s

C h a p t e r 1 6 , D e s i g n i n g a p a g e l a y o u t 527

C h a p t e r

16Chapter 16Designing a page layout

This chapter contains the following topics:

■ About pages

■ Setting paper size, orientation, and margins

■ Setting up a page sequence

■ About subpages

■ Placing a subpage in a report design

■ About flows

■ Specifying headers and footers

■ Designing letterheads, patterns, and other effects

■ About Reportlets

■ Setting properties for a Reportlet

■ Extracting a Reportlet using a search URL

■ About printing and viewing a report across platforms

■ Designing a report to print and display in multiple platforms

■ Testing your report design

■ Understanding font issues

528 D e v e l o p i n g A d v a n c e d e . R e p o r t s

About pagesA page is a component that specifies the visual design of a page in the report. A page can contain the following components:

■ Flows, which determine the printable area of the page. Each page contains at least one flow.

■ Controls, which are optional and display text, numbers, images, or graphic shapes. For example, you can include controls to display a company name and logo at the top of the page and page numbers at the bottom of the page.

■ Frames, which are optional and provide a way to group the controls. You can also place controls directly on the page without using a frame.

In e.Report Designer Professional, you can design a report with right-to-left orientation. You can also display the e.Report Designer Professional and Design Editor windows with right-to-left orientation. For more information about designing reports with right-to-left orientation, see Chapter 5, “Designing e.reports with right to left orientation,” in Working with Multiple Locales.

For more information about flows, see “About flows,” later in this chapter. For more information about frames and controls, see Chapter 12, “Working with frames and controls.”

Understanding what pages do when you run a reportWhen you run a report, e.Report Designer Professional builds frames to display the data. As each frame is created, e.Report Designer Professional places it in the flow on the current page, starting from the top of the flow and aligning each frame with the left edge of the flow.

If a frame that does not contain dynamic text controls is too long to fit in the current flow, e.Report Designer Professional’s default behavior is to place it at

Frame with text and image controls

Flow

Control

ABC Inc.

1

C h a p t e r 1 6 , D e s i g n i n g a p a g e l a y o u t 529

the top of the next flow, which might be on the same page or another page. If you specify that e.Report Designer Professional should split a long frame, or if a frame that contains dynamic text controls does not fit in a flow, e.Report Designer Professional splits the frame and its contents over multiple flows or pages. For more information about splitting frames, see “Controlling how a frame and its contents fit in multiple pages” in Chapter 13, “Working with a dynamic text control.”

The sequence of events is somewhat different when your report design includes subpages. For more information about subpages, see “About subpages,” later in this chapter.

About types of page layouts Actuate providesActuate e.Report Designer Professional provides several standard page components for the most commonly used page styles. In most cases, one of the standard page styles shown in the following illustration meets your needs.

If you want the report content to determine the page size, select dynamic page size. Selecting dynamic page size adjusts a report page’s height to accommodate data added to the report at run time. Report pages translated into pages of DHTML and viewed on the web retain the page-oriented features such as page-level security.

If you select dynamic page size, all data appears on the same page of the report unless one of the following applies:

■ An explicit page break appears in the report such as a page break in a Before section.

■ Page-level security forces a page break in the report.

■ If the data content would exceed the maximum page length, a page break appears in the report to limit the length.

At design time, the maximum size for a report’s dynamic page size is 200 inches tall. Windows NT, Windows 2000, Adobe Acrobat 4.0, and Actuate supported web browsers display report pages up to the maximum 200 inches tall.

8.5” x 11” 8.5” x 14” (legal) A4, A5, B4, B5

530 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Limitations for the report’s dynamic page size include the following:

■ On Windows 98:■ Actuate Viewer, e.Report Designer Professional, and the LRXs display

report pages up to a maximum of approximately 22.75 inches wide and 22.75 inches tall. If you try to open report designs created in Windows NT and Windows 2000 that contain components larger than 22.75 inches, an error message appears.

■ Actuate supported browsers can display large reports, but the operating system limit the maximum printable dimensions to 129 inches by 129 inches.

■ The maximum page size for Adobe Acrobat 3.0 is 45 inches by 45 inches.

■ Because increasing the page size increases the number of controls you can add to a page, you might experience a degradation in report generation performance for pages that contain many controls.

For information about setting the dynamic page size, see “How to set the paper size,” later in this chapter. For more information about the Actuate classes and dynamic page size, see the entries for AcPage, AcBasePage, AcSubPage, and AcPageList in Actuate Foundation Class Reference.

For information about how to add a page to your report design, see “Setting up a page sequence,” later in this chapter.

If none of these page styles meets your needs, you can modify a page layout using Design Editor. For information about how to design a page layout with Design Editor, see “About flows,” “Specifying headers and footers,” and “Designing letterheads, patterns, and other effects,” later in this chapter.

You can also use a page component from a library or from another report design, or you can define a new page class. For information about defining a new class, see “About the Actuate Foundation Classes” in Chapter 2, “Understanding the design process.”

Page orientation and printingThe layout dimensions of a report determine the report’s page orientation when it is printed. Go to the PageStyle property in Component Editor, and enter a height and width in Size to set the page orientation. If the page layout of a report is taller than it is wide, for example, 11 inches tall by 8.5 inches wide, the report prints in portrait mode. If the report layout is wider than it is tall, for example, 11 inches wide by 8.5 inches tall, the report prints in landscape mode. Be sure to adjust the report’s flows and controls to fit on the page orientation you choose.

The page orientation option is maintained by the operating system and the printer driver.

C h a p t e r 1 6 , D e s i g n i n g a p a g e l a y o u t 531

Byfr.roi and the other reports in the \Program Files\Actuate7\Erdpro\Examples directory use landscape page orientation. If you use components from the report object library file Byfr.rol in a report design, your report should use landscape page orientation. If your report uses portrait page orientation, some components might be too wide to fit on the page. Portrait page orientation is the default value for a report design created with the report wizards.

If you want the report content to determine the page size, you can select dynamic page size in Page Setup. For more information about dynamic page size, see “About types of page layouts Actuate provides,” earlier in this chapter, and “How to set the paper size,” later in this chapter.

Setting paper size, orientation, and marginsUse Page Setup to set the paper size, page orientation, and margins.

The units for the height, width, and margins are specified on Options—Units. For information about Options—Units, see “Customizing units of measurement” in Chapter 5, “Customizing the design environment.” For information about specifying the default values for page size and margins, see “Setting the default page size and margins” in Chapter 4, “Using Design Editor.”

532 D e v e l o p i n g A d v a n c e d e . R e p o r t s

The selected component or slot determines which page or pages are affected by the settings in Page Setup, as shown in the following table.

If the selected component or slot does not appear in the preceding table, the first page, page list, or report component that contains the selected component or slot is used. If no component or slot is selected, the top-level report component’s page list is used.

To support a page increasing its height and width to fit its contents, you can enable dynamic sizing. If your report design contains a crosstab, for example, you can enable the height and width to increase to contain the contents of the crosstab. For a selected page component:

■ Selecting Dynamic for Height implicitly sets the Dynamic Size and Position➛CanIncreaseHeight property to True. If you select Dynamic, the Size and Height settings do not affect the page size.

■ Selecting Dynamic for Width implicitly sets the Dynamic Size and Position➛CanIncreaseWidth property to True. If you select Dynamic, the Size and Width settings do not affect the page size.

To use Page Setup with a component in a library, open the library directly and select the component. You cannot use Page Setup with a view of an included library.

How to set the paper size

1 In e.Report Designer Professional, choose Tools➛Page Setup.

2 In Page Setup, complete the following tasks:■ Select a size from the drop-down list.

If you select a… The settings in Page Setup affect the…

Page component Page.

Empty page slot Page.e.Report Designer Professional creates the page component.

Page list component Page or pages in the page list.e.Report Designer Professional creates any missing page components.

Empty page list slot Page or pages in the page list.e.Report Designer Professional creates the page list and page components.

Report component Page or pages in the page list.e.Report Designer Professional creates any missing page list or page components.

C h a p t e r 1 6 , D e s i g n i n g a p a g e l a y o u t 533

■ To specify a page height, complete one of the following tasks: - In Height, supply a value.- Select Dynamic.

■ To specify a page width, complete one of the following tasks: - In Width, supply a value.- Select Dynamic.

For more information about dynamic page size, see “About types of page layouts Actuate provides,” earlier in this chapter.

3 Choose OK.

How to set the page orientation

1 In e.Report Designer Professional, choose Tools➛Page Setup.

2 In Page Setup, select Portrait or Landscape.

3 Choose OK.

How to set the margins

1 In e.Report Designer Professional, choose Tools➛Page Setup.

2 In Page Setup, enter the top, bottom, left, and right margins in the Top, Bottom, Left, and Right fields.

3 Choose OK.

For more information about setting the margins, see “Setting page margins,” later in this chapter.

534 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Setting up a page sequenceThe first step in specifying the page layouts for your report is to decide whether you want to use the same layout for every page. Actuate e.Report Designer Professional provides several page list components, which you use to specify the following page layouts:

■ Simple page list. Same page layout for all pages in the report.

■ Title/body page list. One page layout for the title area of the report and another layout for the rest of the report.

■ Left/right page list. Two alternating page layouts for odd- and even-numbered pages.

You can design a different page sequence by defining a new page list component using Actuate Basic. For information about how to define a new class, see “About the Actuate Foundation Classes” in Chapter 2, “Understanding the design process.”

The first steps in defining the page layouts of a report are the following:

1 Place a page list component in the PageList slot of a report component.

2 Place one or more pages in the page list.

3 Place a flow on the page.

The procedures in this section describe how to place standard page components into a page list. Pages from your component library or another design can also be placed into a page list. After you place a page, you add the flow component. Then you modify its appearance using the procedures described later in this chapter.

You can create a report by choosing one of the following from Create New Report:

■ Quick Report Wizard

■ Listing Report Wizard

■ Blank Report

If you create a report this way, e.Report Designer Professional creates the page list and page components.

How to use one page layout for all pages

1 Drag the page list component from the Pages palette, and drop it in the PageList slot.

C h a p t e r 1 6 , D e s i g n i n g a p a g e l a y o u t 535

Select Component appears.

2 In Select Component, select Simple Page List. Choose OK.

3 Drag a page component from the Pages palette, and drop it on the PageStyle component.

4 Add a flow component to the Content slot of the PageStyle component. For information about flows, see “Placing a flow on a page or subpage,” later in this chapter.

5 Resize the flow to modify the layout of the page.

536 D e v e l o p i n g A d v a n c e d e . R e p o r t s

How to use a layout that includes a title page and a body page

1 Drag the page list component from the Pages palette, and drop it in the PageList slot.

2 In Select Component, select Title/Body Page List. Choose OK.

Two slots, TitlePage and BodyPage, appear in the structure pane.

3 Drag a page component from the Pages palette, and drop it into the TitlePage slot.

4 Drag a flow component and drop it into the Content slot of the TitlePage component. For information about flows, see “Placing a flow on a page or subpage,” later in this chapter.

C h a p t e r 1 6 , D e s i g n i n g a p a g e l a y o u t 537

5 Drag a page component from the Pages palette, and drop it into the BodyPage slot.

6 Drag a flow component and drop it into the Content slot of the BodyPage component. For information about flows, see “Placing a flow on a page or subpage,” later in this chapter.

7 Select the TitlePage component in the structure pane. Resize the flow to modify the layout of the first page of your report.

8 Select the BodyPage to modify the layout of the other pages of your report.

For information about how to develop a layout that separates the title page from the rest of the report using a sequential section, see “How to create a title page on its own page,” later in this chapter.

How to create a title page on its own page

You can separate the title page from the pages containing the data of the report by using a sequential section rather than the TitleBodyPageList component.

The sequential section contains the Pagination➛PageBreakAfter property that can be set to True, which forces a page break after this section.

To create a report with the title page on its own page, do the following:

1 If you have an existing report section in your report, move this to Scratch Pad to create an area for the sequential section.

2 Drag a sequential section component and drop it in the top-level component of your report.

3 Drag a frame component and drop it in the content slot.

4 For the frame, in Component Editor, set the Pagination➛PageBreakAfter property value to True.

5 From the Controls palette, drag a label control and drop it into the frame, or from the Drawing/Graphics palette, drag an image control and drop it into the frame, to create the title you wish.

538 D e v e l o p i n g A d v a n c e d e . R e p o r t s

6 From Scratch Pad, drag the report section that you earlier placed there. Drop it in the sequential section.

The report section positions itself correctly below the sequential section and below the frame holding the title information.

How to alternate left and right page layouts

1 Drag the page list component from the Pages palette, and drop it in the PageList slot.

Select Component appears.

C h a p t e r 1 6 , D e s i g n i n g a p a g e l a y o u t 539

2 Select Left/Right Page List. Choose OK.

Two slots, LeftPage and RightPage, appear in the structure pane.

3 Drag a page component from the Pages palette, and drop it into the LeftPage slot.

4 Add a Flow component to the LeftPage component’s Content slot. For information about flows, see “Placing a flow on a page or subpage,” later in this chapter.

5 Drag a Page component from the Pages palette, and drop it into the RightPage slot.

6 Add a Flow component to the RightPage component’s Content slot. For information about flows, see “Placing a flow on a page or subpage,” later in this chapter.

7 Select the LeftPage component in the structure pane. Resize the flow to modify the layout of the page.

8 Select the RightPage component in the structure pane. Resize the flow to modify the layout of the page.

How to create a final, separate page

To create a final, separate page for your report, see “How to create a title page on its own page,” earlier in this chapter.

Then, do the following:

1 Select in the structure pane the frame that contains the text for the final page.

2 Select Tools➛Slot Information.

540 D e v e l o p i n g A d v a n c e d e . R e p o r t s

The Structure Reference List appears.

3 In the Structure Reference List, select the first item in the list box in the Contents section. This item is the frame containing the text for the final page.

The Structure Reference List contains information about the relationship of components to one another. It appears when the container component can contain multiple, unordered references. It is particularly useful for moving frames to different locations in a report design.

4 Click on the down arrow, which is to the left of the list box.

This moves the first item into the second position in the list box. This selection also causes the FinalPageFrame to move into a position below that of the rest of the report.

5 Choose Close.

6 In Component Editor, in the Pagination group properties, set PageBreakBefore to True for FinalPageFrame.

C h a p t e r 1 6 , D e s i g n i n g a p a g e l a y o u t 541

About subpagesEvery section in a report design can optionally have an associated subpage. A subpage is just like a page except that it fits into a flow on the active page. The active page is the page in the report currently being generated when the subpage starts.

A subpage grows longer or shorter to accommodate the data.

You usually use a subpage when you want to change the page style for the contents of a section in the middle of a page. A bank statement, for example, could be mostly printed in one column, but the list of checks could appear in two columns.

Like a page, a subpage contains one or more flows and can contain frames and controls. In a parallel section, each flow in the subpage corresponds to one of the reports in the section’s Reports slot. For example, you might place two subreports into a subpage with two flows. Each subreport would then use one of the flows. For more information about how to determine which flow is used, see “Assigning flows to parallel subreports” in Chapter 11, “Working with sections.”

Placing a subpage in a report designThe subpage is optional. You can place a subpage component in the Subpage slot of one of the following types of sections:

542 D e v e l o p i n g A d v a n c e d e . R e p o r t s

■ Sequential

■ Conditional

■ Parallel

■ Report

■ Group

If you do not place a subpage in one of the sections named above, the section uses its regular page component for its design.

How to place a subpage in a report design

1 Drag a subpage component from the Pages palette and drop it in the Subpage slot of a section.

2 Design the layout of the subpage.

After you have placed the subpage component into the Subpage slot, you design the layout of a subpage using the same procedures as for a regular page. For more information about designing a page layout, see the procedures later in this chapter.

You can also drag a subpage from a library or from another report design. The Subpage slot, however, receives only a subpage component.

About flowsA flow is a component that defines a printable area on a page or subpage. Each flow is a rectangular area. In its properties, you can specify a size, background color, and other visual characteristics. You use flows to determine the margins and the number of columns on a page.

The maximum size of the printable area on the page is determined by the printer. If a control extends beyond the printable area, it is truncated when printed, even if it is completely in the flow.

The following illustration shows an approximation of how pages, flows, and frames interact.

Note that data controls must be placed inside a frame. Other controls, such as those with which you design a page header, can lie outside a frame and outside the flow, as well.

C h a p t e r 1 6 , D e s i g n i n g a p a g e l a y o u t 543

Placing a flow on a page or subpageYou place a flow on a page or subpage in the same way you place any other component in the report design. You can either drag-and-drop or click and draw.

How to place a flow on a page or subpage

1 Select the page or subpage component in the structure pane.

2 Choose View➛Options.

Options—Design Editor appears.

3 Choose Design Editor.

Options—Design Editor appears.

Be sure Outline Components is selected to display the outlines of the paper edge, the flow edge, the frames, and the components.

4 Close Options—Design Editor.

5 If necessary, use the toolbar’s Zoom control to reduce the view of the page so that you can see the whole work area.

6 In the Pages palette, choose the flow component.

Page edge

Margin of flow

Frame edge

Controls

Margin of frame (frame border)

Flow edge

544 D e v e l o p i n g A d v a n c e d e . R e p o r t s

7 Move the mouse pointer to the layout pane. Draw a flow in the size you want by holding down the mouse button and dragging from one corner to another.

You can also drag the flow component from the Pages palette and drop it into the layout or structure pane, then resize the flow if necessary.

Setting page marginsTo specify the margins in a page layout, work with the height and width of the flow. The shorter and narrower the flow, the larger the margins.

How to set margins on a page or subpage

1 Select the page or subpage component in the structure pane.

2 If necessary, use the toolbar’s Zoom control to reduce the view of the page so that you can see the whole area you want to work with.

3 In the layout pane, select the flow.

4 Use the handles to drag the flow edges with the mouse until the margins are the width you want.

C h a p t e r 1 6 , D e s i g n i n g a p a g e l a y o u t 545

5 To make a more specific adjustment, set the flow’s Size properties.

For more information about how to set a property, see “Setting properties of components” in Chapter 4, “Using Design Editor.”

Setting up multicolumn page layoutsTo design a page layout with more than one column, place more than one flow on the page. Each flow is a column.

You can set a Page component’s Pagination➛BalanceFlows property to True to balance the content among multiple flows.

How to set up multicolumn page layouts

1 Select a page or subpage component in the structure pane.

2 If necessary, use the toolbar’s Zoom control to reduce the view of the page so that you can see the whole area you want to work with.

3 Place the desired number of flows on the page, following the steps in “How to place a flow on a page or subpage,” earlier in this chapter.

4 Resize the flows as needed, following the steps in “How to set margins on a page or subpage,” earlier in this chapter.

Drag any handle to resize

546 D e v e l o p i n g A d v a n c e d e . R e p o r t s

5 Align the flows as needed, following the steps in “Aligning and centering components” in Chapter 4, “Using Design Editor.”

6 Balance the content in flows:

1 Double-click the Page component.

Page—Component Editor appears.

2 Set Pagination➛BalanceFlows property to True.

Choose Close.

Specifying headers and footersYou can specify headers and footers by placing components in two types of locations:

■ In a component—page

■ In a slot—PageHeader or PageFooter

When you specify headers and footers by placing components on a page or subpage, the headers and footers are associated with that particular page layout. When you use the PageHeader and PageFooter slots, the headers and footers are associated with a particular set of data. Each report section and group section has its own PageHeader and PageFooter slots, so you can associate different headers and footers with each part of a report.

Specifying headers and footers in a page layoutHeaders and footers in the layout of a page or subpage component have the following characteristics:

■ They are associated with that particular page layout.

■ They print or appear on every page that uses that layout.

■ They appear outside the flow.

For example, suppose you are using a left/right page list. You can place a page number control on the LeftPage and RightPage components to display page numbers and place an image control on the RightPage component to display a company logo on every odd-numbered page in a report.

C h a p t e r 1 6 , D e s i g n i n g a p a g e l a y o u t 547

For information about isolating a component in Design Editor, such as the pages shown, see “Managing multiple Design Editor windows” in Chapter 4, “Using Design Editor.”

For more information about left/right page lists, see “Setting up a page sequence,” earlier in this chapter.

How to specify headers and footers in a page layout

You can use frames or controls to add a header or footer to a page layout:

1 Select a page or subpage component in the structure pane.

2 If necessary, use the toolbar’s Zoom control to reduce the view of the page so that you can see the whole area you want to work with.

3 Place frames or individual controls outside the flow.

If you want to place data controls on your page, however, you must place them inside a frame but outside the flow. For more information about data controls, see “About controls” in Chapter 12, “Working with frames and controls.”

For information about how to place controls in a report design, see “Placing controls in a report design” in Chapter 12, “Working with frames and controls.”

4 Specify a value for each control.

For more information about specifying the value of a control, see “Setting display values for controls” in Chapter 12, “Working with frames and controls.”

548 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Specifying headers and footers using slotsHeaders and footers in the PageHeader and PageFooter slots have the following characteristics:

■ They are associated with a group of data or a report section, depending on whether the slots belong to a group section or a report section.

■ They print or appear along with the component that contains the slots.

■ They appear inside the flow, in a frame.

■ They can contain data controls to display data from the data stream.

For example, you can place a frame in the PageHeader slot of a group section component to display a running header as that group section displays or prints on multiple pages. If you use the PageHeader and PageFooter slots of both a group section and the report section that contains it, both sets of headers and footers appear, as shown in the following illustration.

How to specify headers and footers using slots

1 Do one of the following:■ Choose one of the following from the menu bar:

- Insert➛Header➛Report Page Header.- Insert➛Footer➛Report Page Footer.- Insert➛Header➛Group Headers.- Insert➛Footer➛Group Footers.

If you choose Insert➛Header➛Group Headers or Insert➛Footer➛Group Footers, Sorting and Grouping appears. For

Report page

Component structure

Page header for report

Page header for data group

Head

10.00

20.00

30.00

40.00

Head

10.00

20.00

30.00

40.00

C h a p t e r 1 6 , D e s i g n i n g a p a g e l a y o u t 549

more information about using Sorting and Grouping to add Before, After, Page Header, or Page Footer frames, see “Setting grouping options” in Chapter 11, “Working with sections.”

■ Drag a frame component and drop it in the PageHeader or PageFooter slot of a report section or group section.

You can drag a new frame from the Structure palette or use a frame from a library or from another report design.

2 Add controls to the frame, and associate them with data or another type of value.

For more information about placing controls in frames and associating them with values, see Chapter 12, “Working with frames and controls.”

3 To show the header on the first page, set the report or group section’s Pagination➛ShowHeaderOnFirst property to AsPageHeader or AsColumnHeader: ■ Choosing AsPageHeader causes the header to appear before the Before

frame.■ Choosing AsColumnHeader causes the header to appear after the

Before frame.

4 To show the footer on the last page, set the report or group section’s ShowFooterOnLast property to True.

For more information about how to set a property, see “Setting properties of components” in Chapter 4, “Using Design Editor.”

550 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Adding page numbersPage numbers can appear in text format or in number format. A page number displayed in text format lets you add words or numbers around a page number value. An example of a page number in text format follows:

Page 2-23

A page number built with a numeric format lets you perform calculations on the number itself. An example of a page number in numeric format is a page number that starts with a 3 on the first page.

To add a text or numeric page number to a report design, place a text control or numeric control where you want the page number to appear in your report.

For more information about placing page numbers see “How to place a page number on all pages except the first page” and “How to place a page number on each page,” later in this chapter.

How to place a page number on each page using the page number control

1 Choose the PageStyle component in the structure pane.

2 Do one of the following:■ Choose Insert➛Page Number, and drop the control in the appropriate

location on the page.■ Drag the page number control from the Pages palette and drop it in the

appropriate location on the page.

3 To display only the page number, choose VisiblePageNumber or ActualPageNumber from the drop-down list for the PageNumberType property. To display the page number relative to the total number of pages, such as Page 41 of 78, choose VisiblePageNofM or ActualPageNofM.

C h a p t e r 1 6 , D e s i g n i n g a p a g e l a y o u t 551

4 Choose OK.

For more information about adding page numbers using the page number control, see Chapter 8, “Designing a report with page-level security,” in Programming e.Reports.

How to place a page number on all pages except the first page

1 Drag a frame component and drop it into the PageHeader slot.

2 To place a page number in text format in the PageHeader frame, drag a text control from the Controls palette and drop it into the PageHeader frame.

3 In Component Properties, set the text control’s ValueExp property. For example:

"Page 2-" + PageNo$()

Following is how this text control appears in the report object instance (.roi) file:

Page 2-23

Users could interpret this page number as “Section 2, Page 23.”

4 Choose OK.

5 Double-click Content-Report in the structure pane.

6 In Component Editor, set the Pagination➛ShowHeaderOnFirst property to NoHeaderOnFirst.

7 Choose Close.

How to place a page number on each page

To place a text or numeric page number directly on each page, outside of a page header or footer, do the following:

1 Drag a text control or numeric (integer) control to the structure pane and drop it directly on a page component.

2 If you placed a text control, set ValueExp property to PageNo$( ). If you placed a numeric control, set the ValueExp property to PageNo( ).

552 D e v e l o p i n g A d v a n c e d e . R e p o r t s

3 In the layout pane, place the control where you want it on the page.

4 Choose OK.

When the report is generated, the page number appears in the location on the page where you placed it.

For more information about how to place a control in a report design and set the ValueExp property, see Chapter 12, “Working with frames and controls.”

For more information about the PageNo method and building more complicated page numbering systems, see Actuate Foundation Class Reference.

Adding a date/time stampTo add the date or time to a report design:

1 Choose Insert➛Report Run Date, and place the control in the appropriate location in the report design.

2 In Date Format, choose the appropriate format for the date or time, and choose OK. To display the date and time, choose General Date.

Alternatively, you can follow steps similar to those you followed in “Adding page numbers,” earlier in this chapter. In general, you place the control, and then you modify the control’s ValueExp property.

Following are the steps to add a date/time stamp to your report:

1 Drag a date/time control from the Controls palette and drop it in the PageHeader or PageFooter frame or to a page component.

2 Set the control’s ValueExp property to Now( ). The default value for a control’s Format property is General Date.

3 Set the Format property by choosing a format from the drop-down list in Component Editor.

After the factory processes are complete, the Now( ) function displays the current date or time, drawn from the operating system.

C h a p t e r 1 6 , D e s i g n i n g a p a g e l a y o u t 553

The setting of the Format property determines whether the date, time, or both appear and in what format. To display the date and time, set Format to General Date.

To perform calculations on the date in your report, see information about the Date Serial function and other functions in Actuate Basic Language Reference.

To specify other formats for your date/time stamp, see the Format and Format$ functions in Actuate Basic Language Reference.

For more information about date types, see Chapter 15, “Understanding variables and data types,” in Programming e.Reports.

For more information about how to place a control in a report design and set the ValueExp property, see Chapter 12, “Working with frames and controls.”

Designing letterheads, patterns, and other effectsYou can place frames or controls anywhere on a page or subpage, as well as in the header and footer areas.

If you want to associate words or graphics with a particular set of data, place frames and text or graphics controls in the PageHeader or PageFooter slots. If you want to associate words or graphics with a particular page layout, place the frames and text or graphics controls in a page or subpage.

Drawing controls enable you to draw decorative shapes in the margins. Image controls let you add a company logo and background pattern to your page layout.

Placing a title or logo on a pageTo place a title or logo on a page layout, follow the steps in “Specifying headers and footers in a page layout,” earlier in this chapter.

To display a title, drag a label control and drop it into the page or subpage.

To display a logo or other image, use an image control. Design Editor lets you specify the file name of an image.

554 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Adding a background pattern to a pageYou can place a pattern or text in the background of a page layout. A background pattern is a graphic image that lies partly or entirely inside the printable area of the page. The report prints on top of the pattern. This type of pattern is sometimes called a watermark.

How to add a background pattern to a page or subpage

1 Select a page or subpage component in the structure pane.

2 If necessary, use the toolbar’s Zoom control to reduce the view of the page so that you can see the whole area you want to work with.

3 Place an image control on the page so that it lies partly or entirely inside the flow.

Be sure that the BackgroundColor for a frame that is positioned over the watermark is set to Transparent Color. Otherwise, the watermark might cover the frame’s content.

For information about how to place controls in a report design, see “Placing components in a report design” in Chapter 4, “Using Design Editor.”

Background pattern

Head Total

DRAFTData 10.00

Data 10.00

Data 10.00

Flow

Image

C h a p t e r 1 6 , D e s i g n i n g a p a g e l a y o u t 555

4 Specify the path name of the file that contains the graphic you want to use.

The image must be layered on top of the flow, or else the flow’s background color obscures the image. When you first place the image, the default behavior is to place the image layer on top. The image should always remain on top of the flow. You can place more frames and controls on top of the image, however. For more information about layering components, see “Layering components” in Chapter 4, “Using Design Editor.”

About ReportletsA Reportlet is a portion of an Actuate report extracted from a report document located in a volume on an iServer using a search URL. One use is to incorporate the Reportlet into a web page. When a user opens the web page, the Reportlet content appears integrated with the web page.

Using Reportlets requires the following:

■ Both the report object instance (.roi) file and the report object executable (.rox) file must be located in an Encyclopedia volume.

■ To extract a Reportlet from the ROI requires specific syntax for the Actuate Active Portal directive, the search URL.

■ The user must have access to the web server and iServer.

■ The web browser must be capable of displaying the HTML web page and the container in which the Reportlet appears.

The following illustration contains an example of page 1 of Detail.roi as a Reportlet contained in a web page. This example uses the IFRAME tag to embed the Reportlet in the web page.

Web page Frame containing a Reportlet

556 D e v e l o p i n g A d v a n c e d e . R e p o r t s

The web page that appears in the preceding illustration contains the following source HTML:

<HTML><HEAD><TITLE>Displaying a Reportlet in a web page</TITLE></HEAD><BODY><CENTER><H2><FONT SIZE=6>Displaying a Reportlet in a web page</FONT></H2></CENTER>

<IFRAME SRC="http://siamese:8700/acweb/servlet/ViewPage?page=1&format=Reportlet&name=/Reportlets/detail.roi&version=001&type=roi&scalingFactor=60" NAME "A" HEIGHT=250 WIDTH=80% HSPACE=10 SCROLLING=YES ALIGN=RIGHT>Your browser cannot display iFrames </IFRAME>

<P><FONT SIZE=5>The frame that appears on this web page enables scrolling to view the content of the Reportlet.</FONT></BODY></HTML>

The HTML formatting tags in a Reportlet are different from the tags in a DHTML report viewed in a browser. The Reportlet HTML does not contain <HTML>, </HTML>, <HEAD>, </HEAD>, <BODY>, and </BODY> tags. Reportlets do not contain JavaScript. The Reportlet’s <DIV> and </DIV> tags designate the divisions between specific portions of the Reportlet content and enable adding a Reportlet to a web page.

From a report object instance (.roi) file you can extract each of the following as a Reportlet:

■ Report section

■ Group section

■ Sequential section

■ Page

■ Frame

From an report object instance (.roi) file, you cannot extract the following as Reportlets:

■ Controls

You can add controls to a frame and extract the frame as a Reportlet.

■ Flows

■ Parallel sections

C h a p t e r 1 6 , D e s i g n i n g a p a g e l a y o u t 557

■ Page headers and footers

Report designers sometimes include controls such as column headings or labels in page headers or footers. Page headers or footers can appear in Reportlets for the following:■ If the target for a search URL contains page headers and the

Visibility➛ShowInReportlet property value is True, the first page header at the beginning of a report or group section appears in the Reportlet.

■ If the target for a search URL contains page footers and the Visibility➛ShowInReportlet property value is True, the first page footer at the end of a report or group section appears in the Reportlet.

Some Actuate report capabilities change in content extracted as Reportlets:

■ Reportlets are delivered as the full width of the frame.

■ The Viewer toolbar does not appear, which disables the table of contents, Search, balloon help, and PDF generation.

■ Hyperlinks from Reportlets replace the entire browser window.

■ Browser Scripting Controls do not work in Reportlets.

To modify a Reportlet's content or appearance in the web page, you can do the following:

■ Change the search URL to display a different report or portion of a report

■ Change the Boolean value of the Visibility➛ShowInReportlet property of components and controls to display or hide them in the Reportlet

■ Change the SearchValueExp property value from a static to a dynamic value

■ Create a script to generate the Reportlet

Setting properties for a ReportletFor portions of reports to extract as a Reportlet, you can do the following:

■ Set the Visibility➛ShowInReportlet property of the components you want to show or hide in the Reportlet.

■ Set the Searching➛SearchValueExp property value to statically or dynamically identify a portion of a report to extract as a Reportlet.

558 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Setting visibility properties for a ReportletIn the portion of a report to extract as a Reportlet, you can specify the visibility of each component.

How to set visibility properties for a Reportlet

1 Right-click a report component and choose Properties.

2 In Component Editor, in the Visibility group properties, set the ShowInReportlet property to one of the following values:■ True is the default value, which enables a report component to appear

in Reportlets.■ False hides a report component in Reportlets.

Setting the SearchValueExp property for a ReportletFor components you can extract as Reportlets, setting a Searching➛SearchValueExp property value can enable dynamically identifying components in Reportlets.

For example, the following illustration shows the layout pane displaying Component Editor for a frame. The Searching➛SearchValueExp property is set to [customers.customName]. Using an Active Portal directive, the value of [customers.customName] determines the content of the frame extracted as a Reportlet.

You do not have to specify a SearchValueExp property value. If you do not specify a value for this property, the default value is an empty string. To extract the component with an empty string value requires specifying the component in the Actuate Active Portal directive.

For information about extracting Reportlets, see “Extracting a Reportlet using a search URL,” later in this chapter.

C h a p t e r 1 6 , D e s i g n i n g a p a g e l a y o u t 559

How to set the SearchValueExp property for a Reportlet

1 Right-click the report component you want to extract as a Reportlet and choose Properties.

2 In Component Editor, in the Searching properties group, you can do the following to set the SearchValueExp property:■ Use a constant String value to identify a component that appears in one

instance in the report.

For example, you can use the following value to identify a frame that contains one instance of a chart:

"TheChart"

■ Use a dynamic String value to identify a component that changes depending on the search URL value that accesses it.

For example, you can use the following value to identify a frame that contains a chart that changes based on the customers.customName from the data row:

[customers.customName]

Extracting a Reportlet using a search URLFor a section, page, or frame, a search URL identifies the portion of a report to extract as a Reportlet. The Factory converts the content of the Reportlet to HTML for viewing in a browser. A Reportlet must be extracted for viewing in a web page.

The search URL to extract a page as a Reportlet uses the following syntax:

http://<web server>:<port number>/acweb/servlet/ViewPage?page=<page number>&format=Reportlet&name=/<folder>/<file name>&version=<version number>&type=<file type>&scalingFactor=<scale>

The search URL to extract a section or frame as a Reportlet is different from the search URL used in a search in a DHTML report document on the web. A search in a DHTML report document uses controls to find the targets for a search.

To extract a frame to view its contents in a web page, you can use syntax similar to the following URL, which extracts the OrderTitleFrame that contains the OrderNumber text control with the value 1810 from the report document detail.roi:

http://<webserver>:<port number>/acweb/servlet/ViewPage?format=Reportlet&name=detail.roi&searchcriteria=OrderTitleFrame::OrderNumber%3D1810

560 D e v e l o p i n g A d v a n c e d e . R e p o r t s

In the preceding URL, in the search criteria parameters syntax, the first equality uses an equals sign (=). As in this example, if the search criteria parameters require more than one equality, use the %3D hexadecimal equivalent for the equals sign for equalities after the first one.

The following HTML contained in a web page extracts the Reportlet and displays it in a frame as shown in the following illustration. This example uses the IFRAME tag to embed the Reportlet in the web page.

<IFRAME SRC="http://siamese:8700/acweb/servlet/ViewPage?format=Reportlet&name=detail.roi&searchcriteria=OrderTitleFrame::OrderNumber%3D1810&scalingFactor=60" NAME "A" HEIGHT=250 WIDTH=80% HSPACE=10 SCROLLING=YES ALIGN=RIGHT>Your browser cannot display iFrames </IFRAME>

To extract a report section as a Reportlet, you can use the GetReportData directive. The search URL to extract a report section uses the following syntax:

http://<web server>:<port number>/acweb/servlet/GetReportData?format=Reportlet&name=/<folder>/<file name>&version=<version number>&type=<file type>&componentID=<componentID>&scalingFactor=<scale>

Because the componentID is dynamic and might change from one report object executable (.rox) file run to another, identifying a part of a report by componentID can cause unexpected results.

For more information about using search URLs with Active Portal, see Chapter 2, “Creating a custom Active Portal for JSP web site,” and Chapter 3, “Creating a custom Active Portal for .NET web site,” in Creating Custom Web Applications using Actuate Active Portal. For more information about using search URLs with ReportCast, see Chapter 7, “Using ReportCast directives,” in Using and Customizing Actuate ReportCast.

Frame containing a ReportletWeb page

C h a p t e r 1 6 , D e s i g n i n g a p a g e l a y o u t 561

Adding a Reportlet to a web pageThe following procedure describes the general process for adding a Reportlet to a web page.

1 Create the Report that contains Reportlets.

2 Add the report object instance (.roi) file and report object executable (.rox) file to the Encyclopedia volume.

3 Set the dependency for the ROX to the ROI.

4 Create a search URL to locate and extract a component as a Reportlet.

In the search URL parameters, the format=Reportlet syntax identifies the format. For example, the following search URL extracts page 1 of the Detail.roi report document located in the Reportlet folder on the server named siamese:

http://siamese:8700/acweb/servlet/ViewPage?page=1&format=Reportlet&name=/Reportlets/detail.roi&version=001&type=roi

5 Embed the search URL in an HTML web page.

6 To view the Reportlet, open the web page in your browser.

Working with a ReportletReportlets enable inserting portions of report documents into HTML web pages. The presentation of the report content in a web page format changes how you work with the report.

Printing and downloading a ReportletYou can print or save the web page that contains a Reportlet as an HTML document. You cannot download or print the Reportlet itself in PDF format.

Enabling a hyperlink in a ReportletActuate supports using hyperlinks in Reportlets. Absolute and relative URLs are supported. In the web page, a relative URL is relative to the location of the web page. When a search URL extracts a Reportlet from a report document, relative URLs in the Reportlet become relative to the web page location. Relative URLs are not relative to the location of the report document from which the Reportlet was extracted.

To avoid unexpected results, use absolute URLs in reports from which you plan to extract Reportlets.

562 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Comparing Reportlets and DHTML reports functionalityReportlets do not support the following features of Actuate DHTML reports viewed on the web:

■ Table of Contents

■ Actuate generated JavaScript

■ Browser Scripting Control

About printing and viewing a report across platforms

The Factory tries to print a report that closely resembles the displayed report. The Factory also tries to minimize the differences in a report’s appearance when printing and viewing in different environments.

Hardware and software differences external to the Factory cause differences between the printed and displayed reports. The hardware and software used in viewing an Actuate report is different from that used in printing it. Viewing a report on a video display uses the Windows display subsystem. The Windows system depends on the following:

■ Capabilities of the installed graphics card.

■ The video driver.

■ Available Windows software fonts.

Printing, on the other hand, depends on the following technologies:

■ The capabilities of the printer, such as color support or resolution in dots per inch.

■ Available printer-resident fonts.

■ Downloadable (soft) fonts.

■ The printer language, which could be PostScript or PCL.

■ The printer driver.

If extremely accurate printed output is required, you must design for printing in a specific printing environment. No matter how hard you try, however, there are always a few slight differences between viewing and printing reports when you print in different hardware and software environments. For more information about viewing reports, see Using e.Reports. For information about working with page orientation in printing, see “Page orientation and printing,” earlier in this chapter.

C h a p t e r 1 6 , D e s i g n i n g a p a g e l a y o u t 563

Designing a report to print and display in multiple platforms

The following are some strategies for designing a report in Actuate e.Report Designer Professional to help you optimize viewing and printing, particularly if the report will be used in a heterogeneous environment:

■ Design for the final delivery environment. How reports appear and print depends on the hardware and software involved. Because exact fidelity between printing and viewing is not possible, decide whether printing or viewing is most important and design for that output.

■ Use standard fonts that users are likely to have on their systems. Avoid custom fonts unless you are certain they are installed on user systems and printers. Distributing custom fonts to users is typically a costly option because of font copyrights and licenses.

■ Minimize the number of fonts used.

■ Use scalable fonts rather than the raster version of fonts. For example, on Windows, use Courier New, not Courier, as the monospaced font.

■ If setting fonts dynamically at run time (either programmatically or by using dynamic text controls), embed in the report object executable (.rox) file font information for all the fonts that can be used in the report. You must, however, still ensure that systems on which the report will be viewed or printed have the actual fonts installed. For information about embedding font information in a report object executable (.rox) file, see “Embedding font information in a report object executable file” later in this chapter.

■ Make sure users of your report have the proper equipment: hardware, fonts, printers with the proper capabilities, and correct display and printer drivers.

■ Allow for differences in text layout and font heights and widths on different platforms by enlarging controls that contain text. For example, the amount of space between lines on a multiline control differs depending on whether it is printed on a UNIX printer or on a Windows printer.

■ Avoid defining BalloonHelp for overlapping controls. For information about overlapping controls, see “Layering components” in Chapter 4, “Using Design Editor.”

If you use BalloonHelp for overlapping controls, you see the help string for each control in Report Viewer. Other platforms, such as a DHTML viewer, however, are less predictable. On the other hand, a graph’s BalloonHelp string does not appear in Report Viewer but does in DHTML. For information about the BalloonHelp method, see Chapter 3, “AFC classes,” in Actuate Foundation Class Reference.

564 D e v e l o p i n g A d v a n c e d e . R e p o r t s

■ Be aware that monitor resolution can affect how much of a report is visible onscreen. In general, a monitor set to a lower resolution is capable of displaying less of a report than a monitor set to a higher resolution. For example, if you have a report with a wide or long format set at 100%, a monitor set to 640x480 resolution can display less of the report than a monitor with a 1024x768 resolution.

■ Minimize the size and color depth of graphics so that they print reasonably on a black and white printer.

■ If viewing reports online and printing reports on UNIX PCL printers, minimize the use of graphs. Graphs in reports do not print in UNIX PCL printers.

■ If printing with UNIX, use PostScript printers if you need to print graphs or images. PCL printers can print text only.

Testing your report designIf your report will be viewed or printed in multiple formats or environments—in the native report object instance (.roi) file format, DHTML, PDF, Windows printers, UNIX printers—testing your report design in as many environments as possible helps you discover and solve problem areas before you distribute or deploy the report.

Do the following when testing your report design:

■ Test viewing and printing, and make sure both generate acceptable reports. Display and printing of text and graphics can exhibit significant differences on different platforms.

■ Test reports in production environments. Use the production printer for development testing because different printers might exhibit different characteristics.

■ Test reports when you add or change printer models or printer drivers. Because vendors continually enhance products, upgrading hardware or software can change the appearance of a report.

For more information about setting up a test environment, setting up a production staging area, and setting up a production environment, see Installing Actuate iServer System.

C h a p t e r 1 6 , D e s i g n i n g a p a g e l a y o u t 565

Understanding font issuesWhen you design a report in e.Report Designer Professional, you can specify any combination of Font properties for controls. Users can see text in the fonts you used only if their systems have the fonts installed. It is your responsibility to ensure that the proper fonts are available in the viewing environment.

If the Factory cannot find the fonts when rendering it in Actuate Viewer, PDF Viewer, or DHTML Viewer, it substitutes fonts, and the report does not appear the way you designed it. For example, when a user opens a report object instance (.roi) file in Actuate Viewer, any unavailable fonts map to the Windows fonts.

You should not use fonts such as Arial and Times New Roman, designed for use with English and other Western European languages, on systems running Japanese, Chinese, or Korean locales. The PDF converter cannot recognize the characters so it uses a Latin character set. Acrobat Reader, in turn, cannot display the correct text. Instead, in Asian locales, you should use fonts designed for Japanese, Chinese, or Korean. Examples of appropriate fonts are MS Gothic, MS Song, and Gulim. For more information about designing reports for multiple locales, see Working with Multiple Locales.

For non-TrueType fonts, however, the font substitution yields incorrect results when the specified font is used with an invalid size, for example Courier 1. For this reason, a string might not appear correctly in the DHTML viewer or in Acrobat, even if the specified font is available in the viewing environment. This is because the specified font was not available in the design environment, so the font information in the report object executable (.rox) file is for the substituted font rather than the specified font.

When Actuate uses font informationIn addition to ensuring that the fonts you use in your report designs are installed on computers on which your reports appear, you might also need to provide font information that the Factory needs for rendering text content.

The Factory uses font information called font metrics to determine character widths and heights, which it uses to compute line breaks, text truncation, fill characters, and so on. The Factory requires font information in the following situations:

■ Rendering DHTML reports

■ Rendering PDF reports

■ Generating dynamic text control data

■ Generating Excel data as specified by AFC Excel API code used in the report design

566 D e v e l o p i n g A d v a n c e d e . R e p o r t s

How Actuate gets font informationDepending on the environment in which the Factory is running, the Factory looks for font information in your report object executable (.rox) file, a customized font file, a master font file, or the system’s operating system. The order in which the Factory searches for font information depends on the system and how the system is configured.

The master fonts file, master_fonts.rox, installed on Actuate iServer contains the font metrics for many commonly used fonts, which appear in the following table. If you use a font that does not appear in master_fonts.rox, you can create a customized fonts report executable (.rox) file.

Font information in a report object executable fileBy default, e.Report Designer Professional embeds font information in the report object executable (.rox) file for every font you use in controls, except in the following cases:

Plain font Bold font Italic font Bold Italic font

Arial Arial Bold Arial Italic Arial Bold Italic

Arial Unicode MS

Arial Unicode MS Bold

Arial Unicode MS Italic

Arial Unicode MS Bold Italic

Batang Batang Bold Batang Italic Batang Bold Italic

Batang 1 Batang Bold 1 Batang Italic 1 Batang Bold Italic 1

Courier Courier Bold Courier Italic Courier Bold Italic

Ming LiU Ming LiU Bold Ming LiU Italic Ming LiU Bold Italic

Ming LiU 1 Ming LiU Bold 1 Ming LiU Italic 1 Ming LiU Bold Italic 1

MS Gothic MS Gothic Bold MS Gothic Italic MS Gothic Bold Italic

MS Gothic 1 MS Gothic Bold 1

MS Gothic Italic 1

MS Gothic Bold Italic 1

MS Mincho MS Mincho Bold MS Mincho Italic MS Mincho Bold Italic

MS Mincho 1 MS Mincho Bold 1

MS Mincho Italic 1

MS Mincho Bold Italic 1

Sim Sun Sim Sun Bold Sim Sun Italic Sim Sun Bold Italic

Sim Sun 1 Sim Sun Bold 1 Sim Sun Italic 1 Sim Sun Bold Italic 1

Symbol Symbol Bold Symbol Italic Symbol Bold Italic

Times New Roman

Times New Roman Bold

Times New Roman Italic

Times New Roman Bold Italic

C h a p t e r 1 6 , D e s i g n i n g a p a g e l a y o u t 567

■ Fonts used in graphs and image controls

■ Fonts that are set dynamically at run time, either programmatically or by using dynamic text controls

To ensure that font information is available for these fonts, you can explicitly embed font information in the report object executable (.rox) file. For information about accomplishing this task, see “Embedding font information in a report object executable file,” later in this chapter.

Font information in a customized font fileAs an alternative to explicitly embedding font information in your report object executable (.rox) file, you can define the font information in a customized font file. The advantage of defining font information in a customized file is that you can specify all the fonts used in all your report object design (.rod) files in one place. A possible disadvantage is that this customized file might be very large, and might take longer to process.

For more information about defining a customized font file, see “Defining font information in a customized font file,” later in this chapter. For information about using the file, see “Using a customized font file on a desktop system,” later in this chapter, depending on whether the Factory is running on a server or desktop system.

Getting font information on Windows and UNIX serversFor rendering DHTML reports and PDF reports, and for generating Excel and dynamic text control data, the Factory gets font information from the following sources:

■ Font information defined in a customized font file stored on the server. For more information about this file, see “Using a customized font file on the server” later in this chapter.

■ Font information defined in a master font file stored on the server.

■ Font information embedded in the report object executable (.rox) file.

■ Default fonts for the controls.

Getting font information on desktop-only environmentsIf a report design contains dynamic text controls, the Factory gets font information for generating and rendering the contents of dynamic text controls from the following sources:

■ Font information embedded in the report object executable (.rox) file

■ Font information in the Windows operating system

■ Default font for the control

568 D e v e l o p i n g A d v a n c e d e . R e p o r t s

If a report design uses the AFC Excel API, the Factory gets font information for generating the Excel data from the following sources:

■ Font information embedded in the report object executable (.rox) file

■ Font information defined in a customized file stored on the desktop. For more information about defining this file and registering it, see “Using a customized font file on a desktop system” later in this chapter.

The look-up order depends on how the customized font file is configured on the desktop system.

Embedding font information in a report object executable fileAs the default behavior, e.Report Designer Professional embeds font information in the report object executable (.rox) file for every font you use in controls, except in the following cases:

■ Fonts used in graphs and image controls

■ Fonts that are set dynamically at run time, either programmatically or by using dynamic text controls

To explicitly embed font information for these fonts in the report object executable (.rox) file, use the following instructions.

How to explicitly embed a font in a report object executable file

1 For each font you want to specify, add a dummy control to the report design.

2 Set the Font property of each dummy control to a different font.

If your report design uses bold or italic versions of a font, you must include them separately. For example, Arial Bold is not the same as Arial.

3 Hide the dummy controls by setting all their Visibility properties to False.

Defining font information in a customized font fileIf your report design sets fonts dynamically at run time, you can specify the font information in a customized font file instead of embedding them in the report object executable (.rox) file. The advantage of specifying font information in a customized font file is that you can specify all the fonts used in all your report designs in one place. A possible disadvantage is that this customized font file might be very large, and might take longer to process.

To specify all the fonts used in all your report designs in one file, you can create a report object design (.rod) file that contains controls set to those fonts.

C h a p t e r 1 6 , D e s i g n i n g a p a g e l a y o u t 569

Save the report object design (.rod) file as customized_fonts.rod and build the report object executable (.rox) file, customized_fonts.rox, which you add to a folder on the Actuate iServer. You must have all the fonts installed on your system for the file to compile with the correct font information. If you do not, the report compiles, but the report object executable (.rox) file does not have the font information for all fonts. You can use the sample fonts defined in customized_fonts.rod only if you have the fonts installed. If you intend to distribute customized_fonts.rox, you should delete from customized_fonts.rod the sample fonts that you did not install.

For more information about using a customized fonts file on an Actuate iServer, see “Using a customized font file on the server,” later in this chapter. For more information about using a customized fonts file for reports that appear in multiple locales, see Chapter 4, “Using fonts with multiple locales,” in Working with Multiple Locales.

How to define fonts in a customized font file

1 In Actuate e.Report Designer Professional, create a blank report with a sequential section:

1 Choose File➛New.

Create New Report appears.

2 Select Blank Report. Choose OK.

A blank report appears in Design1—Design Editor.

3 In the structure pane, select the Content—Report component. Press Delete.

A blank Content slot appears.

4 From Structure, drag Sequential Section and drop it in Content.

Content—SequentialSection appears.

2 From Structure, drag a Frame and drop it in the blank Content slot.

Content—Frame1 appears.

3 To add fonts to the design:

1 Choose Insert➛Label.

570 D e v e l o p i n g A d v a n c e d e . R e p o r t s

2 Drag the label and drop it in the frame.

The label appears in the frame.

3 Choose View➛Component Properties.

Component Properties appears.

4 Set the font properties. For example, for the bold italic Arial Unicode MS font, the Font group properties appear in the following illustration.

Set the text that appears in the label, for example, Arial Unicode MS, as shown in the following illustration.

5 Repeat step 1 through 4 to add all fonts. You must create a separate label for plain, bold, italic, and bold italic fonts. For example, Arial Bold is not the same as Arial.

The layout pane of the report object design (.rod) file used to create master_fonts.rox appears in the following illustration.

C h a p t e r 1 6 , D e s i g n i n g a p a g e l a y o u t 571

Part of the structure pane of this ROD appears in the following illustration.

4 Save the report object design (.rod) file as customized_fonts.rod.

5 Choose Report➛Build and Run.

572 D e v e l o p i n g A d v a n c e d e . R e p o r t s

e.Report Designer Professional runs the report and it appears in customized_fonts—Report Viewer.

Using a customized font file on the serverAs described in “How Actuate gets font information,” earlier in this chapter, by default, the server looks for font information in a customized file if it exists. Otherwise, it uses the master font file.

To specify that the Factory use a customized font file, do the following:

■ Define the font information in a customized font file. For information on accomplishing this task, see “Defining font information in a customized font file” earlier in this chapter.

■ Copy the customized font file report object executable (customized_fonts.rox) file to the iServer in the following location:

$AC_SERVER_HOME\etc

If you work in a cluster environment, copy this file to every server in the cluster.

Using a customized font file on a desktop systemAs described in “How Actuate gets font information,” earlier in this chapter, Actuate desktop software looks for font information in a customized font file if you configure the desktop software to use the file.

To specify that the Factory use a customized font file, do the following:

1 Define the font information in a customized font file. For information on accomplishing this task, see “Defining font information in a customized font file” earlier in this chapter.

C h a p t e r 1 6 , D e s i g n i n g a p a g e l a y o u t 573

2 Register the customized font file by setting environment variables and configuring how the Factory should use the file.

How to register your customized font file

1 Set the AC_MASTER_FONT_FULLPATH_NAME environment variable to the location in which the customized font file is saved. Use the full path name.

2 Specify how the Factory should use the customized font file:■ If you want the Factory to look for fonts in the customized font file first,

set the AC_USE_DEFAULT_FONT_FILE environment variable to "primary."

If font information cannot be found in the customized font file, the Factory looks for the font information embedded in the report object executable (.rox) file.

■ If you want the Factory to look for fonts in the report object executable (.rox) file first, set the AC_USE_DEFAULT_FONT_FILE environment variable to "secondary."

If font information cannot be found in the report object executable (.rox) file, the Factory looks for the font information in the customized font file.

For information about setting environment variables, see Windows Help.

574 D e v e l o p i n g A d v a n c e d e . R e p o r t s

C h a p t e r 1 7 , P r e s e n t i n g d a t a i n a c r o s s t a b r e p o r t 575

C h a p t e r

17Chapter 17Presenting data in a

crosstab reportThis chapter contains the following topics:

■ About crosstab reports

■ Creating a crosstab report using Crosstab Builder

■ Organizing data in a crosstab report

■ Customizing the appearance of a crosstab report

■ Understanding crosstab report sizing

576 D e v e l o p i n g A d v a n c e d e . R e p o r t s

About crosstab reportsA crosstab, or cross tabulation, report displays data in rows and columns. Unlike a listing report, each cell in a crosstab report displays a calculated value. A crosstab report also displays summary information, for example, totals. In a crosstab report, the data and data grouping determine the number of rows and columns.

Comparing a crosstab report to a listing reportUsing e.Report Designer Professional, you can present data in columns and rows in the following report types:

■ Listing report

■ Crosstab report

A listing report displays grouped and sorted data from multiple database tables. For example, the listing report in the following illustration displays information about the closed orders for Advanced Design Inc. This report displays items grouped by order status, customer name, and category. The quantity is an aggregate calculated using the sum function. Each category displays a sales sum and the customer name group displays a total sales sum.

C h a p t e r 1 7 , P r e s e n t i n g d a t a i n a c r o s s t a b r e p o r t 577

This listing report is not ideal for comparing values among the different order status groupings, because it contains over forty pages. A crosstab report presents the information in a more suitable summary format.

StatusCustom NameCategoryDescription Pricequote Quantity

Order Status: ClosedCustom Name: Advanced Design Inc.Item Category: ControllerDescription: 32 bit Programmable Controller 221 69

Sum([items.pricequote] * [items.quantity]) = $15,249.00Item Category: DriverDescription: 64 bit Programmable Video Drvr 320 70

Sum([items.pricequote] * [items.quantity]) = $22,400.00Item Category: DSPDescription: 32 x 16 Programmable DSP 340 69

Sum([items.pricequote] * [items.quantity]) = $23,460.00Item Category: Dynamic RamDescription: 32 x 1 Dynamic Ram 26 417

Sum([items.pricequote] * [items.quantity]) = $11,161.00Item Category: ProcessorDescription: 32 bit General Purpose Processor 310 70

Sum([items.pricequote] * [items.quantity]) = $21,700.00Item Category: Static RamDescription: 8M x 8 Static Ram, 3.3 volts 105 278

Sum([items.pricequote] * [items.quantity]) = $21,308.00Totals for customName = Advanced Design Inc.

Sum([items.pricequote] * [items.quantity]) = $115,278.00

578 D e v e l o p i n g A d v a n c e d e . R e p o r t s

For example, the crosstab report in the following illustration displays summary information for item categories grouped by order status and customer name.

Understanding row and column keysA crosstab report groups data using row and column keys:

■ A row key is an expression that groups rows and subrows. In the crosstab report illustration in the preceding section, “Comparing a crosstab report to a listing report,” the row key orders.status groups rows and customers.customName groups subrows.

■ A column key is an expression that groups columns and subcolumns. In the crosstab report illustration in the preceding section, “Comparing a crosstab report to a listing report,” the column key items.category groups columns.

About creating a crosstab reportTo create a crosstab report, perform the following tasks:

■ Create a blank report.

■ Create a SQL or MDX query.

■ Insert a crosstab control into a frame.

Row group heading

Row subgroup heading Column heading

Group totals

Column totals Row totals

C h a p t e r 1 7 , P r e s e n t i n g d a t a i n a c r o s s t a b r e p o r t 579

■ Choose row keys and column keys for the crosstab report.

■ Specify an expression that calculates the values that appear in cells.

■ Modify page component properties to support resizing to fit a crosstab report.

■ Customize the appearance of the crosstab report.

For more information about creating a crosstab report, see “Creating a crosstab report using Crosstab Builder,” later in this chapter. For more information about customizing the appearance of a crosstab report, see “Customizing the appearance of a crosstab report,” later in this chapter.

Understanding crosstab report limitationsIn Release 7 e.Report Designer Professional, crosstab report limitations include:

■ A crosstab control uses a set of Actuate classes. If you subclass a crosstab control, the subclass inherits only the properties and methods of the AcCrosstab class. The crosstab subclass copies all other information at the time of its creation, including the visual properties of its parent crosstab, for example, background colors and fonts of heading labels.

■ Actuate e.Report Designer Professional does not support modifying the behavior of a crosstab report by overriding methods.

■ If you modify a crosstab control, you cannot choose Undo to reverse the change. Actuate e.Report Designer Professional does not support Undo and Redo for a crosstab control.

■ Actuate e.Report Designer Professional does not support splitting a crosstab report across pages. The generated report truncates a crosstab report if it is larger than a page’s flow.

■ A crosstab report in a report object instance (.roi) file does not support the selection of individual items.

■ A crosstab report does not support searching its contents.

■ A crosstab report does not support exporting data to another application such as Microsoft Excel.

■ A crosstab report does not support LinkExp and TargetWindowName properties.

580 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Creating a crosstab report using Crosstab BuilderCrosstab Builder supports creating a crosstab report by choosing from available data row columns to create crosstab report row and column keys. For a cell, you can specify the aggregate expression the crosstab report uses to calculate the cell’s value.

You can arrange rows and columns in groups. If you group data in a row or column, the crosstab report calculates summary values for the group. A crosstab report also creates a summary row and a summary column. The summary row summarizes each column’s data in the bottom row. The summary column summarizes each row’s data in the right column.

A crosstab report requires:

■ A database connection

For more information about defining a database connection, see “Defining a database connection,” in Chapter 7, “Using a query data stream.”

■ A query

For more information about creating a query, see “Writing a query,” in Chapter 7, “Using a query data stream,” or “Creating an MDX query,” in Chapter 10, “Designing a report that uses an SAP BW data stream.”

How to create a crosstab report

1 Create a blank report. Modify the connection component, if necessary.

This example uses the ODBC data source Sfdata.

2 Create a query. The example shown in the illustrations in this procedure uses the following SQL query:

SELECT customers.customName, ( items.pricequote * items.quantity ) AsExtendedPrice, items.category, orders.statusFROM customers, orders, itemsWHERE customers.custID = orders.custID AND orders.orderID = items.orderID

3 Choose Insert➛Crosstab. Drop the control into a frame, usually a detail frame. Do not add a crosstab control to a frame in a Before slot because the frame cannot resize.

Crosstab Builder appears, displaying columns from the data row in Available data, as shown in the following illustration.

C h a p t e r 1 7 , P r e s e n t i n g d a t a i n a c r o s s t a b r e p o r t 581

4 To create a row key, drag a data field from Available data and drop it into Group rows by. For example, drag orders.status from Available data and drop it into Group rows by.

[orders.status] appears in Group rows by, as shown in the following illustration.

To create another row key, drag a field from Available data and drop it into Group rows by.

[customers.customName] appears in Group rows by.

The order in which the row keys appear in the list determines their nesting levels. This example uses both orders.status and customers.customName.

For more information about crosstab report grouping, see “Modifying crosstab report grouping,” later in this chapter.

582 D e v e l o p i n g A d v a n c e d e . R e p o r t s

5 To create a column key, drag a field from Available data and drop it into Group columns by. This example uses items.category.

[items.category] appears in Group columns by.

You can add additional column keys to Group columns by. The example shown in the illustrations in this procedure uses one column key in Group columns by.

6 To create an aggregate function for a cell, drag a field from Available data and drop it into In each cell, show. The example shown in the illustrations in this procedure uses the computed field ExtendedPrice, which is equal to:

items.pricequote * items.quantity

Sum is the default aggregate function for numeric and currency data types. For other data types, the default aggregate function is Min.

Crosstab Builder appears.

C h a p t e r 1 7 , P r e s e n t i n g d a t a i n a c r o s s t a b r e p o r t 583

7 To examine the crosstab report design in the layout pane, choose OK.

The crosstab report design appears.

8 To resize the crosstab control or a cell, drag a crosstab control’s or cell’s border.

9 To support a page resizing to fit the crosstab report’s content:

1 In the structure pane, expand PageList—SimplePageList.

PageStyle—Page appears.

2 Select PageStyle—Page. Choose View➛Component Properties.

Page—Component Editor appears.

3 In Dynamic Size and Position, set the property values as shown in the following table.

Property Value

CanIncreaseHeight True

CanIncreaseWidth True

584 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Choose Close.

10 To generate the report, choose Report➛Build and Run.

The crosstab report appears in the report in Report Viewer.

Organizing data in a crosstab reportUsing Crosstab Builder, you can modify the data organization in a crosstab report. The following sections describe using Crosstab Builder to complete these tasks:

■ Modifying crosstab report grouping

■ Sorting rows and columns in a crosstab report

■ Modifying an aggregate function in a crosstab cell

Modifying crosstab report groupingYou can change the grouping level of a row or column key on Crosstab Builder. The order in which row keys appear in Group rows by and column keys appear in Group columns by determines their nesting levels in the crosstab report.

How to change crosstab report grouping

1 To open Crosstab Builder, in the layout pane, right-click a crosstab control and choose Crosstab Builder.

Crosstab Builder appears.

C h a p t e r 1 7 , P r e s e n t i n g d a t a i n a c r o s s t a b r e p o r t 585

2 To change crosstab report grouping setup, on Crosstab Builder:

■ For a row key, in Group rows by, select a row key and choose the up or down arrow to reposition the key.

■ For a column key, in Group columns by, select a column key and choose the up or down arrow to reposition the key.

3 Choose OK.

Sorting rows and columns in a crosstab reportOn Crosstab Builder, you can use Group Sorting to sort rows and columns in a crosstab report. The sort order you select determines the order in which the data appears in the crosstab report.

How to sort rows and columns in a crosstab report

1 To open Crosstab Builder, in the layout pane, right-click a crosstab control and choose Crosstab Builder.

Crosstab Builder appears.

2 Select an item: ■ To sort rows, select the row key in Group rows by.■ To sort columns, select the column key in Group columns by.

Choose Sort.

Group Sorting appears.

3 Select the sorting options:■ In Sorting:

- To sort data, select Sort by <field name>.- To display data in the order in which it appears in the data source,

select Keep original order.

586 D e v e l o p i n g A d v a n c e d e . R e p o r t s

■ In Direction, select one of the following options:- If you selected Sort by <field name>, to display data in ascending

order, select Forward. To display data in descending order, select Reverse.

- If you selected Keep original order, to display data in the original order, select Forward. To display data in reverse order, select Reverse.

Choose OK.

Modifying an aggregate function in a crosstab cellOn Crosstab Builder, choose Aggregate to modify the aggregate function that calculates a cell’s value. The default aggregate function is Sum for numeric and currency data types and Min for other data types. For more information about aggregate functions, see “Computing aggregates in a value expression,” in Chapter 12, “Working with frames and controls.”

To change the aggregate function that calculates a cell’s value from values in the data source row, you can choose one of the functions that appear in the following table.

You can also use the aggregate function, Count( ), in a crosstab report. Count( ) returns the number of data rows. For example, the following illustration shows a part of a crosstab report in which each cell displays two values, Count and Sum. For CompuBoards, Sum consists of data from seven data rows.

For example, on Crosstab Builder, to display the number of data rows in a cell, drag the aggregate function <Count> from Available data and drop it into In each cell, show, as shown in the following illustration.

Function Description

Ave Calculates and displays the average value for the cell

Max Displays the highest value for the cell

Min Displays the lowest value for the cell

Sum Calculates and displays the sum of values for the cell

C h a p t e r 1 7 , P r e s e n t i n g d a t a i n a c r o s s t a b r e p o r t 587

How to modify an expression in a crosstab cell

1 In the layout pane, right-click a crosstab control and choose Crosstab➛Crosstab Builder.

Crosstab Builder appears.

2 For In each cell, show, select an expression to modify. Choose Aggregate.

A list of aggregate functions appears.

3 Choose an aggregate function.

Customizing the appearance of a crosstab reportTo customize a crosstab report’s appearance, you can change the propertiesof a:

■ Crosstab control

■ Crosstab row

588 D e v e l o p i n g A d v a n c e d e . R e p o r t s

■ Crosstab column

■ Cell

■ Value or label

The sections that follow explain how to modify properties of a crosstab report and its elements. For more information about properties of a crosstab report, see Class AcCrosstab in Actuate Foundation Class Reference.

Customizing the appearance of a crosstab reportUse <Crosstab control name>—Component Editor to customize the appearance of a crosstab report. To change the appearance of the borders surrounding the crosstab report elements that appear in the following illustration, for example, change the property values in the Borders group.

The following illustration shows the Borders group property settings for the crosstab report shown in the preceding illustration.

OuterBorder

RowHeadingsBorder

ColumnHeadingsBorder

C h a p t e r 1 7 , P r e s e n t i n g d a t a i n a c r o s s t a b r e p o r t 589

To modify the default appearance of a crosstab report, on <Crosstab control name>—Component Editor, you can change the properties summarized in the following table.

To access Crosstab Builder from <Crosstab control name>—Component Editor—Properties, select Definition and choose Builder.

Property group Property Description

BackgroundColor BackgroundColor Choose a background color from the drop-down list or choose Builder to provide a color. The default value is TransparentColor.

Borders ColumnHeadingsBorder

Specify Color and Thickness of the border between the column headings and cells. The default values are black and 1 point.

OuterBorder Specify Color and Thickness of the crosstab border. The default values are black and 1 point.

RowHeadingsBorder

Specify Color and Thickness of the border between the row headings and cells. The default values are black and 1 point.

Dynamic Size and Position

CanMoveLeft Specify to support the crosstab control moving left in the generated report. The default value is False.

CanMoveUp Specify to support the crosstab control moving up in the generated report. The default value is False.

HorizontalPosition

Specify to support displaying the crosstab control in the horizontal position in which the designer placed it in the layout. The default value is HorizontalPositionDefault.

VerticalPosition Specify to support displaying the crosstab control in the vertical position in which the designer placed it in the layout. The default value is VerticalPositionDefault.

590 D e v e l o p i n g A d v a n c e d e . R e p o r t s

How to modify the properties of a crosstab control

1 Select a crosstab control. Choose View➛Component Properties.

<Crosstab control name>—Component Properties appears.

2 In Properties, modify a value of a property.

3 To apply the changes, in <Crosstab control name>—Component Properties, choose Close.

Customizing an element in a crosstab reportYou can customize specific elements in a crosstab report by changing property values. In the layout pane, depending on which crosstab report element you right-click, the available options differ.

You can define the properties of rows, columns, headings, and borders as shown in the following illustrations.

Customizing bordersTo customize borders, you can set row and column properties. A row outside border appears between two consecutive row instances in the same level.

Height

HeadingHeight

HeadingWidth

Width

Row outside borders

C h a p t e r 1 7 , P r e s e n t i n g d a t a i n a c r o s s t a b r e p o r t 591

A row inside border appears between one row level and the next lower level.

A column outside border appears between two consecutive column instances in the same level.

A column inside border appears between one column level and the next lower level.

Row inside borders

Column outside border

Column inside borders

592 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Customizing a row, a column, or a cellTo change the properties of rows, columns, and cells, use Crosstab Row Properties, Crosstab Column Properties, and Crosstab Cell Properties. Descriptions of the available properties appear in the following table.

How to customize a row in a crosstab report

1 In the layout pane, right-click an element in a row and choose Row properties.

Crosstab Row Properties appears.

Property Description

BackgroundColor Choose a background color from the drop-down list or choose Builder to provide a color from Color. The default value is TransparentColor. Row background color takes precedence over column background color. Cell background color takes precedence over row background color.

HeadingHeight Specify the column heading height.

HeadingWidth Specify the row heading width.

Height Specify the row height.

InnerBorder Specify Color and Thickness of the border between a row in one level and the rows in the next lower level or between a column in one level and the columns in the next lower level. The default values are black and 0.5 point.

OuterBorder Specify Color and Thickness of the border between a row and the next instance of the same level row or between a column and the next instance of the same level column. The default values are black and 0.5 point.

Width Specify column width.

C h a p t e r 1 7 , P r e s e n t i n g d a t a i n a c r o s s t a b r e p o r t 593

2 Modify the row property values.

Choose OK.

How to customize a column in a crosstab report

1 In the layout pane, right-click an element in a column and choose Column properties.

Crosstab Column Properties appears.

2 Modify the column property values.

Choose OK.

594 D e v e l o p i n g A d v a n c e d e . R e p o r t s

How to customize a cell in a crosstab report

1 In the layout pane, right-click a cell and choose Cell properties.

Crosstab Cell Properties appears.

2 Modify the BackgroundColor value.

Choose OK.

Customizing a value or a labelYou can customize the display of values that appear in cells and labels that appear in headings. To change the properties of values and labels, use Crosstab Value and Label Properties. The available properties appear in the following table. You can change the default values for font attributes using Options—Fonts. For more information about Options—Fonts, see “Setting the default font for labels, data, and source editor,” in Chapter 5, “Customizing the design environment.”

Property Action

BalloonHelp Type text that appears when the user’s mouse hovers over a row or column label.

DataType Choose a data type setting from the drop-down list:■ DataTypeAutomatic■ DataTypeDateTime uses the default format General

Date.■ DataTypeNumber uses the default format #,##0.00.■ DataTypeText uses the default text data font setting

in Options—Fonts.As the default behavior, e.Report Designer Professional sets the DataType value when you add an expression to the crosstab report.

C h a p t e r 1 7 , P r e s e n t i n g d a t a i n a c r o s s t a b r e p o r t 595

For more information about text format and placement options, see “Formatting data in a control,” “Truncating data in a single-line control,” and “Truncating text in a single-line control,” in Chapter 12, “Working with frames and controls.”

How to customize a cell value or row or column label in a crosstab report

1 In the layout pane, right-click a cell value or row or column label and choose one of the following items:■ Value properties■ Row label properties ■ Column label properties

Font Modify the following font attributes:■ Bold■ Color■ FaceName■ Italic■ Script■ Size■ Strikethrough■ Underline

Format Provide format for a data value, such as currency.

SampleValue Type a value that appears in a label or cell in the layout.

Text Specify the text for the summary row and column heading labels. The default value is Totals.

TextPlacement Modify the following attributes:■ Clip■ Ellipsis■ FillPattern■ Horizontal■ MultiLine■ Vertical■ WordWrap

Property Action

596 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Crosstab Value and Label Properties appears.

2 Modify the property values.

Choose OK.

Understanding crosstab report sizingThe contents of a crosstab report determine its horizontal and vertical size. The data the crosstab report retrieves from the database determines the total number of columns and rows. When the crosstab report generates, it displays all columns and rows that contain data. You can change the crosstab report’s properties to change its appearance.

In e.Report Designer Professional’s layout pane, the crosstab report displays one instance of each row and column level. The following illustration shows a crosstab report layout that contains a group and a subgroup for rows and one group for columns.

A crosstab report resizes to accommodate its data. A frame resizes to accommodate a crosstab report. If a crosstab’s parent frame resizes and exceeds the size of the flow, a report designer has the following options:

■ Increasing the size of the flow in the page.

■ Increasing the size of both the page and the flow.

C h a p t e r 1 7 , P r e s e n t i n g d a t a i n a c r o s s t a b r e p o r t 597

■ Enabling the page to grow dynamically. As the default behavior, pages do not resize. You can set the Dynamic Size and Position properties of the page to support resizing for a large crosstab report.

■ Decreasing the crosstab report’s size by:■ Decreasing the widths of row headings and columns to the minimum

necessary to display the actual data■ Decreasing the font sizes of values and heading labels in the crosstab

report to support decreasing the widths of columns and row headings

598 D e v e l o p i n g A d v a n c e d e . R e p o r t s

C h a p t e r 1 8 , D e s i g n i n g a r e p o r t p a r a m e t e r 599

C h a p t e r

18Chapter 18Designing a report

parameterThis chapter contains the following topics:

■ About report parameters

■ Defining a parameter

■ Creating a reference to a parameter

■ Modifying a parameter for the request page

■ Saving parameter settings into an ROV

■ Setting report parameter options

■ Deleting a parameter

■ Using parameters to manage a large report

600 D e v e l o p i n g A d v a n c e d e . R e p o r t s

About report parametersA parameter is a variable that passes data into a report when the report runs. Requester or the request page supports a report user entering a parameter’s criteria, such as a date, name, or label, before running the report object executable (.rox) file. These parameters support customizing the report’s output. For example, you can create a parameter that supports the user narrowing the scope of the query when executing the report. The ability to narrow the scope of the query supports the user working with one report design to produce many different reports.

For each report parameter, you can specify a parameter display name, which appears in Requester or on the request page when a user runs the report. A report developer uses the parameter display name to provide a meaningful prompt. A report developer can use Component Editor and Parameter Properties to define a parameter, except an ad hoc parameter, which you create on Query Editor—Conditions. Report users cannot define a parameter.

Parameter Properties displays parameters that are in the report design. Developers and users can use Parameter Properties to add parameters to those that already exist.

Parameter groups support a developer organizing parameters into meaningful sets. For more information about organizing parameters, see “Modifying a parameter for the request page,” later in this chapter.

Some parameters do not appear in Requester and on the request page. A parameter that does not appear on the request page is useful when you want to supply a value at the time the report runs without supporting input from users. For information about how to design a parameter that does not appear on the request page, see “Modifying a parameter for the request page,” later in this chapter.

You can use the Requester API (application programming interface) to modify report parameters programmatically. For more information about the Requester API, see Chapter 21, “Requester API user guide,” in Programming e.Reports.

About global and local parametersLike other variables, a parameter has scope. The scope of a parameter is the portion of the report design that can refer to the parameter.

For example, when a parameter has a local scope, you can refer to it from within that scope only. An example of a parameter with local scope is a local variable that sets the font color in a control. The method code for that control refers to the local variable.

C h a p t e r 1 8 , D e s i g n i n g a r e p o r t p a r a m e t e r 601

When a parameter has a global scope, you can refer to it from anywhere in the report design. You can use a global parameter when you want to customize a number of different controls in the same way, for example, setting a user’s preferred color scheme.

You can create these types of global and local parameters:

■ Local parameters to which a component refers

■ Global or local parameters that set the values of a component’s properties

■ Parameters to which properties do not refer

■ Ad hoc parameters, which are local parameters, that support users changing the query

For information about ad hoc parameters, see “Defining and configuring an ad hoc parameter,” later in this chapter. For more information about scope, see Programming e.Reports.

About parameter typesActuate e.Report Designer Professional supports the following parameter types:

■ An ad hoc parameter supports a user providing a query by example expression to refine a query when he runs the report. For more information see “Defining and configuring an ad hoc parameter,” later in this chapter.

■ A Boolean parameter supports only values of True or False. For more information, see “Defining a Boolean parameter,” later in this chapter.

■ A property parameter is available for some properties and can have global or local scope. For more information, see “Defining a property parameter,” later in this chapter.

■ A static parameter is a simple parameter, which has global or local scope. For more information, see “Defining a static parameter,” later in this chapter.

About adding a parameter to a report designAdding a parameter to a report design is a two-stage process. The process differs slightly for ad hoc parameters. For information about ad hoc parameters, see “Defining and configuring an ad hoc parameter,” later in this chapter.

■ Define the parameter. In Component Editor or Parameter Editor, specify the name and characteristics of the parameter.

For more information about defining parameters, see “Defining a parameter,” later in this chapter.

602 D e v e l o p i n g A d v a n c e d e . R e p o r t s

■ Create a reference to the parameter. Use the parameter name in the report design where you want the report to use the value.

For more information about creating references to parameters, see “Creating a reference to a parameter,” later in this chapter.

Defining a parameterA developer can define a parameter by using a combination of Component Editor, Parameter Editor, Parameter Properties, and Query Editor depending on what kind of parameter a report requires.

This section documents several ways to define a parameter, depending on the parameter type. The following table provides an overview.

You can also use Textual Query Editor to create static and ad hoc parameters. For information about Textual Query Editor, see “About Textual Query Editor,” in Chapter 18, “Designing a report parameter.”

Technique When to use

Choose Properties in Component Editor.

Define a parameter that is global or local that provides the value for a component property.

1 Choose Variables in Component Editor.

2 Choose New. Class Variable appears.

Define a local parameter that does not provide a property value. The parameter can have a reference in a property and can have a reference in method code. You can use this parameter in any context where a variable of the same type is appropriate in method code. This parameter does not appear in the component’s properties.

1 Choose Tools➛Parameters.

2 In Parameter Editor, choose Add.

Add a global parameter that is not associated with a component.

On Query Editor—Conditions, select ad hoc.

Define a local ad hoc parameter, which supports users entering a query by example (QBE) expression when they run a report.

On Query Editor—Conditions, enter a parameter name prefixed with a colon.

To define a local parameter, which supports users entering a specific value to select the data when they run the report.

C h a p t e r 1 8 , D e s i g n i n g a r e p o r t p a r a m e t e r 603

When you define a parameter, e.Report Designer Professional declares a variable and adds it to the definition of the appropriate component in the report design. If you define an ad hoc parameter as part of a query, e.Report Designer Professional adds a variable to the query data source component. After you define the parameter, you can view the parameter as a variable on Component Editor—Variables.

Defining a property parameterYou can use a parameter to supply a value for many types of properties. Use Component Editor to create a property parameter. In the following example, you work with the Connection component to add a user name and password as parameters.

How to define user name and password as parameters

1 Double-click the Connection component.

<Component name>—Component Editor—Properties appears.

2 Click in the area to the right of UserName.

Select Parameter.

Parameter

Click in the right column

Select Parameter

604 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Because you can use this type of property as a parameter, Property Parameter Info appears. If you cannot use this type of property as a parameter, Parameter in Component Editor—Properties is unavailable.

3 In Parameter Name, type a unique name for the parameter.

Select Local or Global to indicate the parameter scope. In the following illustration, the parameter has local scope.

Choose OK.

The parameter name appears in Component Editor—Properties.

In Component Editor—Properties, Builder appears. This button indicates that Parameter Properties is available. For more information about Parameter Properties, see “Modifying a parameter for the request page,” later in this chapter.

You just defined and created a reference to a parameter. For more information about defining and creating references, see “About adding a parameter to a report design,” earlier in this chapter.

4 Repeat steps 2 through 3 for the Password property.

Defining a local parameterUse Component Editor—Variables and Class Variable to define a local parameter that is not a property. For information about defining a property parameter, see “Defining a property parameter,” earlier in this chapter.

A report developer can access a parameter with local scope by using its fully scoped name. You can use this process to verify values a user entered. You can check all local or global parameter values for validity in the Start ( ) method of the report component where you change a value if a user entered an unreasonable value.

To specify the parameter’s scope, select Local or Global

Type a new parameter name or accept the default name

Builder

C h a p t e r 1 8 , D e s i g n i n g a r e p o r t p a r a m e t e r 605

How to define a local parameter that is not a property

1 Double-click the component to which you want to add a parameter.

Component Editor—Properties appears.

2 Choose Variables.

Component Editor—Variables appears.

3 To define a new parameter, choose New.

Class Variable appears.

4 Complete the information as shown in the following illustration.

Choose OK.

For more information about creating a variable, see Chapter 4, “Using Component Editor,” in Programming e.Reports.

Defining and configuring an ad hoc parameterAn ad hoc parameter is always a local parameter. An ad hoc parameter supports report users redefining the report’s SQL statement. In Requester or on the request page, the ad hoc parameter accepts a Query by Example (QBE) expression. This QBE expression operates on the WHERE clause of the query.

Developers create an ad hoc parameter on Query Editor—Conditions. The ad hoc parameter then appears in Requester or on the request page, along with other previously defined parameters.

When the report user supplies a value for an ad hoc parameter, the WHERE clause in the SQL statement changes. When the user chooses OK on the request page and runs the report, the adjusted WHERE clause filters the query.

Type parameter name

Select Parameter

Select Static

Select Actuate Basic data type

606 D e v e l o p i n g A d v a n c e d e . R e p o r t s

You can define and refer to ad hoc parameters only in reports that use a query data source. The following illustrations and illustrations in “How to define an ad hoc parameter,” later in this chapter, show static and ad hoc parameters in a query.

For more information about QBE syntax, see “Using Query by Example (QBE) syntax” in Chapter 7, “Using a query data stream,” and Chapter 4, “Running a report,” in Using e.Reports.

How to define an ad hoc parameter

1 Choose View➛Data Source.

Query Editor—Columns appears.

2 Choose Conditions.

Query Editor—Conditions appears.

3 In Column Name, select an empty field.

Select a column name from the drop-down list.

Select Ad-Hoc as shown in the following illustration.

After you select Ad-Hoc, you cannot enter an expression or constant in the Query Expression column.

User can type two values, :ItemMin and :ItemMax

User can type a QBE expression

C h a p t e r 1 8 , D e s i g n i n g a r e p o r t p a r a m e t e r 607

The ad hoc parameter you specify using Query Editor—Conditions appears in Requester or on the request page when a user runs the report.

How to configure an ad hoc parameter

To configure how the ad hoc parameter appears in Requester or on the request page:

1 Choose Tools➛Parameters.

Parameter Editor appears.

2 On Parameter Editor, choose an ad hoc parameter to configure.

3 Choose Modify.

Parameter Properties—General appears.

4 Change the parameter configuration as necessary.

When you identify a column name as an ad hoc parameter on Query Editor—Conditions, its Actuate Basic data type becomes String. You cannot change the data type.

For more information about configuring an ad hoc parameter for Requester and the request page, see “Modifying a parameter for the request page,” later in this chapter.

Choose OK.

5 In Parameter Editor, choose Close.

Defining a Boolean parameterBoolean parameters accept only True and False values. Parameter Properties supports creating labels for Boolean True and False values to customize how a user provides those values in Requester or on the request page.

How to define a Boolean parameter using Parameter Properties

1 Choose Tools➛Parameters.

Parameter Editor appears.

2 Choose Add.

Parameter Properties—General appears.

3 Provide the following values:■ Name■ Type, which must be Boolean■ Group

608 D e v e l o p i n g A d v a n c e d e . R e p o r t s

■ Display name■ Default value■ Required■ Hidden

For more information about these values, see “Setting properties using Parameter Properties—General,” later in this chapter.

4 Choose Advanced.

Parameter Properties—Advanced appears.

5 Provide values to customize the display in Requester and on the request page.

For more information about these values, see “Setting options using Parameter Properties—Advanced,” later in this chapter.

Choose OK.

Defining a static parameterYou can define static parameters using Query Editor or Parameter Properties.

Like ad hoc parameters, static parameters defined in Query Editor modify the query’s WHERE clause. A report user can use QBE syntax in Requester or on the request page for an ad hoc parameter, but the report user must supply a single value for a static parameter.

A static parameter defined in Parameter Properties is global in scope. A report developer uses a globally scoped static parameter when a value entered by the user is useful in more than one location in a single report design.

How to define a static parameter using Query Editor

1 In Query Editor, choose Conditions.

Query Editor—Conditions appears.

2 In Conditions:■ In Column Name, choose the appropriate column from the drop-down

list.■ In Query Expression, type the name of the parameter preceded by a

colon (:).

C h a p t e r 1 8 , D e s i g n i n g a r e p o r t p a r a m e t e r 609

The static parameter can be:■ A local parameter that you define.■ An inherited parameter you define in the report or query component’s

parent class.■ A global parameter that you define.■ A new parameter.

The parameter’s Actuate Basic data type must be compatible with the database column’s data type.

If the parameter is not defined, e.Report Designer Professional defines a local parameter.

3 Choose Tools➛Parameters.

Parameter Editor appears.

4 Select the parameter you defined in Query Editor. Choose Modify.

Parameter Properties—General appears.

610 D e v e l o p i n g A d v a n c e d e . R e p o r t s

5 Choose the parameter’s type from the drop-down list.

The parameter’s Actuate Basic data type must be compatible with the database column’s data type.

Complete Parameter Properties—General as described in “Setting properties using Parameter Properties—General,” later in this chapter.

Choose Advanced.

Parameter Properties—Advanced appears.

6 Complete Parameter Properties—Advanced as described in “Setting options using Parameter Properties—Advanced,” later in this chapter.

C h a p t e r 1 8 , D e s i g n i n g a r e p o r t p a r a m e t e r 611

Choose OK.

7 In Parameter Editor, choose Close.

Creating a reference to a parameterYou can create a reference to a parameter name as part of any expression or value in a report design. You can use parameter names in the following ways:

■ As part of a query, as in an ad hoc parameter

■ To set the value of a property, as in a component or components

■ In method code

How to create a reference to a parameter

To create a reference to a parameter, use its name in any expression or value within the scope of the parameter in your report design. You can refer to a global parameter from any part of the report design. You can refer to a local parameter from any part of the report design by using the fully scoped name of the parameter.

612 D e v e l o p i n g A d v a n c e d e . R e p o r t s

In some cases, Actuate e.Report Designer Professional creates a reference to a parameter when you create and define it. This occurs when you define an ad hoc parameter or use a parameter to set the value of a property.

To view the parameters in your report design:

1 Choose View➛Project Browser.

2 Right-click in the Project Browser and choose Options. Ensure that Variables is selected.

Project Browser indicates which parameters are global and which are local.

How to display a parameter value in a report

1 In your report design, create a control of the appropriate type.

2 Set the control’s ValueExp property to <parameter>, where <parameter> is the name of the parameter. Use the fully scoped name of the parameter if the parameter is locally scoped to a different report component. In your report, the control displays the parameter value a user enters in Requester or on the request page.

For example, you create a date and time control to display a date. If the name of the component on which you define the parameter is DataSource and the name of the parameter is StartDate, set the control’s ValueExp property to DataSource::StartDate. If you type 8/1/1998 for the parameter StartDate in Requester or on the request page, the date and time control displays the value 8/1/1998 in the report.

C h a p t e r 1 8 , D e s i g n i n g a r e p o r t p a r a m e t e r 613

Modifying a parameter for the request pageUse Parameter Editor and Parameter Properties to modify parameters that appear in Requester and on the request page.

Requester displays examples of customizable elements in the following illustration. The request page displays information in the same format as Requester. For more information about customizing Requester, see “Customizing a parameter using Parameter Properties,” later in this chapter.

For more information about creating parameters in a report design, see “Defining a parameter,” earlier in this chapter.

Drop-down lists

Text boxes

Radio buttons for Boolean data type

Radio buttons for ranges of data values

614 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Displaying a parameter using Parameter EditorParameter Editor lists parameters the report contains in the left column. The right column displays the default values that appear in Requester and on the request page. If you select a parameter for which multiple values are available, an arrow appears for the drop-down list as shown in the following illustration. Use the drop-down list to select a default value to appear on the request page.

If you select an ad hoc parameter from the parameters list, an arrow appears to indicate the ad hoc expression builder is available to change the default value. For more information about the ad hoc expression builder, see “Setting a default value for an ad hoc parameter,” later in this section.

How to modify a parameter for the request page

1 Choose Tools➛Parameters.

Parameter Editor appears.

2 Select the parameter to modify. Choose Modify.

Parameter Properties—General appears.

3 Use Parameter Properties—General and Parameter Properties—Advanced to customize the appearance of the parameter in Requester and on the request page.

For more information about customizing the appearance of parameters, see “Customizing a parameter using Parameter Properties,” later in this chapter.

Customizing a parameter using Parameter PropertiesParameter Properties supports customizing the appearance of a parameter in Requester and on the request page. This section contains information about the available options.

C h a p t e r 1 8 , D e s i g n i n g a r e p o r t p a r a m e t e r 615

Setting properties using Parameter Properties—GeneralUse Parameter Properties—General to customize the parameter display name and value a user sees in Requester and on the request page. An example of Parameter Properties—General appears in the following illustration.

Parameter value if user does not supply a value in Requester

Parameter name

Requester group name

Actuate Basic data type

Requester display name

Specify whether the report runs without a value for this parameterSelect to provide the value through code, not in Requester

Specify scope as global or local to which class

616 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Depending on which parameter type you select in Parameter Editor and choose to modify, not all properties in the following table are available in Parameter Properties—General.

Property Description

Name You cannot change the parameter name in Parameter Properties. To change an ad hoc parameter’s name or type, use Query Editor. For more information about modifying an ad hoc parameter in Query Editor, see “Defining and configuring an ad hoc parameter,” earlier in this chapter. To change a scoped parameter’s name, use Component Editor. For more information about modifying parameters in Component Editor, see “Defining a property parameter,” earlier in this chapter.

Type The drop-down list displays the available Actuate Basic data types for parameters.For a complete list of data types, see Appendix A, “Actuate Basic data types,” in Actuate Basic Language Reference.

Group Assign an optional group name in which a parameter appears.

Display name This name appears for the parameter. Assigning a display name is optional. If you do not assign a display name, the parameter name appears.

Default value The value that appears for the parameter. To run the report, if you select Required, the user must provide a value. Settings in Parameter Properties—Advanced determine whether this value appears in a text box or drop-down list in the Parameter Properties—General page. For an ad hoc parameter, you can display the ad hoc expression builder to supply a value. For more information about the ad hoc expression builder, see “Setting a default value for an ad hoc parameter,” later in this chapter.

Required To run the report object executable (.rox) file, if you select Required, the user must provide a value. The user’s request requires a value before it can continue.

C h a p t e r 1 8 , D e s i g n i n g a r e p o r t p a r a m e t e r 617

How to select a default value for a date in Parameter Properties—General

1 If a parameter’s type is Date, to select a default value in Parameter Properties—General, choose Builder to display Select Date and Time as shown in the following illustration.

2 Select a date.

To include a time, select include time and provide a time in Include time.

Choose OK.

Hidden If you select Hidden, the parameter does not appear in Requester or on the request page. You can apply settings in Parameter Properties—Advanced to change the display in Parameter Editor and Parameter Properties—General. If you later deselect Hidden, your custom settings appear on the request page. You can access the parameter through the Requester API.

Scope This property is available for scoped parameters only. You can select Global or the Actuate class name to which the parameter has local scope. If you change a local parameter’s scope to global, you cannot change it back to local. For more information about a parameter’s scope, see “About global and local parameters,” earlier in this chapter. For more information about defining a local parameter, see “Defining a local parameter,” earlier in this chapter.

Property Description

618 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Setting options using Parameter Properties—AdvancedUse Parameter Properties—Advanced to customize the appearance of parameters that appear in Requester and on the request page. Parameter Properties—Advanced supports customizing the following user interface options:

■ Text box

■ Drop-down list

■ Radio button

■ Check box

In Parameter Properties—Advanced, when you select a user interface item to customize, the available options for that item appear.

For more information about customizing user-interface options, see the following sections later in this chapter:

■ “Customizing a text box on the request page”

■ “Customizing a drop-down list on the request page”

■ “Customizing a radio button on the request page”

■ “Customizing a check box on the request page”

How to display options in Parameter Properties—Advanced

1 In Parameter Properties—General, choose Advanced.

Parameter Properties—Advanced appears.

2 In Show as, select one of the following options:■ Text box■ Drop-down list (combo box)■ Radio buttons■ Check box

Check box is an available option for adding or modifying only a Boolean parameter.

The options available for the selection appear in Parameter Properties—Advanced. For example, the options available to modify a sample drop-down list appear in the following illustration.

C h a p t e r 1 8 , D e s i g n i n g a r e p o r t p a r a m e t e r 619

Customizing a text box on the request page

Text box supports the user typing a value to replace an optional default value you provide. Use a text box for:

■ Typing a password

■ Typing a single value

■ Selecting a date and time using Select Date and Time

■ Supplying an ad hoc expression using the ad hoc expression builder

In Parameter Properties—Advanced, to customize a text box, the following options are available:

■ If you select Password field, the characters a user types in the text box in Requester appear as asterisks. To run the report object executable (.rox) file, if you select Required, the user must provide a value. A user’s request requires a value before it can continue.

■ If the parameter’s type is ad hoc, choose the arrow to display the ad hoc expression builder.

■ If you change a parameter’s type to Boolean, which is not supported for this text box, any value you provided disappears from the text box. The text box changes to a drop-down list, which displays False as the default value.

620 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Customizing a drop-down list on the request page

Drop-down list (combo box) supports the user choosing a parameter value from a drop-down list or typing a value:

■ Requester supports the user choosing an entry from a drop-down list or typing a value in the field.

■ On the request page users view in a web browser, which does not support typing a value in the drop-down list (combo box), e.Report Designer Professional adds the following item to the bottom of a drop-down list:

<Type another value>

An example drop-down list appears in the following illustration.

To support typing a value on the request page, if the user chooses <Type another value>, the web browser displays a text box in which the user types a value as shown in the following illustration.

How to customize a drop-down list using Parameter Properties—Advanced

In Parameter Properties—Advanced, you can complete the following tasks to customize a drop-down list:

■ To add a new entry to the list:

1 Choose Create new entry.

A text field appears.

2 Type text or choose the arrow to display ad hoc expression builder.

To add the entry to the list, press Enter.

Type text

Choose the arrow to display ad hoc expression builder

C h a p t e r 1 8 , D e s i g n i n g a r e p o r t p a r a m e t e r 621

■ In the list, to support editing an entry, choose the entry.

■ To move an entry up or down in the list, select the entry and choose the up or down arrow.

■ To display the entry as the default value that appears on the request page, select an entry and choose the check mark.

■ To support the user typing a value that does not appear in the list, select Allow user to type a value. Allow user to type a value is not available for an ad hoc or date parameter.

■ To sort the drop-down list values, select Sort alphabetically.

■ If a parameter’s type is date, in List of values:■ To add a value, type an expression or date value.■ To build an expression, choose the arrow to access the ad hoc expression

builder.

■ To select a date or time, choose Builder.

Select Date and Time appears.

Select a date and time. Choose OK.

■ If a parameter’s type is Boolean, the initial default value setting is False and:■ You can select Default value is True.■ You cannot sort Boolean values alphabetically. ■ You can change the labels for Boolean True and False that appear in the

drop-down list as shown in the following illustration.

622 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Customizing a radio button on the request page

A radio button supports a user selecting a value by selecting its radio button. Selecting a radio button removes a selection from other radio buttons in a group. Use radio buttons to:

■ Enable a user to view all available choices.

■ Display descriptive labels for which the user selects Boolean values.

A group of radio buttons requires a default value. If you do not select a default value, e.Report Designer Professional selects the first radio button value on Parameter Properties—Advanced as the default value.

C h a p t e r 1 8 , D e s i g n i n g a r e p o r t p a r a m e t e r 623

In Parameter Properties—Advanced, you can complete the following tasks to customize a radio button:

■ If the parameter’s type is date, to select a date or time, choose Builder to access Select Date and Time on which you can create a label for the radio button.

■ If a parameter’s type is Boolean, the initial default value setting is False and:■ You can select Default value is True. ■ You can change the labels for Boolean True and False values that appear

for radio buttons, as shown in the following illustration.

Check appears for default value

624 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Customizing a check box on the request page

Check box supports a user choosing a value by selecting its check box. Check box is available for a Boolean parameter only. Check box is not available for other parameter types.

If a parameter’s type is Boolean, the initial default value setting is False. In Parameter Properties—Advanced, in Check box default value, select True to change the default value.

Setting a default value for an ad hoc parameterTo set a default value that appears in Requester or on the request page for an ad hoc parameter, use the ad hoc expression builder in Parameter Editor or Parameter Properties. The ad hoc expression builder items and their descriptions appear in the following table.

Ad hoc expression builder item Description

> Greater than.

< Less than.

>= Greater than or equal to.

<= Less than or equal to.

C h a p t e r 1 8 , D e s i g n i n g a r e p o r t p a r a m e t e r 625

In Parameter Properties—General, typing a value for Default value that is not an expression implies the equal to expression.

For more information about specifying values for an ad hoc parameter, see Chapter 4, “Running an e.report,” in Part 3, “Using an e.report with desktop applications,” in Using e.Reports.

How to set a default value for an ad hoc parameter

1 In Parameter Editor, select an ad hoc parameter from the list.

Choose Modify.

Parameter Properties—General appears.

Or ( | ) Or.

And ( & ) And.

Not ( ! ) Not.

Match 1 character ( _ ) Match one alphanumeric character.

Match 0 or more characters ( % ) Match zero or more characters.

Match character in set ( [ ] ) Match one of the characters specified as list or range.

Range of values ( - ) Range.

Escape character ( \ ) Escape the following character.

Grouping Choose to add opening or closing parentheses.

Decimal separator Choose to add the locale-specific decimal separator.

Ad hoc expression builder item Description

626 D e v e l o p i n g A d v a n c e d e . R e p o r t s

2 In Default value, choose the ad hoc parameter’s arrow as shown in the following illustration.

3 From the drop-down list, choose an expression item. For example, choose the following expression item:

>=

In Default value, the expression appears.

4 Type a value, such as:

500

In Default value, the value appears.

5 Choose OK.

Parameter Editor appears, as shown in the following illustration.

C h a p t e r 1 8 , D e s i g n i n g a r e p o r t p a r a m e t e r 627

6 In Parameter Editor, choose Close.

Sorting parameters on the request pageAs the default behavior, e.Report Designer Professional sorts parameters by parameter name. To apply a different sort order, use parameter display names that can appear in alphabetical order on the request page. To sort parameters by display name, you must set the report component’s SortParamsByAlias property to True in Component Editor.

For example, to arrange Finish and Start parameters to display the Start parameter before the Finish parameter, you can use the display names A Start Time and The Finish Time.

How to sort parameters on the request page

As the default behavior, Actuate e.Report Designer Professional sorts parameters by parameter name in Requester and on the request page, even if you assigned a display name for the parameter. To sort parameters by display name, set the SortParamsByAlias property to True.

1 In the structure pane, double-click the top-level report component.

Component Editor—Properties appears.

2 Set SortParamsByAlias to True.

3 Choose Close.

628 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Saving parameter settings into an ROVWhen you build, run, and debug reports, it can be helpful to develop sets of parameter values and save them in one or more report object values (.rov) files.

In the example that appears in “How to save parameter values into an ROV,” later in this chapter, you complete the following tasks:

■ Create a parameter for the color of the rectangle control.

■ Create a set of parameter values in Requester and save them into a report object values (.rov) file.

How to save parameter values into an ROV

The report object values (.rov) file contains the report’s parameter settings, such as the output file name and the color of the box. To save parameter values into an ROV for repeated use:

1 Choose Report➛Design Properties.

Design Properties—Report Settings appears.

2 In Parameters, select Prompt for Parameters. Choose OK.

3 Create a parameter. In this example, the steps are:

1 To display Component Editor, double-click a rectangle control.

RectangleControl—Component Editor—Properties appears.

2 Select FillColor.

Select Parameter at the bottom of RectangleControl—Component Editor—Properties.

Property Parameter Info appears.

C h a p t e r 1 8 , D e s i g n i n g a r e p o r t p a r a m e t e r 629

3 To accept the default values for Parameter Name and Local scope, choose OK.

<ParmFillColor> appears in FillColor.

4 To open Parameter Properties, choose Builder.

Parameter Properties—General appears.

5 Provide the following values:- In Type, select Integer.- To assign a Group, leave the field blank. This property is optional.- To assign the optional display name to appear on the request page,

in Display name, type:

Color of Box

- To assign a default color value, in Default value, type:

255

This value makes the box red if the user changes no values when heruns the report.

In Parameter Properties—General, choose OK.

6 In Component Editor—Properties, choose Close.

630 D e v e l o p i n g A d v a n c e d e . R e p o r t s

4 Choose Report➛Build and Run.

Requester—CitiesandSquares.rop appears.

5 In Requester—CitiesandSquares.rop:

1 Provide the following parameter values:- Output Parameters—Output File Name, type:

Yellowsquare.roi

- In Color of Box, type the Actuate Basic code value for yellow:

65535

For more information about color code values, see RGB function in Chapter 2, “Statements and functions,” in Actuate Basic Language Reference.

Choose Save As.

Specify Parameter File Name appears.

2 In Specify Parameter File Name, in File Name, type a name for the ROV.

3 Choose Save.

Requester—CitiesandSquares.rop appears.

4 Choose Cancel.

C h a p t e r 1 8 , D e s i g n i n g a r e p o r t p a r a m e t e r 631

6 Choose Report➛Design Properties.

Design Properties—Report Settings appears.

7 Select Read from a File.

In Read from a File, type:

Yellowsquare.rov

Choose OK.

8 Choose Report➛Build and Run.

Requester—CitiesandSquares.rop does not appear. Instead, the run processes take the parameter settings from Yellowsquare.rov.

The report name is Yellowsquare.roi, as you specified in Requester—CitiesandSquares.rop, and the square is yellow. Yellowsquare.roi appears in Yellowsquare—Report Viewer, as shown in the following illustration.

To create another ROV, change the setting on Design Properties—Report Settings back to the default value, Prompt for Parameters. Provide some different parameter values in Requester and save them into another ROV.

632 D e v e l o p i n g A d v a n c e d e . R e p o r t s

For information about Design Properties and using the report object values (.rov) file to test a report, see “Setting report parameter options,” later in this chapter.

Setting report parameter optionsYou can use parameters and a saved report object values (.rov) file to test versions of a report. To assign parameter values for each build and run or simple run of a report, you can specify that Actuate processes perform one of the following actions:

■ Prompt for Parameters, which is the default setting.

If you use this setting, Requester or the request page appears when a user runs the report. Requester or the request page supports your specifying parameter values when you run a report.

■ Use Default Values.

Select Use Default Values if you want to use the default parameter values that appear in Requester or on the request page and in other parts of e.Report Designer Professional and if you have no need to re-enter parameters before you run and view the report. This setting suppresses Requester and the request page.

■ Read from a File.

This setting supports your choosing or browsing for a saved report object values (.rov) file and uses the specified ROV when you run a report. This setting also suppresses Requester and the request page. Actuate e.Report Designer Professional does not support this option for previewing a report in DHTML using the publish tool. If you select this option and choose Publish Report Executable to Server, the request page appears in DHTML Viewer. For more information about the publish tool, see “Publishing a report object executable file to a server,” in Chapter 1, “Designing an e.report with the report wizard.”

Actuate e.Report Designer Professional saves the report parameter options you set in Design Properties into the report object design (.rod) file. For more information about saving parameter settings in a report object values (.rov) file, see “Saving parameter settings into an ROV,” earlier in this chapter.

How to set report parameter options

1 Choose Report➛Design Properties.

Design Properties—Report Settings appears.

C h a p t e r 1 8 , D e s i g n i n g a r e p o r t p a r a m e t e r 633

2 In Report Settings, select one of the following options:■ Prompt for Parameters■ Use Default Values■ Read from a File

When you run the report, the Actuate processes use the correct set of parameter values.

For information about using Design Properties—Report Settings to support simulated page-level security viewing, see Chapter 8, “Designing a report with page-level security,” in Programming e.Reports.

Deleting a parameterTo delete a parameter, you can reverse the procedure with which you define it. For example, if you define the parameter through the Properties page, return to that page to delete the parameter.

How to delete a parameter using Parameter Editor

If you add a parameter using only Parameter Editor, the parameter is global and not attached to any component. To delete this kind of parameter:

1 Choose Tools➛Parameters.

Parameter Editor—<report name> appears.

634 D e v e l o p i n g A d v a n c e d e . R e p o r t s

2 Select the parameter to delete.

Choose Delete.

How to delete a local or global parameter that supplies a property value

1 Double-click the component.

<Component name>—Component Editor—Properties appears.

2 In the right column, select the parameter name.

Deselect Parameter.

How to delete a local parameter not referred to by properties

1 Double-click the component.

<Component name>—Component Editor—Properties appears.

2 Choose Variables.

<Component name>—Component Editor—Variables appears.

3 Select the parameter to delete.

On <component name>—Component Editor—Variables, you cannot delete a parameter that is referred to by or that sets a property value. To delete a parameter that supplies a property value, see “How to delete a local or global parameter that supplies a property value,” earlier in this chapter.

Choose Delete.

Deselect

Select name

C h a p t e r 1 8 , D e s i g n i n g a r e p o r t p a r a m e t e r 635

How to delete an ad hoc parameter

1 Choose View➛Data Source.

DataSource—Query Editor appears.

2 In Query Editor, choose Conditions.

Query Editor—Conditions appears.

3 Select the ad hoc parameter to delete.

Press Shift+Delete.

e.Report Designer Professional removes the ad hoc parameter from the list.

Using parameters to manage a large reportLike other application design projects, report development projects must reflect a clear understanding of user requirements. Considering the usability of the report as the major design criterion, Actuate e.Report Designer Professional provides design techniques to make large reports more usable. These design techniques include options to design reports with page-level security and report bursting. For information about these techniques, see Chapter 13, “Understanding report bursting techniques,” and Chapter 8, “Designing a report with page-level security,” in Programming e.Reports.

Sometimes, you need to reduce the size of a large report to improve the report generation workload balance. To redesign a large report, consider generating the report on demand or restructuring the report. For information about restructuring a report, see “Restructuring a large report,” in Chapter 11, “Working with sections.”

Add parameters to reports to produce the parts of the original large report you need. On-demand reporting works well when the database content remains constant during the time you need the reports. To design an on demand report, you must:

Click here then press Shift+Delete

636 D e v e l o p i n g A d v a n c e d e . R e p o r t s

■ Understand how you use the current report

■ Add parameters to specify the parts of the original large report to run

For example, the Detail report in \Program Files\Actuate7\Erdpro\Examples\Detail is a large report showing sales activity sorted by office, sales representative, customer, and order. The report design contains one data source that supplies data to four smaller reports represented by the nested group section components OfficeGroup, SalesRepGroup, CustomerGroup, and OrderGroup. The following illustration shows the report’s structure.

Requester organizes the parameters controlling the content by subreport.

C h a p t e r 1 8 , D e s i g n i n g a r e p o r t p a r a m e t e r 637

In environments that require frequent and lengthy access to the database tables used in the SQL query, you can further optimize the Detail report by creating a custom SQL query for each group section instead of using a single SQL query for the report. For more information, see “Optimizing SQL queries,” in Chapter 7, “Using a query data stream.”

The Detail report design illustrates using parameters in a long report to produce smaller reports. You type ad hoc parameters using Query by Example (QBE) syntax to select information about offices, sales representatives, customers, and orders.

To view information about the Boston office’s sales, type the following text in the City parameter:

'Boston'

638 D e v e l o p i n g A d v a n c e d e . R e p o r t s

To view information about customers who have a credit rank of C, type the following text in the Credit Rank parameter:

'C'

as shown in the following illustration. If you type C, that value returns any credit rank values that begin with C. If the data contains credit ranks of C1, C2, and C3, those credit rank values appear in the report object instance (.roi) file.

For more information about using Query by Example (QBE) syntax to specify report parameters, see Chapter 4, “Running a report,” in Using e.Reports.

A p p e n d i x A , U s i n g a c o n f i g u r a t i o n f i l e 639

A p p e n d i x

AAppendix AUsing a configuration

fileThis chapter contains the following topics:

■ About configuration files

■ Specifying the configuration file location

■ Creating a configuration file

■ Working with a sample configuration file

■ Choosing a configuration file on the report wizard

■ Using configuration files with Actuate 7 products

640 D e v e l o p i n g A d v a n c e d e . R e p o r t s

About configuration filesConfiguration files support administering files that are external to report designs, such as component libraries and Actuate Basic source files. Actuate e.Report Designer Professional simplifies the administration of these files by saving their paths in a configuration file, a text file in XML format that is referenced by a URL.

Configuration files make building reports much easier in several key ways. The configuration file does the following:

■ Locates component libraries and Actuate Basic source files.

■ Identifies the set of libraries and Basic files to be included in each new design.

■ Identifies site-specific information about databases.

When you build a report, Actuate e.Report Designer Professional makes available all the database connections, libraries, and Actuate Basic files that are listed in the configuration file. When you choose a database connection, e.Report Designer Professional finds the connection properties for that connection in the configuration file. The configuration file can also specify libraries and Basic files that are automatically included in designs.

The database connections you specify in the configuration file are used at design time and at run time.

At design time, the database connections are used in these instances:

■ When you create a report

The connections are listed on the Choose Database page of the report wizard.

■ When you change databases

The connections are listed on the Choose Database page of the Database Connection wizard.

At run time, the database connections are used in these instances:

■ When you log in to a database on opening Query Editor

■ When you generate a report using any Actuate product

For more information about design-time and run-time connection properties, see “Setting connection properties,” later in this chapter.

A configuration file can include an unlimited number of other configuration files. For example, you might start with a standard configuration file that is part of your installation. Later, you might collect additional libraries or Basic files that you want included in your configuration. In this case, you can create your own configuration file that includes the standard configuration file and

A p p e n d i x A , U s i n g a c o n f i g u r a t i o n f i l e 641

lists your own libraries and Basic files. You can then create report designs that point to your custom configuration file. See “Creating a configuration file,” later in this chapter.

Specifying the configuration file locationMultiple users can access a configuration file referenced by a URL on a company’s intranet web server. When database information changes, changing the configuration file referenced by the URL allows you to quickly and easily communicate the changes to all users.

Referencing configuration files by a URL means that the files referenced by the configuration file can be on your system or anywhere on a network you are connected to.

For more information about specifying the configuration file location, see “Choosing a configuration file” in Chapter 5, “Customizing the design environment,” and “Using configuration files with Actuate 7 products,” later in this chapter.

Creating a configuration fileThis topic describes the syntax of a configuration file. A configuration file is a text file in XML format. You can use any text editor to create or modify the file.

Understanding XML basicsA text file in XML format consists of a series of elements of this form:

<Element>...</Element>

These elements are case-sensitive.

Elements can include text:

<Element>text</Element>

Elements can also include other elements:

<Element1><Element2>

text</Element2>

</Element1>

Elements can have attributes of this form:

<Element attribute="value">

642 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Attribute values must be enclosed in quotation marks.

You can add comments to the configuration file in this form:

<!-- text -->

Understanding configuration file sectionsA configuration file has three sections. The file can have any or all of these sections, in any order. Each section is a piece of XML code delimited by a start and end tag. For example, the Include section is delimited by the <Include> and </Include> tags.

Include sectionThe Include section specifies other configuration files to include in the design. You can include multiple configuration files with a design, so the configuration file can have multiple Include sections. Each Include section can contain only one file name.

Design sectionThe Design section specifies connection types, libraries, and templates to include in the design. This section affects the report when it is being designed, rather than when it is run. There is only one Design section, but it can specify multiple libraries, templates, and connections.

Runtime sectionThe Runtime section specifies properties for connections. These properties take affect when the report is run. There is only one Runtime section, but it can specify properties for multiple connections.

Search Path sectionThe Search Path section specifies additional directories to search when locating included files in a design file.

Reviewing a summary of configuration file syntaxThe following syntax conventions are used.

Syntax Means Example

[...] Optional [Alias="alias"]

name Variable template_name

A p p e n d i x A , U s i n g a c o n f i g u r a t i o n f i l e 643

The following is a summary of configuration file syntax:

<Config>

<Include>include_file_name

</Include>

<Design><Library

[Autoinclude="true"|"false"][Alias="alias"]>library_name

</Library>

<Template [Alias="alias"][Description="description"]>template_name

</Template>

<Connection Type="connection_type"[Alias="alias"][Description="description"][DefinedIn="library_name"][IsDefault="true"|"false"]>[<Property PropName="prop_name">

property_value</Property>]

</Connection></Design>

<Runtime><ConnectOptions Type="connection_type">

<Property PropName="prop_name">property_value

</Property></ConnectOptions>

</Runtime>

<SearchPath><Location>..\Path</Location>

</SearchPath>

</Config>

The following topics describe the syntax for each of the tasks the configuration file performs. For a sample configuration file, see “Working with a sample configuration file,” later in this chapter.

644 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Including another configuration fileTo include another configuration file, include its file name in the Include section of the configuration file:

<Include>include_file_name

</Include>

In this case, file is an absolute or relative path name or an absolute or relative URL to the included configuration file name. If you use a relative path, the path is read as being relative to the path of the container configuration file.

For example, you might want to build a report that uses libraries referenced in multiple configuration files. In the configuration file for the report design, you would add a separate line for each of the configuration files you want included.

Including a library or Basic fileYou include libraries and Basic files in the Design section of the configuration file. The Design section is enclosed with the start and end tags <Design> and </Design>. To make a library or Basic file available for a report design, you include its file name in the configuration file, as follows:

<Library> [Autoinclude="true"|"false"][Alias="alias"]>library_name

</Library>

The library name can be absolute or relative to the path of the configuration file.

The autoinclude option specifies whether the library or Basic file is automatically included in new report designs that use this configuration file. To automatically include the library or Basic file, set the autoinclude option to true, as follows:

<Library Autoinclude="true"[Alias="alias"]>library_name

</Library>

If the autoinclude option is set to false or omitted, the library or Basic file is made available for use in report designs but is not added to them automatically. You can choose the library in Library Organizer.

The library alias is optional. The alias appears in the Description column of Library Organizer. For more information about Library Organizer, see “Including a library in a design” in Chapter 6, “Working with libraries.”

A p p e n d i x A , U s i n g a c o n f i g u r a t i o n f i l e 645

Specifying a templateWhen you create a new report, Create New Report offers templates on which to base the report object design (.rod) file. You specify these template files in the configuration file as follows:

<Template [Alias="alias"][Description="description"]>template_name

</Template>

The template file must be a report object design (.rod) file. The configuration file ignores other file types. The template name can be a URL or a file on your local system. The name can be absolute or relative to the path of the configuration file.

The alias is an optional descriptive name for the template. For example, if the template name is a long URL, you might want to provide a short descriptive name to display in Create New Report instead of the URL. If you do not specify an alias, the base file name without the file extension is used.

If multiple templates have the same base file name or alias, a number is added to the duplicate entries in Create New Report. For example, if two templates have the base file name template_name and neither template has an alias, the templates appear in Create New Report as template_name and template_name (2).

The description appears in the Description area of Create New Report. For more information about Create New Report, see “Creating a new report design” in Chapter 4, “Using Design Editor.”

For more information about including libraries that a template references, see “Specifying a search path,” later in this chapter.

Specifying a database connectionYou can specify a database connection to use at design time as follows:

<Connection Type="connection_type"[Alias="alias"][Description="description"][DefinedIn="library_name"][IsDefault="true"|"false"]>[<Property PropName="prop_name">

property_value</Property>]

</Connection>

646 D e v e l o p i n g A d v a n c e d e . R e p o r t s

The Type attributeThe connection type is required. It specifies the name of the component that creates the connection. The component can be specified in a user-defined library, or it can be a component defined in the Actuate Foundation Class library. The configuration file can contain multiple entries for the same connection type, but each entry must have a different alias. For example, you might have several entries for the AcProgressConnection type, each with different property values, such as host, database, and port name.

The Alias and Description attributesThe connection alias and description are optional. Use them to describe the purpose of the connection. The alias and description appear on the Choose Database page of the report wizard, as shown in the following illustration. If you do not provide an alias and description in the configuration file, e.Report Designer Professional uses the connection component’s DisplayName property and Description.

For more information about configuration files and the report wizard, see “Choosing a configuration file on the report wizard,” later in this chapter.

The DefinedIn attributeThe DefinedIn attribute is optional. The library name can be absolute or relative to the path of the configuration file. It specifies the library that contains the component type. If you choose this connection when you are building a report, e.Report Designer Professional automatically includes the library specified here. If you do not define the library that contains the component type here, you must

A p p e n d i x A , U s i n g a c o n f i g u r a t i o n f i l e 647

make sure that the required library is included when you build a report using this connection.

The IsDefault attributeYou can set the default connection type with the IsDefault attribute. The default value is False. Only one default connection is allowed. If multiple default connections appear, only the last one in the file retains the default setting.

The default connection is used when the user creates a blank report design. For information about creating a blank report design, see “How to create a blank report design” in Chapter 4, “Using Design Editor.”

You can also specify these default settings with registry settings. For more information about specifying a default database connection with registry settings, see “Choosing the default connection and data source” in Chapter 4, “Using Design Editor.”

The Property elementYou can use the Property element to specify the following:

■ A property value that is used when the user chooses this connection type in the report wizard.

Type the property name as it appears on the Properties page. For more information about how the report wizard uses information in the configuration file, see “Choosing a configuration file on the report wizard,” later in this chapter.

■ The ConfigKey property.

The ConfigKey property matches a design-time connection with run-time connection properties. For more information about the ConfigKey property and run-time connection properties, see “Setting connection properties,” later in this chapter.

Setting connection propertiesYou set run-time connection properties in the Runtime section of the configuration file. The connection does not have to appear in the Design section. The Runtime section is enclosed with the start and end tags <Runtime> and </Runtime>.

Run-time connection properties are used when Actuate connects to the database. Actuate connects to the database in these cases:

■ The report developer uses Query Editor.

■ The report user runs a report on the client.

■ The report user runs a report on the server.

648 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Run-time connection properties take precedence over any properties set in the connection component.

You set run-time connection properties in the configuration file using the following syntax:

<ConnectOptionsType="connection_type">

<Property PropName="prop_name">property_value

</Property></ConnectOptions>

The property name attribute is required. You use this attribute for each property in the connection component. The property name must match the name of a property in the connection component. The name is not case-sensitive. For information about the set of properties for each connection type, see the Actuate Foundation Class Reference.

For example, ODBC connections require the name of the data source as a property. If the name of the data source is Design Emporium, the code in the configuration file that specifies that property name and value would be as follows:

<ConnectOptions Type="MyODBCConnection"><Property PropName="DataSource">

Design Emporium</Property>

</ConnectOptions>

Design-time connection properties are compiled in the report design. If you run a report without a configuration file, the design-time connection properties are used. If the properties of the connection change, you must change the report design manually. Alternatively, you can use a configuration file’s run-time connection properties to override design-time connection properties for a specified connection type.

To use the configuration file’s run-time connection properties, set the connection component’s ConfigKey property using the Property element for the connection in the Design section of the configuration file. Or, if the connection component is a reference to a connection component in a library, set the ConfigKey property in the library. The value of the ConfigKey property should be the same as the value of the Type attribute for the ConnectOptions element that specifies the run-time connection properties. For example, if the ConnectOptions element’s Type attribute is set to MyODBCConnection, the ConfigKey property should have the same value. If the ConfigKey property is not set, Actuate uses the fully qualified name of the connection component:

A p p e n d i x A , U s i n g a c o n f i g u r a t i o n f i l e 649

<Connection Type="ODBCConnection"><Property PropName="ConfigKey">

MyODBCConnection</Property>

</Connection>

For more information about the Property element, see “The Property element,” earlier in this chapter. For more information about setting run-time connection properties, see “Setting connection properties,” earlier in this chapter.

Specifying a search pathYou specify the directories for e.Report Designer Professional to search when locating included files in the Search Path section of the configuration file. The Search Path section is enclosed with the start and end tags <SearchPath> and </SearchPath>.

To specify the directories to search, include each directory name in the configuration file, as follows:

<SearchPath>directory_name

</SearchPath>

The directory name can be absolute or relative to the path of the configuration file.

When you work with a report template, use the search path to ensure that libraries included in the template are available to your report. For example, suppose you use a template from the directory \\shared\templates. The template is available to your configuration file and includes a library using a relative path, which is located in \\shared\templates\lib. The path that includes this library in the template is \lib\sharedlib.rol. To ensure that new reports created from this template include sharedlib.rol using the same relative path, add the library’s location to the configuration file as a search path, as shown in the following example.

<SearchPath><Location>\\shared\templates</Location>

</SearchPath>

Using this configuration, the design includes the template's library as lib\sharedlib.rol.

650 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Working with a sample configuration fileThe following sample code shows how a configuration file can include another configuration file and use multiple design-time and run-time properties:

<Config>

<Include>C:\Lib\Libconfig.xml

</Include>

<Design><Library

Autoinclude="true"Alias="Corporate Headings">Head.rol

</Library>

<Template Alias="Weekly Report">Weeklyreport.rod

</Template>

<Template Alias="Daily Report">Dailyreport.rod

</Template>

<Connection Type="devODBC"Alias="Dev DB Connections"DefinedIn="C:\Lib\Dbconnections.rol">

</Connection></Design>

<Runtime><ConnectOptions Type="EnterpriseDBConnection">

<Property PropName="DllPath">ODBC32

</Property><Property PropName="DataSource">

Design Emporium</Property>

</ConnectOptions></Runtime>

</Config>

The following is the included configuration file, Libconfig.xml:

<Config>

<Design>

A p p e n d i x A , U s i n g a c o n f i g u r a t i o n f i l e 651

<Library Autoinclude="true"Alias="General Components">C:\Program Files\Actuate7\Erdpro\Examples\Libraries\GENERAL.ROL

</Library>

<Library Autoinclude="true"Alias="Miscellaneous Summary and Flow Components">C:\Program Files\Actuate7\Erdpro\Examples\Libraries\SFLIB.ROL

</Library>

<Library Autoinclude="true"Alias="Graph and Issues Summary Components">C:\Program Files\Actuate7\Erdpro\Examples\Libraries\MYLIB.ROL

</Library></Design>

</Config>

Other sample configuration files are installed with Actuate e.Report Designer Professional in the \Program Files\Actuate7\Erdpro\Examples\ConfigurationFile folder.

Choosing a configuration file on the report wizardUse the report wizard’s Data Sources page to choose how to get data for the report.

652 D e v e l o p i n g A d v a n c e d e . R e p o r t s

You must select one of the following:

■ Choose from a list of predefined data sources.

■ Choose from a list of predefined databases.

■ Build a new database connection.

Once you make a choice, e.Report Designer Professional uses information in the configuration file to help you proceed. The examples in the following topics use a sample configuration file installed with Actuate e.Report Designer Professional, \Program Files\Actuate7\Erdpro\Examples\ConfigurationFile\Sample_configuration_file.xml.

For more information about the report wizard, see Chapter 1, “Designing an e.report with the report wizard.”

Choosing from a list of predefined data sourcesIf you select Choose from a list of predefined data sources, Choose Data Source appears.

The Choose Data Source page lists data sources that are defined in included libraries, as specified in the configuration file. The sample configuration file includes the library Erd_sample_library.rol:

<Library Autoinclude="true"Alias="Sample Data Connections and Data Sources">Library/Erd_sample_library.rol

</Library>

A p p e n d i x A , U s i n g a c o n f i g u r a t i o n f i l e 653

The DataSource component must contain both a Connection component and a DataRow component.

The Name that appears on the Choose Data Source page is specified by the DataSource component’s DisplayName property.

The Description that appears on the Choose Data Source page is specified by the Description on the DataSource component’s Class tab.

654 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Choosing from a list of predefined databasesIf you select Choose from a list of predefined databases, Choose Database appears.

Connections defined in included librariesThe Choose Database page lists database connections that are defined in included libraries, as specified in the configuration file. The sample configuration file includes the library Erd_sample_library.rol:

<Library Autoinclude="true"Alias="Sample Data Connections and Data Sources">Library/Erd_sample_library.rol

</Library>

The Name that appears on the Choose Database page is specified by the Connection component’s DisplayName property.

A p p e n d i x A , U s i n g a c o n f i g u r a t i o n f i l e 655

The Description that appears on the Choose Database page is specified by the Description on the Connection component’s Class tab.

Connections defined with the DefinedIn attributeThe Choose Database page also lists database connections that are defined in the library specified with the DefinedIn attribute in the configuration file. In the sample configuration file, the DefinedIn attribute specifies the library Sample_sfdata_library.rol:

<Connection Type="Sample_dataconnection_sfdata"Alias="SFData Sample Database"DefinedIn="Library/Sample_sfdata_library.rol"Description="Connects to the sfdata sample database (defined in config

file)"IsDefault="True">

</Connection>

The Name and Description that appear on the Choose Database page are specified by the Alias and Description attributes in the configuration file. Because the IsDefault attribute is set to True, this connection is the default selection.

656 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Connections defined in the Actuate Foundation ClassThe Choose Database page also lists connection components that are defined in the Actuate Foundation Class library if the Alias attribute is set. For example, to include an ODBC Connection on the Choose Database page, include the following code in the configuration file:

<Connection Type="AcODBCConnection"Alias="My ODBC Connection">

</Connection>

Build a new database connectionIf you choose Build a new database connection, the Build New Database Connection page appears.

The connection types listed on the Build New Database Connection page are defined in the Actuate Foundation Class library. You can use the Property element to provide default values for any of the properties listed on this page. For example, to provide the default value quikdata for an ODBC Connection’s DataSource property, include the following code in the configuration file:

<Connection Type="AcODBCConnection"[IsDefault="true"]><Property PropName="DataSource">

quikdata</Property>

</Connection>

A p p e n d i x A , U s i n g a c o n f i g u r a t i o n f i l e 657

Do not specify an alias for the connection type. If you specify an alias, the connection type is listed on the report wizard’s Choose Database page rather than on the Build New Database Connection page. For more information about the Choose Database page, see “Choosing from a list of predefined databases,” earlier in this chapter.

If you set the IsDefault attribute to True, this connection type is the default setting when a user builds a new connection. If you choose a different connection type on the Build New Database Connection page, this connection type is stored as the default setting in the registry, and it is the default setting the next time you display the Build New Database Connection page.

Using configuration files with Actuate 7 productsYou can also use configuration files with the following Actuate 7 products:

■ e.Report Designer

■ iServer

■ End User Desktop

Specifying a configuration file with e.Report DesignerYou specify a configuration file with e.Report Designer exactly as you do with e.Report Designer Professional. For information about specifying a configuration file with e.Report Designer, see Chapter 5, “Customizing the design environment,” in Designing e.Reports.

Specifying a configuration file with an iServerTo specify a configuration file with iServer, you use an iServer System parameter. If an iServer System parameter is not defined, Actuate uses the database connection properties that are stored with the report object executable (.rox) file. For more information about specifying a configuration file with an iServer, see Chapter 3, “Configuring the Actuate server,” in Administering Actuate iServer System.

658 D e v e l o p i n g A d v a n c e d e . R e p o r t s

A p p e n d i x B , W o r k i n g w i t h R T F a n d H T M L t a g s i n a d y n a m i c t e x t c o n t r o l 659

A p p e n d i x

BAppendix BWorking with RTF and

HTML tags in a dynamictext control

This appendix contains the following topics:

■ Working with RTF tags

■ Working with HTML tags

660 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Working with RTF tagsThe following table lists the supported RTF structural and definition tags.

RTF tag supported Description

\* This extended feature group indicator specifies the contents of groups identified in this way are ignored.

\blueN Specifies blue value in color table.

\colortbl Specifies the color table.

\deftabN Specifies default value for tab spacing. N is the spacing in twips.

\fonttbl Specifies the font table.

\greenN Specifies the green value in color table.

\redN Specifies the red value in color table.

\rtfN Specifies the RTF dynamic text. N indicates the major RTF version number. The value of N must be 1.

\ucN Specifies the number of text characters to skip following a \uN tag. RTF text can contain alternative representations for Unicode characters for use by RTF readers that do not support Unicode. RTF readers that do not support Unicode skip the \uN tag and display the following character. For example, \rtf1\u8364 E displays the Euro currency symbol on an RTF reader that supports Unicode and E on a reader that does not support Unicode.RTF text that contains alternative representations for Unicode characters uses \ucN to enable RTF readers that support the \uN tag to display the Unicode character(s) and skip the following character(s).

\uN Specifies a Unicode character.

A p p e n d i x B , W o r k i n g w i t h R T F a n d H T M L t a g s i n a d y n a m i c t e x t c o n t r o l 661

The following table lists the supported RTF paragraph formatting tags.

The following table lists the supported RTF character formatting tags.

RTF paragraph tag supported

Description

\fiN Specifies first line left indent. N indicates the indent in twips. \fi is additive with \li and N can be a negative number. For example, \li1440\fi-720 makes the first line indented 0.5" and remaining lines indented 1.0".

\liN Specifies left indent. N indicates the indent in twips.

\pard Specifies resetting all paragraph formatting attributes.

\qc Specifies centering text.

\ql Specifies left-aligned text.

\qr Specifies right-aligned text.

\riN Specifies right indent. N indicates the indent in twips.

\saN Specifies vertical space after the paragraph. N indicates the space in twips.

\sbN Specifies vertical space before the paragraph. N indicates the space in twips.

\slN Specifies vertical line spacing. N indicates the total line height in twips.

\slmultN Specifies vertical line spacing multiplier. N indicates the multiplication type.

\txN Specifies the tab stop. N indicates the tab stop position in twips.

RTF character tag supported

Description

\b Specifies start bold text.

\b0 Specifies end bold text.

\cfN Specifies color number. N indicates the color number in the color table.

\fN Specifies font number. N indicates the font number in the font table.

662 D e v e l o p i n g A d v a n c e d e . R e p o r t s

The dynamic text control recognizes any Unicode character encoded in the standard RTF form \un where n is the decimal Unicode value of the character. If the specified character does not exist in the requested font, the null symbol (¤ , Unicode value 127) is used.

The dynamic text control recognizes any character encoded in the standard RTF format \'xx where xx is the 2-digit hex value of the character. This format is treated as a Unicode value, regardless of the original document encoding. If the specified character does not exist in the requested font, the null symbol (¤ , hex value 0x7f) is used.

The following table lists the supported special characters.

\fsN Specifies font size. N indicates the font size in half points. Because AFC does not recognize fractional font sizes, half point sizes round to integers. For example, \fs21 indicates font size 10.5pt, which rounds to 10pt.

\i Specifies start italic text.

\i0 Specifies end italic text.

\plain Specifies end all character attributes, such as bold, font, and italic.

\ul Specifies start underline.

\ul0 Specifies end underline.

RTF character tag supported

Description

Character Unicode Tag Description

\ \u92 \\ Backslash

\par Paragraph break

\<LF> Paragraph break. <LF> isASCII 10.

\<CR> Paragraph break. <CR> is ASCII 13.

\line Line break

\tab Move to next tab stop.

<TAB> Move to next tab stop. <TAB> is ASCII 8.

\emspace Non-breaking space equal in width to m

A p p e n d i x B , W o r k i n g w i t h R T F a n d H T M L t a g s i n a d y n a m i c t e x t c o n t r o l 663

Working with HTML tagsThe following table lists the supported HTML structural tags.

\enspace Non-breaking space equal in width to n

{ \u123 \{ Left curly brace

} \u125 \} Right curly brace

‘ \u145 \lquote Left single quote

’ \u146 \rquote Right single quote

“ \u147 \ldblquote Left double quote

” \u148 \rdblquote Right double quote

• \u149 \bullet Bullet symbol

– \u150 \endash En-dash

— \u151 \emdash Em-dash

\u160 \~ Non-breaking space

- \_ Non-breaking hyphen

Character Unicode Tag Description

HTML structural tag supported

Description

<HEAD> </HEAD>

Specifies HTML document header information. Actuate ignores all content between <HEAD> and</HEAD> is ignored, including any nested tags.

<!-- --> Specifies a comment. Actuate ignores all content between <!-- and -->.

<COMMENT> </COMMENT>

Specifies a comment. Actuate ignores all content between <COMMENT> and </COMMENT>.

<SCRIPT> </SCRIPT>

Specifies a script. Actuate ignores all content between <SCRIPT> and </SCRIPT>.

664 D e v e l o p i n g A d v a n c e d e . R e p o r t s

The following table lists the supported HTML paragraph formatting tags.

The following table lists the supported HTML character formatting tags.

HTML paragraph tag supported

Description

<BR> Specifies a line break.

<CENTER> </CENTER>

Specifies centering text.

<LI> </LI> Specifies a list item.

<OL> </OL> Specifies an ordered list.

<PRE> </PRE> Specifies a block of fixed-width text. The text truncates if it is wider than the dynamic text control. The text does not wrap.

<P> </P> Specifies a paragraph. Supports the ALIGN parameter.

<UL> </UL> Specifies an unordered list.

HTML character tag supported

Description

<B> </B> Specifies bold text.

<FONT> </FONT>

Specifies the font face, size, and color. If a font is not specified, Actuate uses a default font.

<I> </I> Specifies italicized text.

<TT> </TT> Specifies the default fixed-width font.

<U> </U> Specifies underlined text.

A p p e n d i x B , W o r k i n g w i t h R T F a n d H T M L t a g s i n a d y n a m i c t e x t c o n t r o l 665

The following table lists the supported HTML parameters.

The dynamic text control recognizes any Unicode character encoded in the standard HTML form &#n; where n is the Unicode value of the character. If the specified character does not exist in the requested font, the null symbol (¤ , Unicode value 127) is used.

The following table lists the supported special characters.

HTML parameter supported

Tag Description and values

ALIGN <P> Specifies the alignment. Use CENTER, LEFT, or RIGHT.

COLOR <FONT> Specifies the foreground color. Use the following:■ An RGB value specified as a 6-digit hex

number in the form #xxxxxx■ A color name from the following: aqua,

black, blue, fuchsia, gray, green, lime, maroon, navy, olive, purple, red, silver, teal, white, yellow

FACE <FONT> Specifies the font name, for example, "Arial". If a font is not specified, Actuate uses a default font.

SIZE <FONT> Specifies the font size. Use the following:■ An absolute font size specified as an

integer. Absolute font size values map to point sizes as follows: 0 or 1 = 8 pt, 2 = 10 pt, 3 = 12 pt, 4 = 14 pt, 5 = 18 pt, 6 = 24 pt, 7 or greater = 36 pt.

■ A relative font size specified as an integer with a leading + or -. Relative font sizes are interpreted as offsets from absolute font size 3. For example, +2 is interpreted as 5.

Character Unicode Name Description

" &#34; &quot; Quotation mark

& &#38; &amp; Ampersand

< &#60; &lt; Less than

> &#62; &gt; Greater than

&#8364 &euro; Euro currency symbol

666 D e v e l o p i n g A d v a n c e d e . R e p o r t s

• &#8226; &bull; Bullet point

&#160; &nbsp; Non-breaking space

¡ &#161; &iexcl; Inverted exclamation mark

¢ &#162; &cent; Cent currency symbol

£ &#163; &pound; UK pound currency symbol

¤ &#164; &curren; General currency symbol

¥ &#165; &yen; Japanese yen currency symbol

© &#169; &copy; Copyright symbol

® &#174; &reg; Registered trademark symbol

° &#176; &deg; Degree symbol

¿ &#191; &iquest; Inverted question mark

× &#215; &times; Multiplication operator

Character Unicode Name Description

I n d e x 667

IndexSymbols* (asterisk) in queries 243. (dot) operator 336: (colon) in SQL statements 246:? characters in queries 249

Numerics2D charts

formatting 450overview 431

3D chartsformatting 450overview 431, 435

Aabsolute URLs 561AC_MASTER_FONT_FULLPATH_NAME

variable 573AC_USE_DEFAULT_FONT_FILE

variable 573accessing

components 148, 150data xix, 166, 167

across platforms 562from external applications 364

Encyclopedia volumes 117flat files 168Java objects xxiiionline documentation xxviistored procedures 69

accessing online help xxviiiAcChart class 428, 448AcComponent class 47AcDetailChart class

data streams for 444examples 465guidelines for 449instantiating 456, 468, 482properties overview 466

AcGraph class 428AcHLCChart class

data streams for 444

guidelines for 449instantiating 484

AcImageControl class 364AcLeftRightPageList class 539AcMemoryDataSorter class 176AcODBCConnection type 81AcOleContainerControl class 364AcProgressConnection type 183AcSummaryChart class

data streams for 445examples 462, 470guidelines for 449instantiating 456, 468, 480methods overview 474properties overview 463, 471

activate-in-place 366activating hyperlinks 378Active Portal xxiActiveX controls xxiActuate Basic xxi

declaring report parameters 602generating and compiling code 42–43overview 51–56setting source encoding for 117writing subroutines 70

Actuate Foundation Class Library xxiadding components from 84defining connections in 656developing with 55referencing components 98–99viewing components 64

Actuate Foundation Classesderiving subclasses 53–55overview 51, 55

Actuate home page xxiiiActuate Palette Representation files.

See APR filesActuate product suite xxActuate product updates xxiiiActuate Query Option 222

See also information objectsActuate technology xviiActuate Viewer. See Viewer

668 D e v e l o p i n g A d v a n c e d e . R e p o r t s

ad hoc parameters 602–607adding at run time 196, 204changing 251configuring 607creating 605, 606defining for queries 248–251deleting 635for on demand reporting 637setting properties for 250

ad hoc queries xxiiadding

balloon help 358–359buttons to palettes 122components 83–93

for data streams 172for database connections 167, 168manually 174multiple 84to frames 92to icons 89to layout pane 90–93to query data streams 173–174to report designs 61, 62, 77, 83, 160, 161to report sections 293, 298, 308, 313, 316to slots 85–88, 90to structure pane 88–90

conditional sections 312conditions

for aggregate rows 201to queries 179, 196–197, 201to value expressions 346–347

conditions to queries 205context-sensitive help 357–358controls 330–333

for images 360–364frames 326, 327, 328–330group sections 295, 303headers and footers 546–553hyperlinks

as URLs 387to web-based reports 386

libraries to report designs 115parallel sections 316report sections 292sequential sections 308source files to designs 148, 154, 157specific columns to queries 190, 201

specific columns to reports 19tables to queries 19, 68, 183, 241templates 645titles to reports 12

AddPoint method 444AddValueIndex method 377Adhoc Conditions page 249, 251AFC. See Actuate Foundation ClassesAfter slot (Design Editor)

group sections 300placing dynamic text controls 406visual components in 87

aggregate controlsassigning values to 334, 338–347assigning values with conditions 346–347creating lookahead 340creating running 339getting unique values 340–345setting values 338–347types described 339

aggregate expressions 200, 201aggregate functions

adding to queries 192default values 339entering in crosstabs 586null values and 338value expressions 338

aggregate reports 347aggregate rows

creating 200retrieving with conditions 180setting conditions for 201–202, 204

aggregate valuestypes described 347

Alias attribute 646, 655, 656Alias Name dialog box 184aliases

component libraries 644connections 646, 657database tables 184synonyms vs. 188templates 645value expressions and 336

ALIGN attribute 664, 665Align command 105Align menu 105Aligned layout style 12

I n d e x 669

aligningcomponents 105–106text 661, 665

alternate names. See aliasesalternating background colors 356alternating page layouts 534analysis tools xxiAnalysisType property 388AnalyzeAsAutomatic constant 388AnalyzeAsDimension constant 388AnalyzeAsMeasure constant 388analyzing data xxiiAND conditions (queries) 196, 201application programming interfaces (APIs)

developing with xxiiapplication servers xixapplication window 74–78

closing toolbars and palettes 136context menus 78customizing 111moving toolbars and palettes 133–136opening 58overview 62reconfiguring component palettes 121–128

applicationsaccessing cross-platform 562accessing external 364creating for OLE objects 365customizing xxie.reporting solutions for xviii, xixsample xxiv

.apr filessaving configurations to 126

archive driver xxiiarchiving tools xxiiarea charts

creating 450, 480–482overview 437

arguments. See parametersASC keyword 272Asc keyword 296ascending sort order 296, 304, 306assigning

column names to reports 608values to controls 333–347variables to parameters 603, 606, 614

attachinglibraries to report designs 153–159to databases. See connections

attributesSee also propertiesassigning rich text 661defining HTML text 664XML tags and 641

Auto Joins command 184AutoHyperChart property 522autoinclude option 644automatically aligning components 102AutoSort option 177AutoSplitVertical property 413, 414, 415AutoValueControl constant 334Ave function 338, 586averages 338axes values

displaying gridlines for 453, 455specifying tick intervals for 455, 456

B–b command-line option 45BackgroundColor property

charts 458, 460crosstabs 589, 592frames 356, 554

backgroundsalternating colors for 356printing 554–555

BalanceFlows property 545BalloonHelp method 358BalloonHelp property 358, 594bar charts

adding legends 469creating 450, 468dual y-axis charts as 494–498examples for 470labeling 469overview 434–435setting properties for 468–470

BarGrouping property 469BarOrientation property 469.bas files. See source filesBASC keyword 273Basic. See Actuate Basic

670 D e v e l o p i n g A d v a n c e d e . R e p o r t s

BDESC keyword 273Before slot (Design Editor)

group sections 300placing dynamic text controls 406visual components in 87

bin directory 45binding controls to data 332–333bitmap image controls 363, 364bitmaps 360blank report designs 80Blank Report option 8, 80Blocked layout style 12blocked reports 268, 269BMP images 360BodyPage slot (Design Editor) 536Border property 350borders

removing 350rounding 350

bracket notationcommand-line options 45, 46value expressions 334, 335, 336

break reports. See grouped reportsbrowsers

program-specific 64, 68web environments. See web browsers

browsing 318Build and Run command 26, 43, 44Build command 43Build New Database Connection page 656Builder button 72, 108BuildFromRow method 444building reports

See also creating reports; designing reportsadding components 83–93at run time 383–386including component libraries 153–159overview 42–44process summarized 40–42read-only libraries and 162removing components 109–110with new designs 80–83

builds 44bullets 663, 666buttons

adding to component palettes 122toolbar 75, 76

BW login configurations 256By Filter sort option 252By Query sort option 252

Ccalculated columns

creating 191–193defined 348

calculated controlsexample for 342overview 335

calculated fields. See calculated columnsCalculateEndingValue method 507CalculateStartingValue method 506calculations

aggregate values and 347creating computed columns for 191decimal places and 130overview 347

candlestick chartscreating 450, 484–486formatting 486overview 438setting properties for 485

CanIncreaseHeight property 532, 583CanIncreaseWidth property 532, 583CanMoveLeft property 589CanMoveUp property 397, 400, 589CanReduceHeight property 397, 400CanSortDynamically method 177carriage returns 662case sensitivity

XML elements 641catalogs xixcategory axes

adding to charts 451default formats for 505defined 430displaying gridlines for 453displaying values 438, 482setting properties 473

category labels 430category titles 430CategoryExp property

area charts 480bar charts 469detail charts 477, 479

I n d e x 671

CategoryExp property (continued)pie charts 457, 460summary charts 475, 476

CategoryLabelExp propertyarea charts 480bar charts 469detail charts 477, 479pie charts 457, 460summary charts 475, 476

CategoryLinkExp property 522cells (crosstabs)

adding data 582changing formulas in 586, 587creating aggregate expressions in 582defined 576resizing 583setting cell properties for 594setting value properties for 595

Center command 106Center menu 106centering components 106centering text 661, 664Change Column command 218Change Column dialog box 215Change Column Used in Query dialog 217changes, tracking for report designs 42changing

ad hoc parameters in queries 251column names 214, 217, 218component names 108component properties 65data types 214, 216default component images 124formulas 586, 587information objects 229, 230, 233, 234, 235input parameters 246measurement units 129–132page layouts 534published components 162report contents 541report designs 12, 65server profiles 142sort order 304text-based queries 244

character codes 662, 665character formats 661, 664character sets 662, 665

character strings. See stringscharacters

setting overflow 351, 352chart classes 428Chart command 449chart components 449Chart2DArea property 450Chart2DBar property 450Chart2DPie property 450Chart3DArea property 450Chart3DBar property 450Chart3DPie property 450ChartBackgroundColor property 458, 460ChartBorderStyle property 460ChartCandleStick property 450ChartDayUnit constant 505ChartHLC property 450ChartHourUnit constant 505ChartLine property 450ChartMinuteUnit constant 506ChartMonthUnit constant 506ChartNumberUnit constant 506ChartOHLC property 450ChartQuarterUnit constant 506charts

adding 448–451attaching to data streams 443–445color options 460, 489creating unique series 445example of dual y-axis 490examples for bar 470examples for pie 462–467examples for time series charts 508, 517formatting axes values 451–456labeling 430, 452overview 428–430, 448parts described 429platform-specific requirements for 524positioning legends 475, 478, 481resizing 449resizing legend 451showing multiple series in 435specifying type 430, 449terminology defined 430with multiple time series 502, 510

ChartScatter property 450ChartTape property 450

672 D e v e l o p i n g A d v a n c e d e . R e p o r t s

ChartType propertydual y-axis charts 487pie charts 460

ChartWeekUnit constant 506ChartYearUnit constant 506Check Table command 216Choose Data Source page 652, 653Choose Database page 646, 654, 655, 656Choose Included Module dialog 161choosing

component libraries 155data sources 9, 17database tables 11, 18databases 5report layouts 12report type 8, 16specific database columns 190

class instances 52class libraries

See also Actuate Foundation Class Libraryadding components from 84, 101developing with 55displaying components in 64referencing components in 94, 101

Class page (Component Editor) 66Class Variable dialog box 605classes

deriving subclasses 53–55editing 65overview 47, 51, 55redefining 55, 123–125relationship to objects 52renaming 108saving new associations 126–128viewing project-specific 65

Clear Query button 244Client Integration Technology xxiClip constant 595Clipboard

See also Scratch Padcopying synchronization information

to 212ClipLeading constant 352, 353clipping. See truncatingClipTrailing constant 353, 354, 355close values, plotting 438, 486CloseValueExp property 486

closing component palettes 136clusters xxicode

See also source filesgenerating 51read-only libraries and 162viewing 43writing 70

COLOR attribute 665color options

backgrounds 554charts 460, 489

color palettes 363color tables 660, 661colors 363, 665Column Editor 229, 230, 233, 234column headings

adding to reports 300creating 337repeating 300

column layouts 12column names

adjusting length 182assigning to report parameters 608changing 214, 217, 218conditional expressions and 313referencing 335sorting on 296viewing 190

Column Only command 183Column Property dialog box 191Column Qualifiers command 182columnar reports 268, 269ColumnHeadingsBorder property 589columns

adding specific 19changing type 191creating calculated 191–193creating multi-columnar formats 542data type changed 215defining sort keys for 197–198displaying contents 335establishing unique values for 194getting information for all 243getting number of unique items 341, 342grouping common 293, 294, 303grouping data by 21

I n d e x 673

columns (continued)grouping on 578, 585multi-column page formats 545–546not found 215rearranging 198referencing in queries 218removing from queries 191, 198, 201, 202retrieving specific 190–191selecting multiple 190setting crosstab properties for 593sorting on 22, 294, 306viewing nonsynchronized 211viewing specific 68

Columns page (Query Editor)defining aggregate expressions 200deleting columns 191overview 67reordering columns 191selecting columns 190

command-line executables 45, 46comments xxx, 642, 660common fields 293communication devices 166communication protocols 380company names and logos 546, 553comparisons

data segments 432numeric values in charts 432, 434, 437related values 440, 441

compiling 42compiling code 42–43complex reports 368Component Drop dialog box 153Component Editor

declaring parameters 602, 603, 605deleting parameters 634displaying parameters 603overview 65–66renaming classes 108setting component properties 108setting fonts and 119

component librariesadding components from 84, 161, 327adding to configuration files 640, 644, 646advantages 47aliasing 644attaching to designs 115, 153–159

creating 149–150locating included 159overview 148referencing components in 98–99, 101removing from designs 159setting search paths for 137setting URLs for 156

Component Library option 8component names, dimmed 61component palettes 77–78

changing class associations 123–125closing 136customizing 121–128displaying 136docking 133, 135dragging components from 84floating 136inserting separators 122moving 133, 134overview 62, 74pinning 77reading from files 127saving class associations 126–128

Component Properties dialogoverview 107renaming components 108

component reference properties 85components

See also specificaccessing 148, 150adding 83–93

for data streams 172for database connections 167, 168manually 174multiple 84to frames 92to icons 89to layout pane 90–93to query data streams 173–174to report designs 61, 62, 77, 83, 160, 161to report sections 293, 298, 308, 313, 316to structure pane 88–90

aligning 105–106centering 106changing class names 108changing images 124copying 94, 95–96, 363

674 D e v e l o p i n g A d v a n c e d e . R e p o r t s

components (continued)creating vs. referencing 98customizing 55, 124, 148deleting references to 109deselecting 100drawing 92, 93editing 65, 110inserting in slots 85–88layering 106modifying 107, 110moving 94, 100–102optimizing searches for 377overview 47–50placing in Scratch Pad 104publishing 148, 150–153, 162referencing 62, 94, 98–99, 151removing 109–110renaming 108resizing 104reusing 94–99, 150selecting 77, 99–100setting properties 107–108

copy operations and 95subclassing 94, 96–98viewing report 64

computed columns. See calculated columnsComputed Field command 192ComputeMinMax method 474conditional expressions

creating 312entering QBE 205inserting in queries 248, 249

conditional query statementscomparing types 179creating 196–197, 204defining for aggregate rows 201–202, 204,

346setting at run time 196

conditional reportsbuilding 312, 313overview 291running 314

conditional section components 312conditional sections 311–315

adding 312overview 290, 356

placing components in 313setting conditions 312

Conditions page (Query Editor)declaring report parameters 606, 608deleting report parameters 635overview 67setting conditions 196

Config tag 650ConfigKey property 647, 648configuration files

adding comments 642and the report wizard 652creating 641–649loading 115nesting 640, 642, 644overview 115, 640referencing 641running sample 8sample 650sections described 642selecting connections in 18setting defaults in 81setting locations 641setting search paths 116, 138, 160setting up sample 6–7specifying with e.Report Designer 657specifying with e.Reporting Server 657specifying with iServer 657

ConfigurationFile folder 651configurations

SAP GUI clients 256connection components 166

adding 167, 168publishing 151setting properties 169, 171, 172subclassing 97

Connection registry setting 81Connection slot (Design Editor)

conditional sections 313group sections 300parallel sections 316sequential sections 308

Connection tag 645ConnectionOptions tag 648connections

aliasing 646, 657

I n d e x 675

connections (continued)available types 169configuring 640, 642creating new 656defined in libraries 654, 655, 656defining 167–172differences in database types 207displaying types 656multiple databases and 97overview 166, 167predefined data source 222reusing data source 223selecting database 10, 17setting at run time 647setting database 645–647setting options for 647sharing 293specifying default 81, 647, 655, 657specifying multiple 642, 647supported servers 167validating 207

ConnectionString property 171consistency checks 209, 216containers

See also framescopying components in 95, 96sections as 290

content management systems xixContent slot (Design Editor)

adding frames 330overview 87, 300, 308placing dynamic text controls 406

contents pagecreating 318, 320default values 318developing for grouped reports 318optimizing 318–321

context menus 78context paths 27context-sensitive help xxvii, xxviii, 357–358controls

adding 330–333for images 360–364

binding to data 332–333changing display values 348changing in copied frames 96customizing 123, 349–357

default fonts and 118dependency 347editing in place 349grouping related 326hiding 359hyperlinks in 322maintaining spacing among 400moving 101optimizing 363overview 40, 327–328placing in frames 396–399providing help with 358publishing 364reducing number of 328referencing 337, 363repositioning 399–404resizing 397, 399, 401, 402rounding corners 350setting display values 333–347user-defined values in 337

converting OLE controls to bitmaps 363, 364converting queries 252converting to new releases 46copying

components 94, 95–96, 363frames 95, 96synchronization information 212

Count function 339, 586Create New Data Source dialog 5Create New Report dialog 80, 143creating

ad hoc parameters 605, 606balloon help 358–359charts. See chartscomponent templates 98configuration files 641–649context-sensitive help 357–358crosstab reports 580dummy controls 568graphs. See graphshyperlinks

as URLs 387for web-based reports 386

images 363information objects 223, 228multi-columnar layouts 542, 545multi-page reports 413

676 D e v e l o p i n g A d v a n c e d e . R e p o r t s

creating (continued)ODS data sources 283queries. See queriesreports 7, 15, 143

at run time 383–386report-specific online help xxxserver profiles 27–29subreports 321text-based queries 69, 238

creating queriesselecting tables 183–188

criteria. See parameterscross tabulation. See crosstab reportscross-platform applications 562–564cross-platform reporting xxCrosstab Builder

creating crosstabs with 580entering expressions 586, 587grouping with 584overview 580sorting with 585

crosstab reportschanging properties 590, 594creating 580customizing 587, 588, 590, 592, 593, 594designing 578examples 269, 270grouping data in 578overview 575, 576, 596resizing 596running 584sorting data in 585

currency controlsSee also data controlsdisplaying overflow characters 351, 352formatting values 349overview 328

currency symbols 665current date and time 552current release xviicurrent working directory 160custom classes

defining 55, 123–125saving associations 126–128

custom components 55, 124, 148custom controls 123, 349–357

custom data sourcessorting on 176, 177

custom data streams 168, 173defining data rows for 175

Custom From Clause command 187Custom FROM Clause dialog box 187customer profiles xviiiCustomer Support xxivCustomize Button Layout command 122Customize Toolbar window 122customized font file

defining font information in 569customized font files

defining font information in 568customizing

applications xxicrosstab reports 587, 588, 590, 592, 593, 594e.Report Designer Professional 111, 112queries 222Query Editor 182report designs 51reports xxi, 553–555

Ddata

accessing xix, 166, 167across platforms 562from external applications 364

analyzing xxiias content 87binding controls to 332–333comparing values 432, 434, 437display options 129, 131displaying 327, 328, 428

from a single column 335from alternate sources 326from multiple columns 335in static controls 337

formatting 349formatting in charts 524formatting in controls 348grouping by fields 21grouping by interval 297–298grouping by tables 20grouping on columns 578grouping on rows 578

I n d e x 677

data (continued)grouping related values 293, 294, 303plotting relationships to whole 432, 437presorted 199required 600retrieving from databases 179retrieving with conditions 180, 196retrieving with joins 193retrieving with queries 177setting values at run time 196, 204, 337,

600showing range of values 438sorting 197–198

database utilities for 176for unique values 342in group sections 296, 304, 306–307with Component Editor 198, 199with sort filter 177with sorting property 177with text-based queries 251

sorting options for 176specifying default font for 118–120summarizing 200–201, 576values changing over time 440, 499–507

data controlsSee also controls; dataadding 330, 331–333assigning values 337defined 327removing outlines 350truncating single-line 351–354

data dictionary 205, 209data filters 167, 175data integrity xxdata object executables

creating 226publishing 27

data object instanceschanging 229creating 223generating 226overview 222previewing 27

data row components 172, 175Data Row Editor 229, 230data row objects 175

data rowsaggregating subsets 200, 201, 338, 340counting 339custom data streams and 175defined 166, 175filtering duplicate values 340, 342grouping on 578, 585relationship to controls 327relationship to frames 326, 327reordering 197setting crosstab properties for 592sorting on 22, 175, 304, 306

Data Sorting page 22data source components

adding to designs 173–174inserting manually 174overview 166, 172

Data Source Editor 252data sources

choosing 9, 17defining in libraries 653flat files as 168ODBC connections and 171predefined connections for 222reports 40, 166, 172, 175reusing connections for 223selecting predefined 652, 654selecting text-based query 239setting up manually 5sorting data in 177specifying default 81, 82

Data Sources page 651data streams

alternate sources 326charts and 443–445customizing 168, 173defined 166maintaining 291overview 165, 166, 172–173reusing 151sorting on 176

data typesadding to expressions 594changed 215changing 214, 216characteristics of 52mapping databases to 216

678 D e v e l o p i n g A d v a n c e d e . R e p o r t s

data types (continued)QBE expressions and 205, 211reassigning 191

Database Browseraccessing 66displaying Oracle synonyms 188overview 68selecting tables 183, 184

database connections. See connectionsdatabase example file 4Database Field command 331Database Login dialog box 11, 171, 182database schema

checking table consistency 216refreshing dictionary for 209synchronizing with queries 205updating 209, 213viewing 182

database servers. See serversdatabase sort utilities 176, 177databases

accessing 166, 167attaching to. See connectionschoosing 5, 654contents changing frequently 321contents remaining constant 635creating joins 194e.reporting solutions for xviii, xixlarge amounts of text in 390loading sample 225logging into 167, 171mapping to data types 216multiple style formats in 390obsolete tables in 215referencing tables in 185reporting vs. transaction 348retrieving data from 18, 177, 193selecting from predefined 652, 654selecting specific columns 190selecting tables 11, 183setting default connections to 81setting up as data sources 5sorting data 197–198, 251

for unique values 342on primary keys 194

supported types 167table consistency checks 209, 216

viewing contents 68, 182, 183DataFont property 234DataSource component 653

See also data sourcesDataSource property 171, 656DataType property 594DataTypeAutomatic constant 594DataTypeDateTime constant 594DataTypeNumber constant 594DataTypeText constant 594DataValue attribute 377date formats 349date stamps 552date/time controls 328, 612

See also data controlsdate/time functions 552DateExp property 486dates

adding to graphs 505adding to reports 612displaying current 336, 552sorting by interval 297

DB2 tablesconnecting to 167connection parameters for 169

Debugger toolbar 76debugging reports 41, 628decimal places

display options for 129setting 130

decimal points 129Default Action command 378default connections 81, 647, 655, 657default data sources 81, 82default fonts 120default operations 98default properties, restoring 108default sort order 296default values 339defaults 112DefaultSplitting constant 414DefinedIn attribute 646, 655Definition property 589deleting

borders 350columns from queries 191, 198, 201, 202component libraries from designs 159

I n d e x 679

deleting (continued)components 109–110directories from search paths 139, 140frames 330group sections from reports 304report parameters 633–635sort keys 307tables from queries 184

deployment xix, xxiiiderived classes 53DESC keyword 273Desc keyword 296descendant classes. See subclassesDESCENDANTS function 266descending sort order 198, 296, 304, 306Describe Query command 238, 242Description attribute 646, 655Description page (Component

Properties) 108deselecting components 100Design Editor 59–62

accessing 45, 110adding controls 330–333adding sections 292, 295, 308, 312, 316aligning components 105–106building query data sources 174centering components 106creating page layouts 534–539

background images 554headers and footers 547multi-column formats 545setting margins 544

customizing 112, 137, 143defining flow 543deselecting components 100drag-and-drop operations in 101editing components 110layering components 106overview 58placing components 83–93

multiple 84on icons 89

placing subpages 542rearranging components 99–106referencing components 98removing components 109–110resizing components 104

reusing components 94–99selecting components 99–100setting component properties 107–108specifying default fonts for 118starting 45subclassing components 96–98

Design Editor page 141Design Editor window

component palettes 47, 55, 62grids 102layout pane described 61opening 110overview 59resizing panes 59slots 85–88, 90

conditional sections 313group sections 299, 300page layouts 534, 548parallel sections 316sequential sections 308

structure pane described 60–61tools described 63–66

design filesbuilding 42, 223executing from the command line 45, 46generating information objects from 228,

229publishing 150, 151saving 141setting search paths for 138

Design Properties command 632Design Properties dialog 628design search path 138, 159Design Search Path page 138Design section (configurations) 642, 644Design tag 644design tools xx

display options for 137designing crosstabs 578designing e.Spreadsheet reports xxi, xxiiidesigning reports xx

See also Design Editorcomponent libraries and 159component reuse and 94, 150cross-platform guidelines 563custom classes and 123graphical tool for xxv

680 D e v e l o p i n g A d v a n c e d e . R e p o r t s

designing reports (continued)including component libraries 153layout options for 12previewing design 107process described 40–42programmatically 51referencing components and 62, 98removing components 110search strategies and 368sizing strategies 321, 635source files and 42structure pane and 61testing designs 564tips for restructuring large 321with charts 448with dynamic text controls 395, 396–399,

413with report wizards 3

design-time connection properties 648desktop 58destination URL syntax 378, 380detail charts

adding time series to 508bar charts as 468, 470defining time series for 500, 507dual y-axis charts as 490formatting axes values 452line or tape charts as 477overriding methods for 467pie charts as 456scatter charts as 482setting properties for 477

Detail command 330detail reports

contents pages and 318creating 303, 321examples for 637sorting data 22, 304, 306–307

Detail sample reportcontents page in 319on-demand reporting in 636

detailed line charts 444developing reports xxi, xxx, 51development languages xxidevelopment tools xxi, xxiiDHTML reports

displaying xix

generating 328printing 35

DHTML Viewer 27Dimension type 388dimmed components 61directories

removing from search paths 139, 140searching 137, 139setting new design 141

directory pathsimage searches 361, 362included libraries 159setting as search 137setting for configuration files 641verifying 208

discounts 336display formats. See formattingDisplay Gridlines command 102display options

data 129, 131design tools 137

display resolution 564displaying

column names 190component palettes 77, 136component properties 65components 64context menus 78current date 336data 327, 328, 428

from a single column 335from alternate sources 326from multiple columns 335in crosstabs 576in static controls 337

database tables 68, 182, 183Design Editor grids 102DHTML reports xixdynamic text controls 422hyperlinks 378images 327, 360MDX queries 279methods 70numbers 337online documentation xxviiprintable areas 543query statements 202

I n d e x 681

displaying (continued)report designs 107report files 64report parameters 600, 603, 612, 615reports xxiii, 14, 26, 41, 73, 562source code 43synchronization information 211, 213text 337, 393toolbars 136variables 63, 65

DisplayName propertyconnections 646, 654data sources 653

Distinct keyword 340, 341docking

component palettes 133, 135toolbars 133, 135

document filescreating 42, 383indexed searches and 377

documentationaccessing xxviioverview xxiiisyntax conventions for xxxitypographical conventions for xxx

.doi files. See data object instancesDoNotSplit constant 413dot notation 336downloadable fonts 562downloading

Reportlets 561SAP Java Connector libraries 256

.dox files. See data object executablesdrafts 554drag-and-drop operations 84, 94, 101drawing components 92, 93drawing controls 328, 553Drawing/Graphics palette 93drop shadows 350drop targets. See slotsdual y-axis charts

bar charts as 494–498creating 487–490identifying series for 487, 488limitations 490optional properties for 488overview 441–442

scatter charts as 490–494specifying line properties 490

DualYAxisOrigin property 488DualYDisplay property 487DualYLabelFormat property 488DualYLabelOrientation property 488DualYLabelStyle property 488DualYLineThickness property 490DualYMajorTickCount property 489DualYMajorTickStyle property 489DualYMax property 489DualYMin property 489DualYShowLine property 489DualYTickInterval property 456, 489DualYTitle property 489DualYTitleBackgroundColor property 489DualYTitleBorderStyle property 489DualYTitleOrientation property 489DualYValueExp property 486, 488dummy controls

creating 568hiding 568

duplicate values 340, 342duplicated controls 363duplicating component palettes 126dynamic page size 529, 532, 533dynamic report parameters 383–386dynamic text controls

adding 328, 395–396adjusting text formats for 407–413displaying 422generating content for 392–395HTML character encoding and 665orphan/widow control for 421overview 390–392placing in frames 405–407positioning in frames 396, 397, 399resizing 397, 399, 401, 402rich text formats for 660shrinking 400spanning multiple pages 413–421supported formats for 391truncated 392, 407

Ee.Analysis 388e.Analysis Option xxii

682 D e v e l o p i n g A d v a n c e d e . R e p o r t s

e.Business applications xixe.Report Designer xx

reconfiguring component palettes 123e.Report Designer Professional xxi

activating context menus 78changing display options for 137closing toolbars and palettes 136customizing 111, 112defining connections 168developing with xxvdrag-and-drop operations in 84, 94installing in nonstandard locations 208main window 74–78moving toolbars and palettes 133–136overview 57setting options for 112starting 45tools described 58

e.Report Engine xxiiie.Report Option xxiie.reporting solutions xvii, xixe.Spreadsheet Designer xxi, xxiie.Spreadsheet Engine xxiiie.Spreadsheet Option xxiie.Spreadsheet reports

designing xxi, xxiiigenerating xxii

Edit SQL command 252Edit String dialog box

setting defaults 81, 82, 83setting image search path 364

editingdesigns 65, 110information objects 229, 230, 233, 235text-based queries 243

edit-in-place 349editors 43electronic catalogs xixellipsis characters 351

displaying 353, 354Ellipsis constant 595Else slot (Design Editor) 313Embedded property 360, 361, 362embedding font information 568embedding OLE objects 364–366encoding

dynamic text controls 665

source code 117Encyclopedia volumes

accessing 117generating documents for xxilogging into 34management tool for 74managing server profiles 27, 142publishing executables to 27

End User Desktop xxentering expressions. See Expression Builderenterprise reporting xviii, xixequi-joins 194, 195Erd_sample_library.rol 652, 654erdpro command 45<ERROR> in SQL statements 205evaluating SQL statements 203example configuration file 650Example folder xxivexample reports. See sampleExcel spreadsheets

developing for xxi, xxiiigenerating xxiilinking with OLE controls 365

executable filescreating 42, 226default search paths for 44embedding font information in 568getting font information from 566publishing 27, 31rebuilding 44, 45, 46running 43, 45

executing reportsdefault actions for 43from the command line 45–47page layouts and 528procedure for 26report sections and 301, 310, 314, 317saving parameters 628with specific parameters 632

exploding pie slicescreating 460examples 465

Expression Buildercreating expressions 72displaying external functions in 148overview 59, 71–73starting 72

I n d e x 683

expressionsSee also Expression Builderadding data types 594adding literals 337adding query conditions with 205changing 586, 587charts and 485creating conditional 248, 249, 312creating value 71, 72, 333–347displaying results 348null values in 335producing text values 337QBE syntax for 204referencing column names 335referencing controls in 337referencing functions 335, 336referencing report parameters 337referencing variables 335returning distinct values 340–345returning summary values 338–347summarizing values 200, 201taking multiple values 334

external applications xxaccessing from OLE controls 364

external functionsdisplaying in Expression Builder 148

F–f filename.log option 45F1 key xxviiiFACE attribute 665factory processes 445Factory servers 321FetchLimit property 286Field List

See also Design Editoraccessing 332overview 63, 84placing controls with 330, 331, 332

fields. See columnsfile argument 380file-based databases 207, 208files

accessing flat 168creating report 42, 383displaying project 64generating report 41, 42–43

managing 34naming 25running executable 43running from the command line 45–47saving design 141setting recently opened 114setting search paths for 137setting URLs for report 156verifying paths 208

FillPattern constant 595FILTER function 274filters 167, 175finding data. See searchingfinding images 361–363finding included libraries 159First function 338fixed line breaks 395, 408fixed values 600fixed-width text 664flat files 168floating component palettes 136floating toolbars 133, 136floating-point controls 328

See also numeric controlsflow 542–546

adding to layouts 543–544background patterns and 555balancing 545, 546defined 528defining

for multi-column layouts 545–546for specific pages 534, 536, 537, 538, 539for subreports 317

overview 528, 541resizing 544

flow componentsadding 534, 535, 536, 543, 545defined 542placing on subpages 541

FlowName property 317font attributes 595font files

copying to servers 572defining font information in 567, 568, 569registering 573specifying clients for 572

Font property 595

684 D e v e l o p i n g A d v a n c e d e . R e p o r t s

font tables 660, 661fonts

availability for Windows servers 562changing information object 234, 235embedding 568getting information for 566, 567overview 565providing information for 565resetting defaults 120scalable vs. raster 563searching for 567setting dynamically 563setting properties for 565setting size 662, 665specifying 665specifying default 118–120substituting 565text attributes for 661, 664unavailable 393

Fonts page 118Footer command 548footers

adding to reports 87, 546–553associating with data groups 293, 300displaying 304placing dynamic text controls in 407

Forecast sample reportcontents page in 320subreports in 321

Forecast.rod 310foreground colors 665foreign keys 193, 194Format property 595formats

adjusting text 407–413HTML tags for 664rich text control words for 660supported 391

formattingchart axes values 451–456data in controls 348, 349dynamic text controls 391, 396page numbers 550

formatting toolbardescribed 76fonts names in 119formatting data with 348

setting properties from 107Formula One product suite xxiiiformulas

See also expressionschanging 586, 587

frame components 328frames

adding 326, 327, 328–330controlling multi-page spread for 413–421copying 95, 96creating running headers with 548, 549customizing 349–357extracting as Reportlets 559group sections and 303, 304, 305hiding 359keeping contents on page 417manipulating controls in 396–399moving 349, 540nesting 328, 349, 405numbering report pages with 551overview 40, 326, 528placing

components in 92controls in 331–333, 405, 542dynamic text controls in 405–407headers and footers in 547

positioning controls in 396, 399–404relationship to data rows 326, 327removing 330resizing 104, 349, 405resizing controls 397, 399, 401, 402rounding corners 350setting auto-split options for 413, 414, 415setting no-split options for 417setting page breaks 350setting properties 349

FROM clause (SQL) 179, 183customizing 186

Full Name command 182functions

See also methodsassigning data streams to charts 444converting to C++ 347date/time 552methods as 70referencing 335, 336

fundamental data types. See data types

I n d e x 685

GGeneral option 6General page 114generating

code 42–43, 51on demand 635report files 41, 42–43reports xxi, 176, 328, 347

GetReportData directive 560GIF images 360global parameters

adding 600, 602deleting 633referencing 611

global scope 601, 604global search path

designs and 138included libraries and 160removing directories from 140setting 139

Global Search Path page 139Globals Browser

dragging components from 84overview 64reconfiguring 64

graphical tools xxvgraphics

as background patterns 554–555creating 363, 553displaying in reports 327publishing 363, 364

graphics applications 364graphics controls. See image controlsgraphics tools 363graphs

assigning values 334grayed components 61grids

charts 453, 455, 489layout pane 102

GROUP BY clause (SQL) 179, 200, 348compared to Order By clause 180

Group By keyword 340Group By page (Query Editor)

displaying 68removing columns 201summarizing data 200

group fields. See calculated controlsGroup Footers command 548Group Headers command 548group keys

displaying 306getting relevant data for 306specifying 296, 302, 303

group section components 295group sections

adding to reports 295, 303creating 302–306getting distinct values for 342grouping data by interval 297–298hyperlinks and 322nesting 295, 297overview 290, 293–302page layouts and 546, 548placing components in 298–301queries and 197removing 304setting group keys 296setting grouping intervals for 305sorting data 199, 296–297, 304, 306–307

Group Sorting dialog 585group/totals reports. See grouped reportsgrouped reports

adding groups 303adding headers and footers 304adding summary data 21arranging data 20, 21building 293, 295, 298changing sort order 304creating 15–23, 302generating contents page for 318laying out 23overview 290, 294removing groups 304running 26saving designs for 24setting up data groups 305sorting data 22

grouping controls 326grouping data

by fields 21by tables 20in crosstabs 578on common fields 293, 294, 303

686 D e v e l o p i n g A d v a n c e d e . R e p o r t s

grouping interval 305Grouping Options dialog

displaying 304setting grouping intervals 306setting grouping options 304

GroupInterval property 297GroupOn property 297groups 20

Hhandles (sizing) 105HAVING clause (SQL) 179, 201

compared to WHERE clause 180Having page (Query Editor) 68, 201, 202Header command 548headers

adding 87, 546–553associating with data groups 293, 300displaying 304placing dynamic text controls in 406

HeadingHeight property 592HeadingWidth property 592heap 287Height property 397, 592help

accessing online xxvii–xxxbuilding context-sensitive 357–358creating balloon help text for 358–359including for searches 368, 378providing online 357–359viewing tool tip 75

help buttons 357Help command 357Help menu xxviiihelp topics xxviiiHelpText property 357hiding

frames and controls 359high values, plotting 438, 486high-low-close charts

attaching to data streams 444creating 450, 484–486formatting 486overview 438setting properties for 485

HighValueExp property 486hints 75

HLC charts. See high-low-close chartsHLCBarStyle property 486home page (Actuate) xxiiiHorizontal constant 595HorizontalPosition property 589host strings 170HTML formats 392HTML forms

character encoding in 665setting up 663

HTML reportscreating hyperlinks for 378, 386generating from Reportlets 559, 561image types supported 360

HTML tagsspecial characters in 665supported 663

http argument 380HyperChartDisabled property 522HyperChartEnabled property 522hypercharts

creating 521setting link expression 523

hyperlink expressions 379hyperlinks

activating 378adding to web-based reports 386creating temporary reports with 384displaying first page only 381enabling in Reportlets 561multiple search criteria and 382search expressions 381searching with 367subreports and 321, 323URLs as 387

IIBM DB2 tables

connecting to 167connection parameters for 169

iconsDesign Editor window 47, 55, 62sections as 290

identifying toolbar buttons 75IfExp property 313IFRAME tag 560

I n d e x 687

image controlsadding to reports 360–364, 546for special effects 553interaction with data rows 328overview 327

ImageDesignTime setting 360, 361ImageFactoryTime setting 360, 362images

as background patterns 554–555as company names and logos 553changing default component 124creating 363finding 361–363linking to OLE 366publishing 364setting search paths for 137storing 363types supported 360

ImageViewTime setting 360, 362Include Library dialog 155Include Library option 156Include section (configurations) 642, 644Include tag 644included files 137indenting text 661index (online documentation) xxviiindexes (search) 377–378Information Delivery API xxiiinformation delivery solutions xvii, xixInformation Object wizard

starting 223information object wizard

overview 223information objects xxi

adding columns 234creating 223, 228defined 222editing 229, 230, 233, 235examples 223generating executables for 226, 227

InformationObject constant 228Informix tables

connecting to 167connection parameters for 169

inheritance 53–55copied components and 95subclassing and 96, 148

inherited properties 107inner joins 194, 195InnerBorder property 592input parameters

See also stored procedureschanging 246

Insert menu 84, 330installation

SAP Java Connector libraries 256installing online documentation xxviiinstantiation 52, 322integer controls 328, 337

See also numeric controlsintegrated content xxinvalid table entries 214IsDefault attribute 647, 655, 657iServer

managing multiple xxioverview xviiirunning multiple xxi

iServer Systemoverview xxi

IsNull() method 335Itemreport.rod 14

JJava objects xxiiiJava programs

developing for xxiiiJava Virtual Machines

setting maximum heap size for 287JavaScript functions 386join operator icon 194join operators 195joins

changing type 194creating 19, 193–195establishing for Progress tables 193overview 20removing 195types supported 194

JPEG images 360justifying text 408JVM heap size 287

688 D e v e l o p i n g A d v a n c e d e . R e p o r t s

Kkey fields. See sort key columnsKey property 296keyboard selection 100keys. See sort keys

Llabel controls

as graphical element 553changing in copied frames 96displaying values 337overview 328

LabelFont property 234labels

charts 430, 452default formats for x-axis 505frames 337setting default font for 118–120

landscape mode 530, 533large reports

reducing size 635restructuring 321

Last function 339layering components 106Layers command 106Layers menu 106layout painter. See Design Editorlayout pane (Design Editor)

adding frames 92aligning components 102layering components 106moving components 101overview 61placing components 90–93removing components 110resizing components 105selecting components 100

layout styles 12layouts. See page layoutsleading spaces 249, 352, 353Left slot (Design Editor) 539left/right page list 534, 546LeftPage components 546LegendBackgroundColor property

area charts 481detail charts 478

pie charts 457summary charts 475

LegendBorderStyle propertyarea charts 481detail charts 478pie charts 457summary charts 475

LegendColorText propertyarea charts 481detail charts 478pie charts 457summary charts 475

LegendMinFontSize propertypie charts 458, 476, 478, 481

LegendPosition propertyarea charts 481detail charts 478pie charts 458summary charts 476

legendsadding to charts 430displaying items in 451formatting 460positioning in charts 475, 478, 481setting properties for 472

letterheads 553level break listings. See grouped reportsLibconfig.xml 650libraries

See also Actuate Foundation Class Libraryadding components from 84, 101adding to configuration files 640, 644, 646adding to report designs 115advantages for component 47aliasing 644attaching to designs 153–159creating 149–150defining data sources in 653designing with xxdisplaying components in 64including components from 161installing SAP Java Connector 256locating included 159overview 148program-specific classes 55referencing components in 94, 98–99, 101removing from designs 159

I n d e x 689

libraries (continued)saving as read-only 163setting as read-only 162setting search paths for 137setting URLs for 156

Library Browserdragging components from 84, 161opening 161overview 64published components in 151, 152

Library Browser command 161Library Organizer

adding libraries from 154creating component libraries with 149locating libraries for 155opening 149removing files 159

Library Organizer command 154Library tag 644line breaks

adding manually 349dynamic text controls and 408HTML tag for 664RTF character for 662running dynamic text controls and 393unpredictable results and 394

line chartsadding legends 475, 478as dual y-axis charts 442attaching to data streams 444creating 450, 474–479dual y-axis charts and 490labeling 475, 477overview 434, 435

line heights 394, 409line spacing 409, 410line styles and patterns 489linefeed character 662LineSpacing property 409LineStyle property

charts 486dual y-axes charts 490line charts 479pie charts 460scatter charts 484summary charts 476

LineStylesList propertydetail charts 479pie charts 460scatter charts 484summary charts 476

LineThickness propertycharts 476, 479, 486pie charts 460scatter charts 484

LineWidthPadding property 408link fields. See sort keysLinkExp property 522

calling JavaScript functions with 386dynamic parameter syntax for 383hyperlink expressions for 379, 385overview 378

linking related tables 193, 194linking to OLE objects 364–366links

See also joins; hyperlinkssubreports and 321, 323

links (online documentation) xxviiListing Report option 8, 17Listing Report wizard

adding totals 21overview 15saving designs 24selecting data sources for 17–18selecting database tables 18selecting layout style 23selecting report type 16setting sort order 22setting up report structure 20, 21starting 16

listing reportsadding summary data 21arranging data 20, 21creating 15–23laying out 23running 26saving designs for 24sorting data 22

lists 664literal values 337local libraries 148

690 D e v e l o p i n g A d v a n c e d e . R e p o r t s

local parametersadding 600, 602, 605deleting 634referencing 611

local scope 600, 604locales

e.reporting solutions for multiple xviiilocating data. See searchinglocating images 361–363locating included libraries 159log files 45logging into databases 167, 171logging into Encyclopedia volumes 34login information 167logos

adding to reports 546, 553lookahead aggregates

compared with running 339overview 347replacing 347–348specifying 340

low values, plotting 438, 486LowValueExp property 486LRX (Live Report Extension) xxiii

Mmain toolbar 75main window. See application windowManagement Console xxi

managing reports with 34overview 74setting URLs for 117

managing clusters xxiManuals directory xxviiMargin property 418margins

flow components and 542setting dynamic text 418–421setting page layout 531, 533, 544specifying default 82, 83

master font filescopying to servers 572defining font information in 567, 569registering 573specifying clients for 572

master reports 321

matrix reports. See crosstab reportsMax function 338, 586maximum values 338MaximumHeight property 401MDX queries

clearing 280creating 260, 263displaying 279filtering with 274, 275generating order entries 271, 272sorting with 273specifying axes for 266verifying 280

Measure type 388measurement units

customizing 129–130setting suffixes for 131–132specifying 531

MEMBERS operator 266Memory Data Sorter filter 177menu bar 58menus 78Method Editor 58, 70methods

assigning data streams to charts 444changing 65designing with 41displaying 65, 70inheritance and 53overriding 54, 71overview 51referencing 336

Methods page (Component Editor) 66Microsoft Access 208Microsoft SQL databases 167, 176

connection parameters for 170migrating to new releases 46Min function 338, 586minimum values 338MinimumHeight property 400modifying. See changingmodules 61monitor resolution 564monospaced fonts 563monospaced text 664mouse cursor (changing shape) 94Move Forward command 106

I n d e x 691

Move to Front command 106moving

component palettes 133, 134components 94, 100–102frames 349, 540toolbars 133, 134

moving through reports 321Multi-Application Option xxiimulti-column page layouts 542, 545–546Multidimensional Expressions. See MDX

queriesMultiline constant 595multiline controls 563

truncating text in 356MultiLine property 349multilingual reporting xviiimulti-page reports 413multiple components

adding 84moving 101publishing 151selecting 100

multiple connections 642, 647Multisettimeseries.rod 491multi-table queries 19, 183, 193–195

Nnaming parameters 604navigating large reports 321navigation tools 318Navigator

defining universal hyperlinks for 386enabling 117toolbar 76

Navigator command 117negative values 432nested frames 349nested group sections

creating contents page for 319nested reports 291nesting configurations 640, 642, 644nesting frames 328, 405new design directory

setting 141NewConnection method 98newlines 349, 662, 664

NoHeaderOnFirst constant 367non file-based databases 207non-breaking hyphens 663non-breaking spaces 662, 666non-TrueType fonts 565NoSplitBottom property 417NoSplitTop property 417not found column entries 215not found table entry 214NotSearchable constant 366, 378Now function 552Null keyword 335null symbol 662, 665null values

aggregate functions 338testing for 335, 346value expressions 335

numbering report pages 550–552alternating layouts for 546in page footers 87with numeric controls 337with value expressions 336

numeric controlsSee also data controlsassigning values 337creating page numbers with 550, 551overview 328

N-up reports. See multi-column page layouts

Oobject templates 51object-oriented programming 51–56objects

hyperlinks and instantiating 322overview 52providing help with 357, 358referencing 336relationship to classes 51, 52

obsolete tables 215ObtainSelectStatement method 172, 186ODBC Data Source Administrator dialog 5ODBC databases

connecting to 167, 648, 656connection parameters for 170, 171

ODBC DataSource registry setting 81ODBC Microsoft Access Setup dialog 5

692 D e v e l o p i n g A d v a n c e d e . R e p o r t s

ODS data source components 283ODS data sources

creating 283fetching data for 286

ODS objects 280OHLC charts. See open-high-low-close chartsOLE applications 365OLE controls 364–366

converting to bitmap images 363, 364OLE objects 366on demand reporting 635one-pass aggregates. See running aggregatesonline documentation

accessing xxviioverview xxiiisyntax conventions for xxxitypographical conventions for xxx

online helpaccessing xxvii–xxxproviding 357–359

online reports. See reportsopen server technology xxopen-high-low-close charts

creating 450, 484–486formatting 486overview 438setting properties for 485

openingapplication window 58configuration files 115Design Editor window 45, 110Expression Builder 72Library Browser 161Library Organizer 149Query Editor window 182Registry Editor window 81reports 45, 114sample template 8SAP BW BEx Data Source Builder 264Scratch Pad 103Textual Query Editor 69, 240

opening values, plotting 438, 486OpenValueExp property 486Operational Data Store (ODS) 280operators 195optimizing queries 203options 112

iServer System xxiiOptions dialog box

changing class associations 123changing server profiles 142changing tool display 137choosing configuration files 6, 112, 115enabling grids from 102enabling Navigator from 117overview 112refreshing data dictionary 209removing component libraries 159restoring class associations 125saving palette representations 126saving palettes 126setting default fonts 118setting Management Console URLs 117setting measurement units 129, 131setting search paths 141setting source encoding in 117summarizing data 200summarizing with conditions 201

OR conditions (queries) 196, 201Oracle tables

connecting to 167connection parameters for 170querying 187–188

ORDER BY clause (SQL) 177, 179, 197compared to Group By clause 180compared to OrderBy property 198

Order By page (Query Editor)deleting columns 198overview 67selecting columns 198

ORDER function 271, 272OrderBy property 198, 199ordered lists 664Ordertotals.rod 25orientation (page layouts)

printing and 530, 533right to left 528setting 531, 533

orphan control 421outer joins 194, 195OuterBorder property 589, 592Outline Components option 543outlines around frames

removing 350

I n d e x 693

outputadjusting padding 411adjusting space between paragraphs 410adjusting vertical space 408displaying 393e.reporting solutions for xxjustifying 408optimizing 393, 394, 407printing 562troubleshooting common problems 422

Overall keyword 340overflow characters 351, 352overlapping components 106overlapping text 407overriding methods 54, 71__overwrite keyword 383

Ppadding 393, 408, 411page breaks 305, 350, 537, 549, 551page components

adding 528, 535, 536, 539inserting flow components 543, 545inserting label controls 553types described 529

page headers and footersadding 87, 546–553associating with data groups 293, 300displaying 304placing dynamic text controls in 406, 407searching 367

page layoutsadding headers and footers. See page

headers and footersalternating 534changing 534customizing 553–555defining printable areas 542–546designing 41, 527displaying current date only 552dynamic page size 529listing reports 23multi-column formats 542, 545–546numbering pages 87, 546, 550–552

with value expressions 336orientation 530, 531, 533

orphan/widow control for 421page styles 534, 536, 537, 538, 539

changing 541placing searchable controls in 368predefined 529running reports and 528setting default size 82, 83setting margins 542, 544setting up page sequences 534–539standardized 534subpages and 541–542temporarily changing contents 541title pages 536, 537viewing printable areas 543

Page Level Security Option xxiipage list components

adding 534–539attaching page components to 535types described 534

Page Margins registry setting 82Page Number command 550page numbers

adding 546, 550–552components for 87defining in value expressions 336numeric controls for 337

page orientationdescribed 530printing and 533right to left 528specifying 531, 533

Page Setup command 533Page Setup dialog box 531, 532page size

dynamic 529, 532setting default 82, 83, 533

Page Size registry setting 82PageBreakAfter property 350, 537, 549, 551PageBreakBefore property 350PageDecorationFont property 234PageFooter component 87PageFooter slot (Design Editor)

adding components 549group sections 300overview 87, 546, 548placing dynamic text controls 407

PageHeader component 87

694 D e v e l o p i n g A d v a n c e d e . R e p o r t s

PageHeader slot (Design Editor)adding components 549group sections 300overview 87, 546, 548placing dynamic text controls 406

page-level security xxiiPageList slot (Design Editor)

adding components 534, 536, 538PageNumberType property 550pages

See also page layoutsadding to page lists 534overview 528self-adjusting 541

Pages palette 550Paintshop Pro files 365palettes

See also component palettesaccessing program-specific 77application window 58image controls and color 363

paper size 531, 532paragraph break character 662paragraph formatting 661, 664paragraphs 410, 421parallel reports

building 292, 316running 317

parallel section components 316parallel sections 290, 315–317

adding 316, 541assigning flows to 317placing components in 316searching 369

Parameter Editor 609, 633accessing 602

Parameter Properties dialog boxchanging ad hoc parameters 251changing static parameters 248opening 607, 614viewing system parameters 600

parameter values filescreating 44, 628naming 630saving parameter settings for 628–632

parameterized queries. See stored procedures

parametersSee also specific typesadding to URLs 378aliasing 600assigning display names 600changing 614column names as 608defining 603–605defining static 608deleting 633–635displaying values 612entering stored procedure 69example for generating subreports 635naming 604overview 44, 600property values and 603, 634referencing 601, 611–612

in value expressions 337saving 628–632scope 600, 604setting at run time 196, 204, 632setting dynamically 383–386setting for database connections 169, 171,

172setting options for run time 632types described 600, 605viewing 603, 612, 615

Parameters command 609, 614passwords

defining for connections 169, 171obtaining customer xxiiisetting as parameters 603

pathsimage searches 361, 362included libraries 159relative names and 116setting for configuration files 641setting search 137verifying for file-based databases 208

patterns (as backgrounds) 554–555PCX images 360PDF files 365percentages 334, 340, 347, 432performance

large reports 635measuring 203

PerRowControl constant 334

I n d e x 695

pie charts 432–433creating 450, 456examples 462–467exploding slices 460, 465setting properties for 456–460

Pin checkbox (Method Editor) 71pinning component palettes 77, 133, 135Plain text formats 392point count (charts) 444PointLabelFont property 460PointLabelMinFontSize property

pie charts 459PointLabelOrientation property 460PointLabelStyle property 459, 460, 464, 467PointLabelVariableFontSize property

pie charts 459PointLinkExp property 522PointsArePercent property 460portrait mode 530, 533PostScript printers 564prebuilt sections 292predefined connections 222predefined data sources 652, 654presorted data 199Presorted option 177, 252previewing

report designs 12, 107reports 27, 29

primary keys 193, 194Print command 35printers

UNIX platforms 564Window environments 562

printing Reportlets 561printing reports 35

across platforms 562, 563–564alternating page numbers 546backgrounds 554hiding frames and controls 359page orientation options 530with alternating background colors 356with multiple columns 542, 545–546with parallel sections 317with running headers 548with sequential sections 309

printing subreports 317procedures 41, 70

See also methods

product suite xxproduct updates xxiiiprofile names 27profiles

changing 142managing 142setting up server 27–29testing 29

programming languages xxi, 51programming tools xxi, xxiiProgress databases xxii

as data source 167connecting to 183connection parameters for 170, 172establishing joins for 193

Progress Option xxiiProject Browser

dragging components from 84overview 64reconfiguring 64

projects 40Prompt for Parameters option 632, 633properties

changing component 65changing crosstab 590, 594changing database table 185, 214changing textual query 245chart type listed 450copy operations and 95database connections 647, 648deleting parameters with component 634restoring defaults 108setting 41setting bar charts 468–470setting candlestick chart 485setting component 107–108

copy operations and 95setting database connection 169, 171, 172setting database connections 642setting dual y-axis charts 488setting font 565setting for table of contents 318setting frame 349setting high-low-close chart 485setting open-high-low-close chart 485setting pie charts 456–460setting query 247, 250setting scatter chart 483

696 D e v e l o p i n g A d v a n c e d e . R e p o r t s

properties (continued)setting summary chart 471setting time series chart 500, 502, 513setting time series summary charts 514setting with report parameters 603subclassing and 97viewing current 65visually represented 85

Properties page (Component Editor)defining report parameters 108overview 66

Property elementdescribed 647providing default values with 656

Property Parameter Info dialog box 604property sheets. See Properties pagePublish and Preview Options dialog 29, 31Publish Class dialog 364Publish command 364Publish to Server command 31published components

adding to libraries 161changing 162

publishingcomponents 148, 150–153controls 364report object executables 27, 31

pushpin button 77

QQBE expressions 204queries

See also Query Editoradding conditions 205building data sources for 174changing ad hoc parameters in 251changing column names 214, 217, 218changing data types 214, 216changing input parameters 246changing tables properties for 185, 214converting 252copying synchronization information 212creating 181

for data groups 180for multiple databases 185for multi-table joins 193–195

for summary values 200–201with conditions 179, 196–197, 201, 204with QBE syntax 204

creating charts with 463, 465, 471creating text-based 69, 238, 241, 242customizing 222data filters vs. 175data source connections and 167defining ad hoc parameters for 248–251defining MDX 260, 263, 266defining sort keys 197–198deleting columns 191, 198, 201, 202displaying statements 202displaying synchronization

information 211, 213editing text-based 243evaluating statements 203examples 637generating dual y-axis values 491generating time series with 508, 511, 517optimizing 203optional procedures 181outdated 206overview 177–181removing column references 218removing multi-table joins 195removing tables 184reordering columns 198replacing lookahead aggregates with 348required procedures 181retrieving data with 166returning computed columns 191–193running ad hoc xxiirunning text-based 69selecting data for 18selecting specific columns 190–191selecting tables 19, 68, 183–184, 241

multiple copies 183setting conditions at run time 196sorting with 251synchronizing 205–219verifying database connections 207verifying statements 206

Query by Example. See QBE expressionsquery data source components

adding 173–174group sections and 296

I n d e x 697

query data streamsadding to designs 257building 173–174overview 165, 166, 173publishing and 151sorting on 176

Query Editorchanging data types 216converting queries 252creating charts 443creating computed columns 191–193creating joins 193–195creating queries 179, 181customizing 182defining report parameters 602, 605, 606,

608deleting tables 184displaying column names 182, 190overview 58, 66–68, 203refreshing data dictionary 209removing columns 191, 198, 201, 202removing report parameters 635removing tables 184selecting columns 190–191selecting tables 183–188setting conditions 201sorting data 197–198starting 182summarizing data 200–201synchronizing queries 210viewing Oracle table synonyms 188viewing query statements 202

Query Editor windowopening 182resizing 67toolbar 76tools described 68, 69

Query Option xxiiquery statements. See queries; Query Editorquery tools 222Quick Report option 8Quick Report wizard

overview 7previewing designs 12selecting data source for 9selecting database tables 11selecting report layouts 12

selecting report type 8starting 8

Quick Reportscreating 7–11layout options for 12previewing designs for 13selecting tables for 11

Quikdata sample database 4, 225Quikdata.mdb 4

R–r command-line option 46range of values 438Range property 502, 515RangeUnit property 503, 515raster fonts 563Read from a File option 632, 633read-only libraries 162ReadOnlyQuery property 172Recently used files list 114reconfiguring component palettes 121–128records

See also data rowsreordering 197sorting 22, 175

rectangle controls 328redefining classes 123–125reducing

number of controls 328report size 635

referencing components 98–99overview 62, 94publishing and 151

referencing configuration files 641referencing controls 337referencing duplicated controls 363referencing objects 336referencing report parameters 601, 611–612

in value expressions 337referencing tables 185referencing variables 335Refresh button 116Refresh Data command 43refreshing data 43refreshing data dictionary 209regedit command 81regedit.exe 364

698 D e v e l o p i n g A d v a n c e d e . R e p o r t s

regions. See framesregistering font files 573Registry Editor window

setting defaults 81, 82, 83storing default connection type in 657

related reports 290related values 440, 441relational databases. See databasesrelationships xxiirelative font sizes 665relative paths

configuration files 116, 644graphics files 361included files 137, 159

relative URLs 561release notes xxiiiremoving. See deletingrenaming

classes 108components 108tables 184, 185, 217

replacing lookahead aggregates 347–348report components. See componentsreport design files. See design filesreport designs

adding components 83, 83–93adding dynamic text controls 395, 396–

399, 413changing 12, 65creating 51, 80–83cross-platform guidelines 563custom classes and 123customizing 51hyperlinks and 322layout options for 12optimizing 62, 293overview 40–42previewing 107rearranging components 99–106referencing components and 98removing component libraries from 159removing components 109–110reusing components 94saving 24structuring 61testing 564tracking changes to 42

with charts 448report documents. See document filesReport Encyclopedia. See Encyclopedia

volumesreport examples xxivreport executables. See report object

executablesreport files

building 42creating 383displaying project-specific 64generating 41, 42–43managing 34naming 25running 43

from the command line 45–47setting recently opened 114setting search paths for 137setting URLs for 156

report object design files. See design filesreport object designs 42report object executables

See also executable filescreating 42getting font information from 566locating 44publishing 27, 31rebuilding 44, 45, 46running 43

report object instances 27See also document files

Report Page Footer command 548Report Page Header command 548report painter. See Design Editorreport parameters. See parametersreport section components 292, 320report sections

adding 292defined 290extracting as Reportlets 560hyperlinks and 322multiple 291overview 291–293page layouts and 546, 548placing components in 293placing frames in 326sharing connections 293

I n d e x 699

Report Server API xxiiReport Server Security Extension xxiireport server. See iServerReport Settings dialog box 633report tools 58

See also specific toolsReport Totals dialog box 21ReportCast xxireporting database 348Reporting Engines suite xxreporting solutions xvii, xixReportlets 559–562

embedding in web pages 560, 561restrictions 562

ReportQuery technology xxreports

See also specific typesaccessing sample 15adding background images 554–555adding date/time stamps 552adding title pages 536, 537attaching component libraries to 153–159building 42–44changing contents 541creating 7, 15, 143creating at run time 383–386creating multi-page 413customizing xxi, 553–555debugging 628designing xxdesigning. See report designsdeveloping xxi, xxx, 51displaying xxiii, 73extracting portions of 559, 561generating xxigenerating on demand 635generating specific portions 635indexed searches and size 377laying out 12, 23migrating to new releases 46minimizing controls in 328nesting 291numbering pages 87, 336, 337, 546, 550–

552opening 114

from the command line 45overview 166

previewing 27, 29printing 35providing contents for 87providing online help for xxxreducing number of controls in 328reducing size 635restructuring large 321running 26

with specific parameters 632selecting type 8, 16setting default size 82, 83setting values at run time 196, 204, 337,

600temporary 383, 384testing 27–33, 42types described 291

Reports slot (Design Editor) 316ReportType property 228Requester API xxi, 600Requester dialog box

configuring parameters for 607displaying fields in 600displaying parameters in 607displaying values in 612running reports from 26

Requester web pageconfiguring parameters for 607displaying fields in 600displaying parameters in 607setting parameters at run time in 605

required values 600resizing

charts 449components 104controls 397, 399, 401, 402crosstab cells 583crosstabs 596frames 104, 349, 405text controls 392window panes 59, 67

resizing handles 544resolution 564restoring defaults 108restructuring large reports 321result column properties 245result sets 193

retrieving 238

700 D e v e l o p i n g A d v a n c e d e . R e p o r t s

retrieving datafrom databases 177, 179with conditions 180, 196with joins 193

reusing components 94–99, 150reusing data streams 151RGB values 660, 665rich text formats 392, 660Right slot (Design Editor) 539right to left layout orientation

designing reports with 528RightPage components 546.rod files. See design files.roi files. See document files.rol files. See librariesrounded borders 350rounding 351, 503Rounding property 351RoundTo property 503, 505, 515routines 70.rov files. See parameter values filesRowHeadingsBorder property 589rows

See also data rowsgrouping on 578, 585reordering 197setting crosstab properties for 592sorting on 22, 175

.rox files. See executable files; report object executables

RSSE. See Report Server Security ExtensionRTF formats 392, 660rubberband selection 77, 100Run dialog box 81, 364

setting defaults in 81, 82, 83Run time section (configurations) 647running aggregates 339

overview 347running headers 548running report executables 43

from the command line 45–47running reports

page layouts and 528procedure for 26report sections and 301, 310, 314, 317saving parameters 628with specific parameters 632

run-time connection properties 647, 648Runtime section (configurations) 642Runtime tag 647

SSales Detail example report 356sample applications xxivsample configurations 6, 8, 650sample database 4

loading 225Sample Parameter Values dialog 69sample reports xxiv

generating subreports from 321on demand reporting 635overview 15showing optimized contents pages 319,

320with alternating backgrounds 356

sample templates 8Sample_configuration_file.xml 6sample_configuration_file.xml 652sample_sfdata_library.rol 655SampleValue property 107, 595SAP BW BEx Data Source Builder

creating MDX queries 263displaying technical names 265opening 264setting SAP variables 277, 278specifying MDX query axes 267specifying slices 276, 277updating metadata 265viewing dimensions in 265

SAP BW data streamsadding to designs 257, 267, 280overview 256

SAP GUI clients 256SAP Java Connector libraries 256SAP variables 277, 278SAPOdsSource components 283Save As dialog box 25saving

component palettes 126design files 141read-only libraries 163report designs 24report parameters 628–632Reportlets 561

I n d e x 701

scalable fonts 563scaling factors 393scatter charts

attaching to data streams 444connecting points 484creating 450, 482–484defining dual axes for 487defining time series for 500, 507dual y-axis charts as 490–494DualYLinePattern property 492overview 437setting properties for 483specifying line properties 491

schemachecking table consistency 216refreshing dictionary for 209synchronizing with queries 205updating 209, 213viewing 182

scope 600, 604Scratch Pad 102–104

See also Design Editormoving components and 101overview 63, 84

Scratch Pad command 103search criteria 382search expressions 381Search Extension API xxisearch indexes 377–378search paths

choosing design 137–140configuration files 116images 361, 362included libraries 159removing directories from 139, 140report executables 44specifying 137, 138

search URLs 559, 561searchable controls 368Searchable property 366, 377searching

directories 139for control objects 366, 368for images 361–363large reports 377, 377–378subreports 321with hyperlinks 381

with indexes 377with QBE expressions 204

SearchNoIndex constant 366, 378SearchTag Property 375–377SearchWithIndex constant 366, 377section components 318sections

See also specific typeadding to reports 292, 303, 308, 312, 316design process and 40extracting as Reportlets 560getting distinct values for 342information objects and 228nesting 291, 295overview 290placing subpages in 541prebuilt 292removing from reports 304searches and 369types described 290

securitye.reporting solutions for xxenabling page-level xxii

security tools xxiiselect all character (queries) 243Select All command 100SELECT clause (SQL) 179, 190, 200Select Database dialog 5select painter. See Query Editorselecting

component libraries 155components 77, 99–100data sources 9, 17database tables 11, 18, 183databases 5report layouts 12report type 8, 16specific database columns 190, 201

selection formulas. See parametersSend Backward command 106Send to Back command 106separators (component palettes) 122sequential reports

building 308defined 291printing 309running 310

702 D e v e l o p i n g A d v a n c e d e . R e p o r t s

sequential section componentsadding 308creating subreports with 321

sequential sectionsadding 308defined 290overview 307–311placing components in 308placing title page on 537searching 369setting print order 309–310

series (defined) 430series labels 430SeriesExp property

area charts 480bar charts 469detail charts 477dual y-axis charts 487line charts 479pie charts 460scatter charts 483summary charts 475, 476time series charts 502, 515

SeriesLabelExp propertyarea charts 481bar charts 469detail charts 477dual y-axis charts 488line charts 479scatter charts 483summary charts 475, 476time series charts 502, 515

SeriesLinkExp property 522Server Integration Technology xxiserver profile names 27server profiles

changing 142managing 142setting up 27–29testing 29

server-based reporting xxservers

connecting to 166, 167–172copying font files to 572e.reporting solutions for xixmanaging clusters for xxisharing connections 293

verifying connections 207setting database connections 645–647setting default page size 82, 83setting margins

for dynamic text controls 418–421page layouts 531, 533, 542, 544

setting measurement units 129–132, 531setting page orientation 531, 533setting properties. See propertiessetting sort order 22, 198, 307setting up projects 40setting Visibility properties 568sfdata data source

creating charts with 463, 465, 471Shadow property 350ShowAsPercent property

area charts 482pie charts 460

ShowFooterOnLast property 87, 367, 549ShowHeaderOnFirst property 87, 367, 549ShowInDHTML property 359ShowInPDF property 359ShowInReportlet property 359ShowLines property

area charts 482detail charts 479pie charts 460scatter charts 484summary charts 476

ShowOverflowChar constant 352ShowSticks property

detail charts 479summary charts 476

ShowSymbols propertyarea charts 482detail charts 479pie charts 460summary charts 476

ShowWhenPrinting property 359ShowWhenViewing property 359Simple Page List option 535simple page lists 534single selection 77single-line controls

truncating data in 351–354truncating text in 354–355

SIZE attribute 665

I n d e x 703

Size property 105, 545sizing handles 105Slot Information command 309, 539slots (Design Editor)

adding dynamic controls to 406conditional sections 313group sections 299, 300overview 85–88page layouts 534, 548parallel sections 316placing components 88, 90sequential sections 308

small reports 637snap to grid 102Snap To Grid command 102SOAP messaging protocol xxiisoft fonts 562sort filters 176, 177sort key columns

adding 306creating 198, 296defined 294

sort keysdeleting 307group sections and 176, 293, 301sorting with 197specifying 198, 296, 306

sort options 176, 252sort order

changing 304default 296setting 22, 198, 272, 296, 307

sort utilities 176Sorting & Grouping command 303Sorting and Grouping dialog 302sorting data

database utilities for 176for grouped reports 304, 306–307for unique values 342in crosstab reports 585in custom data sources 176, 177in detail rows 22in SQL databases 176on column names 296on primary keys 194overview 175with Component Editor 198, 199

with group sections 296with Query Editor 197–198with sorting property 177with text-based queries 251

Sorting page (Sorting and Grouping) 306Sorting property 200sorting property 177SortParamsByAlias property 627source code

See also Actuate Basicgenerating 51read-only libraries and 162specifying default font for 118viewing 43writing 70

source filesadding to configuration files 644adding to designs 148, 154, 157generating 42including in reports 153tracking design changes with 42

SpaceBetweenLines property 410SpaceBetweenParagraphs property 410spacing 409, 410, 661special characters 662, 665Specify Grouping page 20, 21Specify Parameter File Name dialog 630SplitIfNecessary constant 414SplitIfPossible constant 414SplitMarginBottom property 418, 420SplitMarginTop property 418, 420spreadsheets

designing xxi, xxiiigenerating xxiilinking with OLE controls 364

SQL databasesconnecting to 167connection parameters for 170optimizing report generation for 176

SQL expressions. See QBE expressionsSQL page (Query Editor)

overview 68viewing query statements 202

SQL queriesadding tables 183–188

SQL statementsadding conditions 205

704 D e v e l o p i n g A d v a n c e d e . R e p o r t s

SQL statements (continued)adding tables 19, 68, 183–184, 241

multiple copies 183building data sources for 174changing ad hoc parameters in 251changing input parameters 246changing tables properties for 185, 214creating

for data groups 180for multi-table joins 193–195for summary values 200–201

data filters vs. 175defining ad hoc parameters for 248–251defining sort keys 197–198defining text-based 69, 238, 241, 242editing 243entering 181evaluating statements 203example for 637optimizing 203overview 177–181removing multi-table joins 195removing tables from 184replacing lookahead aggregates with 348returning computed columns 191–193selecting specific columns 190setting conditions 179, 196–197, 201, 204setting conditions at run time 196setting static parameters for 246, 247sorting with 251undoing changes to 244verifying 206, 216viewing 202

standard deviation 334standard page styles 529starting

e.Reporting Designer Professional 45Expression Builder 72Information Object wizard 223Listing Report wizard 16Query Editor 182Quick Report wizard 8SAP BW BEx Data Source Builder 264Textual Query Editor 240

starting values, plotting 438, 486static controls

adding to reports 326, 328displaying values 337

static parametersdefining for Requester 608setting for text-based queries 246, 247

Static Parameters page 246, 247status messages 14stock prices 486stocks, tracking 438stocktrades data source 499

creating charts with 491, 508Stocktrades.mdb 499Stored Procedure Data Source Builder 69stored procedures

accessing 69entering parameters 69overview 173replacing lookahead aggregates with 348

Stored Procedures toolbar 76storing images 363strings

defining for online help 357, 358hyperlink search expressions and 382not displaying correctly 565truncating in multiline controls 356truncating in single-line controls 354–355wordwrapping 354, 355, 356

structural group reports 20structure pane (Design Editor)

gray or dimmed components in 61moving components 101overview 60–61placing components 88–90removing components 110resizing components 105selecting components 99setting fonts for 120

Structure Reference List dialog box 309, 540structured content technology xviiistructures, referencing 336subclasses 53subclassing 96–98

overview 53–55publishing and 148report components 94

subpage componentsadding 541, 542inserting flow components 543, 545inserting label controls 553

I n d e x 705

Subpage slot (Design Editor)adding components to 541, 542conditional sections 313group sections 300parallel sections 316sequential sections 308visual components 87

subpagesadding headers and footers 546creating 293, 300, 309, 314, 316creating backgrounds for 554defined 87defining printable areas 542overview 541–542

subreportsassigning flows to 317defined 291designing 290guidelines for creating 321in different flows 315printing 317

subroutines 70substituting fonts 565subtotals 337Sum function 338, 586summary charts

adding time series to 513, 520area charts as 480bar charts as 468creating 449dual y-axis charts as 494line or tape charts as 474pie charts as 456setting properties 471

summary dataadding to grouped reports 21adding to reports 87creating aggregate controls for 334displaying in crosstabs 576overview 200

Summary Options command 21summary reports 322summary values

creating 200–201getting unique 340–345getting with conditions 346–347getting with value expressions 338–347

SummaryControl constant 334Summarytimeseries.rod 495superclasses 53, 54, 108Supported Products matrix 177Sybase tables

connecting to 167connection parameters for 171verifying connections 208

Synchronize Query command 210Synchronize Query With Schema button 210Synchronize Query with Schema dialog 210

displaying output for 213synchronizing queries 205–219

checklists for 213prerequisites for 206

synonyms. See table synonyms; view synonyms

syntaxSee also bracket notationad hoc parameters in queries 249command-line executables 45, 46configuration files 641, 642, 643lookahead aggregates 339, 340QBE expressions 196, 201, 204running aggregates 339, 340search URLs 559, 560static parameters 246validating SQL 206value expressions 341, 346

syntax conventions (documentation) xxxisystem tables 183

viewing 189

Ttab characters 662tab stops 411, 660, 661tabbed text 411Table and Column command 182table consistency checks 209, 216table of contents

creating 318, 320default values 318developing for grouped reports 318optimizing 318–321

Table Property dialog 185, 214table synonyms 187–188

706 D e v e l o p i n g A d v a n c e d e . R e p o r t s

tablesSee also databasesaccessing 166, 167adding to queries 19, 68, 183–188, 241alternate names for 184changing properties 185, 214displaying nonsynchronized 211entries invalid or not found 214grouping data by 20linking related 193, 194obsolete 215referencing for query statements 185removing from queries 184renaming 184, 185, 217report generation and 328retrieving all columns 190selecting 11, 18sorting data 175, 197–198, 199, 251

on primary keys 194sorting for unique values 342updating definitions 213viewing 68, 182, 183

Tables and Joins page (Query Editor)deleting tables 184setting table properties from 185synchronizing queries 206

TabPadding properties 412TabSpacing property 413tabular reports 268, 269tags

configuration files and 641, 642special characters in 665supported HTML 663unrecognized 392

tape chartsadding legends 475, 478creating 450, 474–479labeling 475, 477overview 434, 435

targets. See slotstechnical assistance xxivTemplate tag 645templates

creating component 98opening sample 8specifying 645

temporarily removing components 109

temporary reports 381, 383, 384testing

report designs 564reports 27–33, 42server profiles 29

textadding to reports 328, 390adjusting spacing 408, 410aligning 661, 664, 665displaying 337, 393formatting 391, 396indenting 661justifying 408setting margins for 418–421setting tab stops for 411truncated 392, 407truncating in multiline controls 356truncating in single-line controls 354–355wordwrapping 354, 355, 356

text attributes 595, 661, 664text controls

See also data controlsadding 87adjusting formats for dynamic 407–413creating page numbers with 550, 551displaying values 337overview 328, 390report generation and 328

text editors 43text formats

adjusting 407–413HTML tags for 664rich text control words for 660

Text property 337crosstab reports and 595

text strings. See stringstext-based queries

changing ad hoc parameters in 251changing result column properties 245converting to graphical 252creating 69, 238, 241, 242defining ad hoc parameters for 248–251editing 243optional procedures 239required procedures 238setting ad hoc parameters for 250setting static parameters for 246, 247

I n d e x 707

text-based queries (continued)sorting with 251specifying data sources for 239

TextCharacterWrap constant 355, 356TextFormat property 396TextPlacement property

crosstab reports and 595setting overflow character with 352truncating multiline text controls 356truncating single-line data controls 351,

352, 353, 354truncating single-line text controls 354,

355TextTruncateLines constant 356textual queries. See text-based queriestextual query data sources

overview 238selecting 239

Textual Query Editoraccepting the query 243defining ad hoc parameters with 248, 249defining static parameters in 246editing queries 243editing result column properties 245erasing query statements 244overview 58, 69, 238setting data sources in 239setting SQL properties with 247, 250sort options 252starting 240writing queries 238, 241, 242

TextWordWrap constant 354, 356TGA images 360Then slot (Design Editor) 313third-party productivity tools xxithird-party security tools xxiithree-dimensional charts

formatting 450overview 431, 435

throughput 321tick intervals

specifying for dual y-axes 456specifying for value axes 455specifying for y-axes 455

tick marksdetail charts and 520dual y-axis charts and 489

in charts 430scatter charts and 503

TickInterval property 503, 516TickIntervalUnit property 504, 505, 516TIF images 360time 328, 612time continuums 434, 437, 438time formats 349time functions 552time series charts

bar charts and 470creating 499–507default formats for x-axis labels 505detail charts as 508formatting 500, 502high-low-close charts and 484limitations 521overview 440–441plotting time intervals for 502, 503rounding starting values for 503setting tick intervals 503stocktrades data source for 499summary charts as 513, 520with multiple time series 502, 510

time stamps 552TimeSeries property 501title pages 534, 536, 537Title/Body Page List option 536TitleFont property 234TitlePage components 537TitlePage slot (Design Editor) 536titles

adding to charts 430adding to reports 12, 553formatting 460setting chart properties 473

To be continued strings 300TocAddComponent property 318, 320TocAddContents property 318, 320TOCIfAllVisible setting 318tool tips 75toolbars

accessing Navigator 117adding buttons 122described 74–77displaying 136docked vs. floating 133

708 D e v e l o p i n g A d v a n c e d e . R e p o r t s

toolbars (continued)identifying buttons 75moving 133, 134overview 58tool specific 76

Toolbars command 136tools 58

See also specific toolsdisplay options for 137

Total command 338totals

adding to reports 21charts 434computing 338, 340, 341displaying in charts 432group sections returning 293

TQE data sources 238, 239tracking design changes 42trailing spaces 353, 354, 355transaction database 348transactions xixtransparent colors 554trends xxii, 434, 474triggering hyperlinks 378truncating data 351–354truncating text

in dynamic text controls 392, 407multiline controls 356single-line controls 354–355

twips 82, 129two-dimensional charts 431

formatting 450two-pass aggregates. See lookahead

aggregatesType attribute 646types. See data typestypographic conventions

(documentation) xxx

U–u command-line option 46unavailable fonts 393, 565undoing changes in SQL statements 244Unicode characters 118, 660, 662, 665unique series 445

units of measurementcustomizing 129–130setting suffixes for 131–132specifying 531

Units page (Options dialog) 129, 131universal hyperlinks 386UNIX servers

formatting charts for 524printing from 564

unknown data types 212unordered lists 664unrecognized RTF tags 392unstructured content xixupdates xxiiiupgrades 46URLs

Actuate libraries and 156creating 378, 380defining as hyperlinks 387defining for temporary reports 381extracting Reportlets from 559, 561setting Management Console 117shortcuts for 645

usability 321, 635Use As dialog box 90Use Default Values option 632user names

defining for connections 170, 171setting as parameters 603

user-defined values 337UserName property 167

Vvalue axes

defined 430displaying gridlines for 455formatting 453, 454setting properties 473

value expressionsSee also ValueExp propertycreating 71, 333–347defined 333defining conditions 346–347examples for charts 464, 471, 509, 512null values in 335producing text values 337

I n d e x 709

value expressions (continued)referencing column names 335referencing controls 337referencing functions 335, 336referencing report parameters 337referencing variables 335returning distinct values 340–345returning summary values 338–347

value labels 430value titles 430ValueColorList property 460ValueExp property

aggregate controls 339date/time stamps 552overview 347page numbers 551report parameters 612setting at run time 337setting for controls 333setting for multiple columns 335setting for single columns 335static controls 337

valuesSee also summary valuesassigning as literals 337assigning to controls 333–347averaging 338changing over time 440, 499–507comparing 432, 434, 437, 440, 441display options 129, 131displaying in Requester 612filtering duplicate 340, 342getting first/last 338, 339getting maximum/minimum 338grouping related 293, 294, 303multiple in expressions 334null 346required 600returning unique 340–345returning with conditions 346–347setting at run time 196, 204, 337, 600showing range 438showing relationships 432, 437sorting by interval 297user-defined 337

ValuesColorList property 459ValueType property 334

variablesadding 327, 331assigning to report parameters 603, 606,

614data rows as 175defined 51displaying 63, 65displaying parameters as 603referencing 335report parameters as 600subclassing and 53

Variables page (Component Editor)declaring report parameters 605deleting report parameters 634overview 66

versioning reports 383Vertical constant 595VerticalPosition property 399, 403, 589VerticalPositionFrameBottom constant 404VerticalPositionFrameTop constant 404VerticalSize property 397, 400, 401, 402VerticalSizeFrameRelative constant 397, 402VerticalSizeRelative constant 397, 401video displays 562view synonyms 187–188Viewer xxiii

defining hyperlinks for 380displaying reports in 14, 26overview 59, 73providing help for reports in 357–359searching reports with 369toolbar 76

Viewer Search feature 321viewing

column names 190component palettes 77, 136component properties 65components 64context menus 78current date 336data 327, 328

from a single column 335from alternate sources 326from multiple columns 335in crosstabs 576in static controls 337

database tables 68, 182, 183

710 D e v e l o p i n g A d v a n c e d e . R e p o r t s

viewing (continued)Design Editor grids 102DHTML reports xixdynamic text controls 422hyperlinks 378images 327, 360MDX queries 279methods 70numbers 337online documentation xxviiprintable areas 543query statements 202report designs 107report files 64report parameters 603, 612, 615reports xxiii, 14, 26, 41, 73, 562source code 43synchronization information 211, 213text 337, 393toolbars 136variables 63, 65

view-time errors 318visible grid

charts 453, 455, 489report designs 102

visual components 85visual designs 528volumes. See Encyclopedia volumes

Wwatermarks 554web browsers

displaying online documentation in xxviidisplaying reports in xxiiihyperlinks and 380printing from 35

web pagesSee also HTML reportsembedding Reportlets in 560, 561

web sitese.reporting solutions for xviii, xixincluding libraries from 156obtaining Actuate product updates xxiiisecuring xxitesting reports for 27testing reports on 42

web-based hyperlinks 378, 386WHERE clause (SQL)

compared to Having clause 179conditions and 179, 196creating 194user input and 248

Where keyword 340, 346widow control 421WidowAndOrphanControl constant 421Width property

crosstabs 592dynamic text 397

Window menu 110Windows servers

formatting charts for 524printing from 562, 563

windows. See application windowwizards

choosing configuration files 651customizing item list for 143, 144overview 7, 15, 223previewing designs 12saving designs 24selecting data sources for 9, 17selecting database tables 11, 18selecting report layouts 12selecting report type 8, 16setting sort order 22starting 8, 16

word processing applications 364Wordpad documents 365WordWrap constant 356, 595wordwrapping 354, 355, 356working directories 160

XX axis. See category axesXLabelFormat property 504, 506, 516XML data sources xxiiiXML development tool xxiiXML format (configurations) 641XML tags 642XValueExp property

scatter charts 483time series charts 501

I n d e x 711

YY axis. See value axesYLabelStyle property 455YOverlayKeyValue property 488YOverlayLabelStyle property 456YOverlayLineColor property 489YOverlayLinePattern property 489YOverlayLineThickness property 489YOverlayShowSymbols property 489YTickInterval property 455

YValueExp propertyarea charts 481bar charts 469, 472detail charts 477, 479pie charts 457, 460, 464, 467scatter charts 483summary charts 475, 476time series charts 501

ZZoom control 543Z-order (components) 106

712 D e v e l o p i n g A d v a n c e d e . R e p o r t s