Programming 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-130311 April 11, 2003

i

ContentsIntroduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xxiUnderstanding Actuate 7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxi

Addressing diverse customer profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiiAddressing customer requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiiSupporting international information delivery requirements . . . . . . . . . . . . . . . . . xxiiProviding a scalable, high performance server . . . . . . . . . . . . . . . . . . . . . . . . . xxiiProviding a complete information delivery solution . . . . . . . . . . . . . . . . . . . . . xxiii

Introducing the Actuate 7 and ReportingEngines product suite . . . . . . . . . . . . . . . . xxivAbout Actuate e.Report Designer Professional product . . . . . . . . . . . . . . . . . . . . . xxviiAbout Programming e.Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxixOnline documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxxii

Using online manuals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxxiiUsing online help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxxii

Using context-sensitive online help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxxiiUsing the Actuate online help system. . . . . . . . . . . . . . . . . . . . . . . . . . . . xxxiiUsing report-specific online help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxxiv

Typographical conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxxvSyntax conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxxv

Part 1Programming with the Actuate Foundation Classes

Chapter 1Understanding the Actuate Foundation Classes . . . . . . . . . . . . . . 3About the Actuate Foundation Class architecture . . . . . . . . . . . . . . . . . . . . . . . . . . 4

About abstract base classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4About concrete classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Understanding the AFC by functional category . . . . . . . . . . . . . . . . . . . . . . . . . . . 7About report object structure classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7About connection classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

About connection abstract base classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8About connection concrete classes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

About data stream classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9About data stream abstract base classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9About data stream concrete classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10

About report section classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10About report section abstract base classes . . . . . . . . . . . . . . . . . . . . . . . . . . .10

ii

About report section concrete classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10About page layout classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

About page layout abstract base classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11About page layout concrete classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

About control classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13About control abstract base classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14About control concrete classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

About internal tool classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14About collection classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Chapter 2Working with a class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17About classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Declaring a class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Understanding class relationships . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

About inheritance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20About scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Understanding class scope naming conventions . . . . . . . . . . . . . . . . . . . . . . . 22About default class scope in a report design . . . . . . . . . . . . . . . . . . . . . . . . . 22About the default scope of a class in a library . . . . . . . . . . . . . . . . . . . . . . . . 24

About class variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24About variables in Component Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24About visibility of variables in Component Editor . . . . . . . . . . . . . . . . . . . . . . . 25Using property variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26Using parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28Using regular variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

About methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30Using methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30About methods you can override . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31About methods you can call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31About private methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32Overloading a method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Chapter 3Working with an object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33About objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34Creating an object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Declaring an object reference variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34Declaring an object reference variable as a specific class . . . . . . . . . . . . . . . . . . 35Declaring an object reference variable as AnyClass type . . . . . . . . . . . . . . . . . . 36

Creating an object using New . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36Using an object reference variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Working with a simple variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

iii

Working with an object reference variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . .38Referencing an object’s variables and methods . . . . . . . . . . . . . . . . . . . . . . . . . .39Referencing a method of a class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .40

Referencing a method in a superclass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .40Using a class name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .40Resolving an ambiguous method call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41

Assigning an object to an object reference variable . . . . . . . . . . . . . . . . . . . . . . . .42Comparing Set and Let . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43Setting an object reference variable to Nothing . . . . . . . . . . . . . . . . . . . . . . . .43

Passing an object reference to a procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43Getting information about an object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .44Testing an object reference with the Is operator . . . . . . . . . . . . . . . . . . . . . . . . . .44

Testing for Nothing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .44Comparing object reference variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45

About object lifetime. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45About transient objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45About persistent objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .46

Chapter 4Using Component Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47About Component Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .48Getting information about a class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .48

Viewing general information about a class . . . . . . . . . . . . . . . . . . . . . . . . . . . .49Inspecting a variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .50Viewing and setting property values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .51Inspecting a method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .51

Working with a class variable. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52Creating a class variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .53Editing a variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .55Deleting a variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .56

Overriding an inherited method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .56Overriding a method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .56

Working with a user-defined method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .57Creating a method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .58Naming a method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .59Editing a method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .60Deleting a method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .61

Chapter 5Understanding document generation . . . . . . . . . . . . . . . . . . . . . . 63Overview of the Factory service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .64Starting the Factory service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .65

Adding startup and cleanup code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .66

iv

Starting the build process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66Creating content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

Using the core protocol for content creation . . . . . . . . . . . . . . . . . . . . . . . . . . . 68Using a component reference in content creation . . . . . . . . . . . . . . . . . . . . . . . . 68

Using a report section to implement the content-creation protocol . . . . . . . . . . . . 69Using a group section to implement the content-creation protocol . . . . . . . . . . . . 70Using a frame to implement the content-creation protocol . . . . . . . . . . . . . . . . . 71Using a control to implement the content-creation protocol . . . . . . . . . . . . . . . . 72

Creating a page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72Determining the page on which to place a frame . . . . . . . . . . . . . . . . . . . . . . . . 73Understanding the page list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

Instantiating a class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74Working with a data stream . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

About data adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76Combining data adapters to form a data stream . . . . . . . . . . . . . . . . . . . . . . . 76About the protocol for a data adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78Instantiating a data adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

Sequential and random access to data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79About data sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80About data filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80About data rows. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

Understanding the data row life cycle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81Connecting to a database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

Placing the connection in a data stream . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83Placing a connection in a section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83About connection precedence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84About SQL support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84Using statements and cursors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85About connection relationships . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85Creating and executing a custom SQL statement . . . . . . . . . . . . . . . . . . . . . . . . 86

Part 2Customizing report designs

Chapter 6Customizing a report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89Customizing a data stream . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

Creating a computed data row variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90Filtering out a selected data row. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91Creating a select filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92Creating a sort filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

v

Retrieving data from a flat file. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .94Working with data from multiple sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . .98

Customizing the report layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104Conditionally creating a component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104Dynamically embedding an image control . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

Customizing report data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108Conditionally setting properties of a control . . . . . . . . . . . . . . . . . . . . . . . . . . 108Creating a custom control to display a group section key . . . . . . . . . . . . . . . . . . . 108Changing a control property based on another control’s value . . . . . . . . . . . . . . . . 110

Using GetControlValue( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110Using the ObjectVariable property. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111Using FindContentByClass( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112Using a global variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

Chapter 7Debugging a report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115About debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116Understanding the types of errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

About compilation errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116Run-time errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117Logic errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117About the Actuate Output window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

Starting a debugging session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118Controlling program execution. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

Running to a breakpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123Stepping through code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123Resuming code execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124Stopping code execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

Examining variable values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125Monitoring a variable as its value changes . . . . . . . . . . . . . . . . . . . . . . . . . . . 125Interpreting the icons in the Variables window . . . . . . . . . . . . . . . . . . . . . . . . . 126Tracing object reference variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126Checking the value of a specific variable. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

Viewing the stack of method calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

Chapter 8Designing a report with page-level security . . . . . . . . . . . . . . . . 131About personal views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132About page-level security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

About the Security ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133About the Access Control List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133About the GrantExp property for a secure report . . . . . . . . . . . . . . . . . . . . . . . . 134Viewing a report with page-level security . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

vi

Designing a report with page-level security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135Testing a report design security example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141

Understanding the security scenario example . . . . . . . . . . . . . . . . . . . . . . . . . . 141Examining the report component for the security example . . . . . . . . . . . . . . . . . . 142Reviewing the query for the security example. . . . . . . . . . . . . . . . . . . . . . . . . . 142Examining the GrantExp property for the security example . . . . . . . . . . . . . . . . . . 143Examining the page layout for the security example . . . . . . . . . . . . . . . . . . . . . . 144Examining the report security example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145

Testing a security requirement example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149Examining the report design and GrantExp property . . . . . . . . . . . . . . . . . . . . . 149

Customizing the Security ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151Using GetUserACL( ) to create a Security ID . . . . . . . . . . . . . . . . . . . . . . . . . . 152

Customizing the Access Control List. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153Using the CascadeSecurity property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153Using the GetFullACL( ) method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153Using the SetSecurity( ) method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153

About the secure read privilege. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154

Chapter 9Programming for report viewing events . . . . . . . . . . . . . . . . . . . 155About report viewing events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156

Objects that respond to report viewing events. . . . . . . . . . . . . . . . . . . . . . . . . . 156Mouse events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156Responding to mouse events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157

About the Shift value in mouse event methods . . . . . . . . . . . . . . . . . . . . . . . 158Using the Shift value. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158

Creating a context menu. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159About default context menu items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160

About the Default Action context menu item. . . . . . . . . . . . . . . . . . . . . . . . . 160About the Help context menu item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160About the Copy Link context menu item . . . . . . . . . . . . . . . . . . . . . . . . . . . 160

Customizing context menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161Providing help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162

Providing balloon help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162Providing context-sensitive help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163

Chapter 10Using and customizing a stored procedure . . . . . . . . . . . . . . . . 167About stored procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168

About stored procedure result sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168Using stored procedure tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168

Designing a report with stored procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171

vii

Working with stored procedures dialogs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174Working with data from a stored procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176

Synchronizing the stored procedure design . . . . . . . . . . . . . . . . . . . . . . . . . . . 177Narrowing a search and matching patterns in stored procedures. . . . . . . . . . . . . . . 177

Working with sample values for input parameters . . . . . . . . . . . . . . . . . . . . . . . . 179About input and output parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180About Oracle8 and Oracle9i stored procedures . . . . . . . . . . . . . . . . . . . . . . . . . . 182

About stored functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182Using the Stored Procedure Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182Overriding the OpenCursor method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183Understanding the data retrieval example. . . . . . . . . . . . . . . . . . . . . . . . . . . . 184

About the EMP table in the example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184About the stored function in the example . . . . . . . . . . . . . . . . . . . . . . . . . . 184About the Stored Procedure Data Source Builder in the example . . . . . . . . . . . . . 186About parameters in the example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186About the Requester in the example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188About the report in the example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188

Customizing a stored procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188Accessing a stored procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188

Working with a Sybase stored procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . 189Working with an Oracle stored procedure . . . . . . . . . . . . . . . . . . . . . . . . . . 191Working with a stored procedure’s return value. . . . . . . . . . . . . . . . . . . . . . . 192Working with a stored procedure to return an ID . . . . . . . . . . . . . . . . . . . . . . 192

Accessing Sybase SQL Server multiple result sets . . . . . . . . . . . . . . . . . . . . . . . 193Accessing Oracle8 and Oracle9i stored procedure multiple result sets . . . . . . . . . . . . 194

Adding support in Actuate Basic methods . . . . . . . . . . . . . . . . . . . . . . . . . . 194Mapping Actuate variable types and Visual Basic type codes . . . . . . . . . . . . . . . . . 198

Chapter 11Writing custom browser code . . . . . . . . . . . . . . . . . . . . . . . . . . . 201About custom browser code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202About the browser scripting control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202

Including custom browser code in a report design . . . . . . . . . . . . . . . . . . . . . . . 205About the context block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205Clipping the output of custom browser code . . . . . . . . . . . . . . . . . . . . . . . . . . 206Aligning the output of custom browser code . . . . . . . . . . . . . . . . . . . . . . . . . . 207Debugging custom browser code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208

Including global custom browser code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209Creating an HTML form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210Generating custom browser code dynamically . . . . . . . . . . . . . . . . . . . . . . . . . . . 210

Overriding BrowserCode( ) and GetText( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . 211Determining the application execution context . . . . . . . . . . . . . . . . . . . . . . . 211Generating output for different browsers. . . . . . . . . . . . . . . . . . . . . . . . . . . 211

viii

Adjusting for the current scaling factor . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212Overriding the BuildFromRow( ) and OnRow( ) methods . . . . . . . . . . . . . . . . . . . 212

Printing and viewing a report using the PDF converter . . . . . . . . . . . . . . . . . . . . . . 213Displaying different controls in DHTML and PDF output . . . . . . . . . . . . . . . . . . . 214ShowWhenPrinting and ShowWhenViewing . . . . . . . . . . . . . . . . . . . . . . . . . . 214

Printing and viewing a report using the Actuate Viewer . . . . . . . . . . . . . . . . . . . . . 214Creating an example library for Internet Explorer . . . . . . . . . . . . . . . . . . . . . . . . . 215

Using DHTMLForm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215Working with DHTMLForm variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216Working with DHTMLForm methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216Subclassing DHTMLForm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217

Working with DHTMLMenuControl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218Working with DHTMLMenuControl variables . . . . . . . . . . . . . . . . . . . . . . . . 218Working with DHTMLMenuControl methods . . . . . . . . . . . . . . . . . . . . . . . . 218Subclassing DHTMLMenuControl. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220Displaying custom browser code in the Viewer . . . . . . . . . . . . . . . . . . . . . . . 221Displaying custom browser code output in a web browser . . . . . . . . . . . . . . . . . 222

Creating a report for viewing in Netscape. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222

Chapter 12Designing a report for XML data. . . . . . . . . . . . . . . . . . . . . . . . . . 225About the XML data format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226

About Document Type Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226Examining a simple XML document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227

About the View process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228Publishing an Actuate report as XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229

Mapping XML to Actuate report sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230About XML properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230

About AcReport XML properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231About AcReportComponent XML properties . . . . . . . . . . . . . . . . . . . . . . . . 232About AFC XML functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232

Chapter 13Understanding report bursting techniques. . . . . . . . . . . . . . . . . 237About report bursting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238Understanding report bursting techniques . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238Understanding report bursting tasks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239Examining report bursting examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240

Examining a subreport bursting example . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240Examining the report structure for a subreport bursting example . . . . . . . . . . . . . 241Examining the detail report’s PageList component for a subreport bursting example. . 241Examining the detail query for a subreport bursting example . . . . . . . . . . . . . . . 242

ix

Examining the BuildFromRow( ) method for a subreport bursting example . . . . . . . 242Examining the SuggestRoiName( ) method for a subreport bursting example . . . . . . 243Examining the summary entry’s LinkExp property for a subreport bursting example . 243

Examining a group bursting example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244Examining the report structure for a group bursting example . . . . . . . . . . . . . . . 244Examining the detail report’s PageList component for a group bursting example. . . . 245Examining the SuggestRoiName( ) method for a group bursting example . . . . . . . . 245Examining the summary entry’s LinkExp property for a group bursting example . . . 245

Part 3Programming with Actuate Basic

Chapter 14Introducing Actuate Basic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249About Actuate Basic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250Programming with Actuate Basic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251Understanding code elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252

About statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252About expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253About operators. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253

Using an arithmetic operator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254Using a comparison operator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254Working with logical operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255Using the concatenation operator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256

About operator precedence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256Adhering to coding conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256

Commenting code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256Breaking up a long statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257Placing short, related statements on a single line . . . . . . . . . . . . . . . . . . . . . . . . 257Indenting code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257Using a consistent naming and style convention . . . . . . . . . . . . . . . . . . . . . . . . 257About naming rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258

Using the code examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258

Chapter 15Understanding variables and data types. . . . . . . . . . . . . . . . . . . 259About variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260

Declaring a variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260About global variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260Using a local variable. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262About class variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263

x

Declaring an array . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263About multi-dimensional arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264About dynamic arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264Changing the size of an array . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264

About data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264Using standard data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265Using an AFC data type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265Assigning a data type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266

Using the As keyword. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266Using a type-declaration character. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266

About constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267Working with variant data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267Working with string data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268

Declaring a string . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268Using binary string data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269Manipulating a string. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269Formatting strings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270Comparing strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270Changing capitalization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271Removing spaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271Embedding a quote in a string. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272

Working with numeric data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272About numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272About currency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272Using numeric data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273

Working with date data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273Using Date display formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274Formatting date and time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274

Working with a user-defined data type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275Using an alias . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275Using a structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275Using a class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276

Working with a CPointer data type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276Converting a data type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277

Chapter 16Writing and using a procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . 279About procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280

About scope in procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280About methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280Creating a global procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281

Declaring a procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282

xi

Declaring a Sub procedure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282Declaring a Function procedure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282

Declaring an argument . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283About argument data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284Passing an argument by reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284Passing an argument by value. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284

Calling a procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284Calling a Sub procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284Calling a Function procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285

Overloading a procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285Using a control structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285

Using If...Then. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286Using If...Then...Else . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286Using Do...Loop. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286Using For...Next . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287Using a nested control structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287Exiting a control structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287Exiting a Sub or Function procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287

Part 4Programming in the Windows environment

Chapter 17Using an object from another application. . . . . . . . . . . . . . . . . . 291Adding an object from another application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292About object linking and embedding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292

About supported OLE objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293About OLE custom controls (OCX) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293

Understanding linking and embedding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294Working with a linked object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294Working with an embedded object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295

Guidelines for linking and embedding. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296Linking and embedding an OLE object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296Editing an OLE object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299Inserting an OLE custom control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300Moving and sizing an OLE component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301Subclassing an OLE component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302

xii

Chapter 18Programming an object from another application . . . . . . . . . . . 303About programming other applications’ objects . . . . . . . . . . . . . . . . . . . . . . . . . . 304About OLE Automation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304

Differentiating an OLE Automation object from another OLE object . . . . . . . . . . . . . 304Determining which OLE Automation objects an application supports . . . . . . . . . . . . 304

Creating an OLE Automation object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305Working with an OLE Automation object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305Using an OLE Automation example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306

Chapter 19Calling an external function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309Calling an external C function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310Using a C function with Actuate Basic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310Declaring a C function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311

Declaring the C function as a Sub procedure . . . . . . . . . . . . . . . . . . . . . . . . . . 311Declaring the C function as a Function procedure . . . . . . . . . . . . . . . . . . . . . . . 311Understanding C function declaration issues . . . . . . . . . . . . . . . . . . . . . . . . . . 311

Specifying the library of a C function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312Passing an argument by value or reference . . . . . . . . . . . . . . . . . . . . . . . . . . 312About flexible argument types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312Aliasing a non-standard C function name . . . . . . . . . . . . . . . . . . . . . . . . . . 313

Determining an Actuate Basic argument type . . . . . . . . . . . . . . . . . . . . . . . . . . 313Calling a C function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314

Calling a C function with a specific data type . . . . . . . . . . . . . . . . . . . . . . . . . . 315Passing a string to a C function. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315Passing an array to a C function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315Passing a null pointer to C function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315Passing a user-defined data type to a C function. . . . . . . . . . . . . . . . . . . . . . . 316Passing an object reference variable to a C function . . . . . . . . . . . . . . . . . . . . . 316

About return values from C functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316Working with a Java object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316

About Java requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316Creating a Java object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317Invoking a method and accessing a field on a Java object . . . . . . . . . . . . . . . . . . . 317Invoking a static method and accessing a static field . . . . . . . . . . . . . . . . . . . . . . 318

Converting a Java data type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318Converting a Java String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319Converting a Java null . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319Converting an array. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319

About Java exception and error handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320Debugging a Java object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321

xiii

Part 5Programming with Actuate’s C++ APIs

Chapter 20Using Actuate’s application programming interfaces . . . . . . . . 325About the programming interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326

About the Report Server API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326About the Requester API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326About the search extension API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327About the Actuate ActiveX controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327

A comparison of API features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328Choosing the appropriate API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329

When to use the Report Server API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330When to use the Requester API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330When to use the search extension API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330When to use Actuate ActiveX controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330

Chapter 21Requester API user guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333About the Requester API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334Understanding the Requester API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334

Working in the client-server environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335Working locally . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336

Using the Requester API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336About the Requester API development environment . . . . . . . . . . . . . . . . . . . . . 337

Identifying the APIs to your application . . . . . . . . . . . . . . . . . . . . . . . . . . . 337Selecting a compiler and other tools. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337Choosing API files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338Choosing a DLL file for the Windows environment . . . . . . . . . . . . . . . . . . . . . 339Working with UNIX libraries and path variables . . . . . . . . . . . . . . . . . . . . . . 340

About the Requester API operating environment. . . . . . . . . . . . . . . . . . . . . . . . 340Using the Requester API with the Actuate Viewer . . . . . . . . . . . . . . . . . . . . . 341

Understanding API functions by programming tasks . . . . . . . . . . . . . . . . . . . . . . . 341Writing startup and cleanup code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342Working with report files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342

Specifying a local file name—Requester API . . . . . . . . . . . . . . . . . . . . . . . . . 343Specifying an iServer file name—Requester API. . . . . . . . . . . . . . . . . . . . . . . 343

Getting the parameter and parameter group names . . . . . . . . . . . . . . . . . . . . . . 344Getting the parameter attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345Getting the default parameter values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346

xiv

Getting the current parameter values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346Setting parameter values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347Configuring a printer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348Running, viewing, and printing reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348

Running a report locally. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349Checking for errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349

Functions with direct error checking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350Functions that do not support error checking . . . . . . . . . . . . . . . . . . . . . . . . 350

Writing a Requester API application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350Writing an application that uses iServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351

Initializing an API session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351Connecting to iServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351Specifying parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352Running and viewing the report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353Printing the report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353Closing the API session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353

Writing an application for local reports. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354Declaring a Visual Basic method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354Initializing an API session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355Specifying parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355Generating a report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356Viewing a report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356Printing a report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356Closing a session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356

Processing a report request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357Using the Requester API in Actuate Basic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358

Generating a report in Actuate Basic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358Using the Requester API in Visual Basic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360

Accessing the Requester API from Visual Basic . . . . . . . . . . . . . . . . . . . . . . . . . 360Specifying the DLL in the Declare statement . . . . . . . . . . . . . . . . . . . . . . . . . 360

Manipulating parameter values, generating and printing a report . . . . . . . . . . . . . . 361Creating a custom dialog for requesting parameter values. . . . . . . . . . . . . . . . . . . 366

Using the Requester in a C++ application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368Working with a BSTR in the Windows environment . . . . . . . . . . . . . . . . . . . . . . 368Working with BSTRs in C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369

Chapter 22Requester API reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375AcReqCloseFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376AcReqConnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376AcReqDisconnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377AcReqGenerateReport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377

xv

AcReqGetAdhoc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382AcReqGetAlias . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382AcReqGetDefaultValueCurrency. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383AcReqGetDefaultValueDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384AcReqGetDefaultValueDouble . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385AcReqGetDefaultValueInteger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386AcReqGetDefaultValueStr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387AcReqGetDefaultValueString. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388AcReqGetError . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389AcReqGetErrorString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391AcReqGetFirstGroup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391AcReqGetFirstParameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392AcReqGetHidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393AcReqGetHideText . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393AcReqGetNextGroup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394AcReqGetNextParameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395AcReqGetParmType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396AcReqGetReportVersion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396AcReqGetRequired . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397AcReqGetType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398AcReqGetValueCurrency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399AcReqGetValueDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400AcReqGetValueDouble . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401AcReqGetValueInteger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401AcReqGetValueStr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402AcReqGetValueString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403AcReqGetVersionNumber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404AcReqHasDefaultValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405AcReqInitialize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405AcReqPrintReport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406AcReqReadFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407AcReqReportStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408AcReqSelectClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409AcReqSetDefaultPrinter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410AcReqSetEUDTPath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410AcReqSetPrinterCollate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411AcReqSetPrinterColor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411AcReqSetPrinterDuplex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412AcReqSetPrinterFormName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 412AcReqSetPrinterName. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413AcReqSetPrinterNumberCopies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413AcReqSetPrinterOrientation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413AcReqSetPrinterPaperSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414

xvi

AcReqSetPrinterScale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417AcReqSetPrinterTray . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417AcReqSetRequestPriority . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418AcReqSetScopedParameterName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418AcReqSetValueCurrency. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419AcReqSetValueDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420AcReqSetValueDouble . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421AcReqSetValueInteger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422AcReqSetValueString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422AcReqUnInitialize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423AcReqViewReport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424AcReqWriteFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425AcWReqConnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425AcWReqGenerateReport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426AcWReqGetAdhoc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430AcWReqGetAlias . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430AcWReqGetDefaultValueCurrency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431AcWReqGetDefaultValueDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432AcWReqGetDefaultValueDouble . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433AcWReqGetDefaultValueInteger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434AcWReqGetDefaultValueStr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435AcWReqGetDefaultValueString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 436AcWReqGetErrorString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437AcWReqGetFirstGroup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437AcWReqGetFirstParameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438AcWReqGetHidden . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439AcWReqGetHideText . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439AcWReqGetNextGroup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440AcWReqGetNextParameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441AcWReqGetParmType . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442AcWReqGetRequired . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442AcWReqGetValueCurrency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443AcWReqGetValueDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444AcWReqGetValueDouble . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445AcWReqGetValueInteger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446AcWReqGetValueStr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447AcWReqGetValueString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448AcWReqGetVersionNumber . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448AcWReqHasDefaultValue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449AcWReqPrintReport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450AcWReqReadFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452AcWReqSetEUDTPath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452AcWReqSetPrinterName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453

xvii

AcWReqSetValueCurrency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453AcWReqSetValueDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454AcWReqSetValueDouble . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455AcWReqSetValueInteger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456AcWReqSetValueString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457AcWReqViewReport. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457AcWReqWriteFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459Undocumented functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459

Chapter 23Search extension API user guide. . . . . . . . . . . . . . . . . . . . . . . . . 461About the search extension API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462Search extension API functions by programming task . . . . . . . . . . . . . . . . . . . . . . 462

Writing startup and cleanup code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463Setting search parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463Processing search results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 464

Developing a search extension . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 464Writing search extension code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 464Creating a definition file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465Creating a header file. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 466Compiling the code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 466

Installing a custom search extension. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 466

Chapter 24Search extension API reference. . . . . . . . . . . . . . . . . . . . . . . . . . 467Close. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 468GetColumnDelimiter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 468GetName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 469GetParameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 469IncludeHeader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 469InputParameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 470Open. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 470PutRow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 470SetDataTypeInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471SetParameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 472

Chapter 25Actuate ActiveX controls user guide. . . . . . . . . . . . . . . . . . . . . . 473About Actuate’s ActiveX controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474

Features of ActiveX controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474Adding the Actuate ActiveX controls to your application . . . . . . . . . . . . . . . . . . . 474Adding the Actuate ActiveX controls to Visual Basic. . . . . . . . . . . . . . . . . . . . . . 474

xviii

Adding the Actuate ActiveX controls to C or C++ . . . . . . . . . . . . . . . . . . . . . . . 475Using ActiveX controls embedded in dialogs . . . . . . . . . . . . . . . . . . . . . . . . . . 475

About report files and the Actuate ActiveX controls . . . . . . . . . . . . . . . . . . . . . . . . 476Specifying local file names for Actuate reports . . . . . . . . . . . . . . . . . . . . . . . . . 476Specifying iServer file names for Actuate reports . . . . . . . . . . . . . . . . . . . . . . . . 476

Actuate ActiveX methods by programming task . . . . . . . . . . . . . . . . . . . . . . . . . . 477Opening and closing a report instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477Navigating and viewing the report instance . . . . . . . . . . . . . . . . . . . . . . . . . . . 478Running a report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 479Printing, mailing, and saving a report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 480Invoking functions in an open report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 480Handling error conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 481

Visual Basic example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 482Building the sample application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 482Visual Basic code segment descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484Running the sample application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 485

Installing Actuate ActiveX controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 486Choosing API files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 488

API file name conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 488API file versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 489

Chapter 26Actuate ActiveX controls reference . . . . . . . . . . . . . . . . . . . . . . . 491AboutBox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 492Back . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 492BackDisable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 492BackEnable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 492BundleReportInstance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493CallBasicFunction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493CancelReport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 494CanRunReport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 494CloseReportExecutable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 495CloseReportInstance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 495ConnectToServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 495CurrentPage. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 496FirstPage. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 496GetLastError . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 496GetMostRecentListCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 497GetMostRecentListItemAt. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 497GetStatusCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 497GetStatusMessageAt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 498GoToPage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 498

xix

LastPage. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 498LoadResource . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 498MailReportInstance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 499NextPage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 499OpenRecentReportInstance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 500OpenReportExecutable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 500OpenReportInstance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 501PageCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 501PreviousPage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 502Print . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 502PrintReport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 502ResetStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 503RunReport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 503RunReportWithParameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 504SaveAsXMLData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 504SearchWindow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 505SetScaleFactor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 505SetWindowLayout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 505TableOfContents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 506

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 507

xx

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

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

xxii P r o g r a m m i n g 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 xxiii

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.

xxiv P r o g r a m m i n g 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 xxv

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:

xxvi P r o g r a m m i n g 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 xxvii

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

xxviii P r o g r a m m i n g 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 xxix

About Programming e.Reports Programming e.Reports provides information about using the Actuate Basic programming language and the Actuate foundation classes to go beyond what you can accomplish with the Actuate e.Report Designer Professional interface.

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

xxx P r o g r a m m i n g e . R e p o r t s

Programming e.Reports 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. Understanding the Actuate Foundation Classes. This chapter explains the architecture of the Actuate foundation class library, and provides an overview of classes by category.

■ Chapter 2. Working with a class. This chapter explains what classes are and how to use them.

■ Chapter 3. Working with an object. This chapter explains what objects are and how to work with them.

■ Chapter 4. Using Component Editor. This chapter describes how to use Component Editor to modify classes.

■ Chapter 5. Understanding document generation. This chapter explains how the Factory builds Actuate reports and document object instance (.doi) files. It also describes the class protocols that determine how objects in a document fit together.

■ Chapter 6. Customizing a report. This chapter shows several examples of customizing reports through code.

■ Chapter 7. Debugging a report. This chapter describes the features of the Actuate debugger.

■ Chapter 8. Designing a report with page-level security. This chapter describes how to create a report design that generates different reports depending on the report user.

■ Chapter 9. Programming for report viewing events. This chapter describes the Viewer events you can control and provides examples.

■ Chapter 10. Using and customizing a stored procedure. This chapter describes how to create and call stored procedures.

■ Chapter 11. Writing custom browser code. This chapter describes how to include custom browser code such as HTML in a report design.

■ Chapter 12. Designing a report for XML data. This chapter describes how to design an XML report.

■ Chapter 13. Understanding report bursting techniques. This chapter describes different ways to implement report bursting.

■ Chapter 14. Introducing Actuate Basic. This chapter provides an overview of the Actuate Basic language, the basic code elements, and coding conventions.

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

■ Chapter 15. Understanding variables and data types. This chapter describes the Actuate Basic data types and how to work with them.

■ Chapter 16. Writing and using a procedure. This chapter describes how to write and call procedures.

■ Chapter 17. Using an object from another application. This chapter describes how to insert and use OLE (Object Linking and Embedding) objects in reports.

■ Chapter 18. Programming an object from another application. This chapter describes how to use OLE Automation to integrate other applications in reports.

■ Chapter 19. Calling an external function. This chapter describes how to use external functions in your report application.

■ Chapter 20. Using Actuate’s application programming interfaces. This chapter describes the features of the Actuate APIs and presents guidelines for choosing among them.

■ Chapter 21. Requester API user guide. This chapter provides a description of the Requester API and a task-oriented description of the interface. Actuate Basic and Visual Basic examples demonstrate how to use the API.

■ Chapter 22. Requester API reference. This chapter provides an alphabetical reference with descriptions and programmatic details for each Requester API method.

■ Chapter 23. Search extension API user guide. This chapter provides a description of the search extension API and a task-oriented description of the interface.

■ Chapter 24. Search extension API reference. This chapter provides an alphabetical reference with descriptions and programmatic details for each search extension API function.

■ Chapter 25. Actuate ActiveX controls user guide. This chapter provides a description of the Actuate Viewer ActiveX control and Actuate Desktop ActiveX Control interface. It explains how to integrate Actuate reporting features into Windows applications. An example shows how to add the Desktop ActiveX control to a Visual Basic application.

■ Chapter 26. Actuate ActiveX controls reference. This chapter provides an alphabetical reference with descriptions and programmatic details for the Actuate Viewer and Desktop ActiveX controls.

xxxii P r o g r a m m i n g e . R e p o r t s

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.

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.

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

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.

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

xxxiv P r o g r a m m i n g e . R e p o r t s

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.

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.

Type the keyword for which to search

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

Choose Search

Report-specific online help

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

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

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

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

Symbol Description Example

[ ] Optional item [Alias<alias name>]

Array subscript matrix[ ]

< > Argument you must supply

<expression to format>

Delimiter in XML <xsd:sequence>

xxxvi P r o g r a m m i n g e . R e p o r t s

{ } 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

Symbol Description Example

P a r t 1 , P r o g r a m m i n g w i t h t h e A c t u a t e F o u n d a t i o n C l a s s e s 1

P a r t

Part 1Programming with theActuate Foundation Classes

2 P r o g r a m m i n g e . R e p o r t s

C h a p t e r 1 , U n d e r s t a n d i n g t h e A c t u a t e F o u n d a t i o n C l a s s e s 3

C h a p t e r

Chapter 1Understanding theActuate Foundation

ClassesThis chapter contains the following topics:

■ About the Actuate Foundation Class architecture

■ Understanding the AFC by functional category

4 P r o g r a m m i n g e . R e p o r t s

About the Actuate Foundation Class architectureThe Actuate Foundation Class (AFC) is an object-oriented architecture that forms the framework on which report developers build additional classes and Actuate reports. You can use the AFC library to build reports that address a wide range of reporting requirements.

A class protocol is the set of methods and the rules governing their use. Since all AFC classes follow a specific class protocol, you can combine them in a variety of ways to address varied reporting requirements. Objects in a report, such as charts, integer controls, and sections, share a core protocol. You build the features that differentiate those classes on top of the core protocol.

Using an Actuate report design product such as e.Report Designer Professional, you can create reports without understanding the class protocols. You must understand the class protocols only if you create custom components that require programming or to change or extend the AFC class architecture.

About abstract base classesThe higher a class is in its class hierarchy, the more general is its protocol. Each successive generation of classes contains increasingly specialized versions of the general protocol.

Abstract base classes define the top level, or core, protocol. These classes are abstract because they provide general rules that subclasses refine. Report developers never instantiate an abstract base class. Many methods in the abstract base classes are empty. These empty methods are defined to enforce a protocol. The subclasses then add the necessary implementation details.

In general, do not derive a class from an abstract class, only from its specialized subclasses. If you derive a class directly from an abstract class, you must add functionality to your derived class. Most often, that functionality already exists in a subclass.

The following illustration shows the AcComponent abstract base class and its subclasses. This illustration provides an overview of the principal report components.

C h a p t e r 1 , U n d e r s t a n d i n g t h e A c t u a t e F o u n d a t i o n C l a s s e s 5

The following table describes these classes.

AcComponent

AcDataRow

AcReportComponent

AcPageList

AcConnection

AcDataAdapter

AcSectionAcDBConnection

AcDataSource AcDataFilter

AcVisualComponent

AcFlow AcControlAcBaseFrame

AcReport

Base class Description

AcComponent Principal base class for all components that appear in the report structure pane. It defines the mechanism for creating objects within container objects.

AcConnection Defines the logic for generic connections.

AcDBConnection Defines the logic for connecting to relational databases. The database connection classes provide native support for the following database: ■ DB2■ Informix■ Microsoft SQL server■ ODBC■ Oracle■ Progress■ SAP■ SybaseFor more information about the classes that support connecting to these databases, see Actuate Foundation Class Reference.

6 P r o g r a m m i n g e . R e p o r t s

About concrete classesA concrete class, also called a leaf class, defines the specific implementations of an abstract base class. You can instantiate a concrete class. You subclass a concrete class to create a class that modifies or extends the functionality of the original class.

AcDataRow Defines the general characteristics of a data row. A data row is a record structure that contains data from a single record in a format that the report accepts.

AcDataAdapter Defines the logic of data-related classes, such as data sources and data filters, that can combine to form a data stream. The data stream manages data collection and processing.

AcDataSource Defines the logic for retrieving data from an external source and creating a data row for each input record.

AcDataFilter Defines the logic for processing data rows retrieved from another data adapter.

AcReportComponent Defines the general structural characteristics of all classes in which a report stores persistent objects.

AcSection Defines the characteristics of all non-visual structural classes. Derived classes represent different ways of grouping data.

AcVisualComponent Defines the characteristics of all visual classes. Derived classes display data or graphical elements.

AcReport The structural class that represents the entire report.

AcFlow Defines the logic for placing frames in a flow.

AcBaseFrame Defines the general characteristics of frames and pages and the logic for instantiating the content in frames and pages.

AcControl Defines the general characteristics of all controls.

AcPageList Defines the logic for building pages and managing displays.

Base class Description

C h a p t e r 1 , U n d e r s t a n d i n g t h e A c t u a t e F o u n d a t i o n C l a s s e s 7

Understanding the AFC by functional categoryThe following functional categories describe the Actuate Foundation Classes:

■ Report object structure classes

■ Connection classes

■ Data stream classes

■ Section classes

■ Page layout classes

■ Control classes

■ Internal tools classes

■ Collection classes

The following sections provide an overview of the Actuate Foundation Classes, their purpose, and their position in the class hierarchy. For detailed information about each class, see Chapter 3, “AFC classes,” in Actuate Foundation Class Reference.

About report object structure classes

Classes in this category form the backbone of a report. They define the general structural characteristics of objects, how to create them, and how they fit together. Typically, you do not derive from these classes. When you create a report in e.Report Designer Professional, you derive a report class from AcReport. The report is the container for all other objects in a report.

AcComponent

AcReportComponent

8 P r o g r a m m i n g e . R e p o r t s

About connection classes

Classes in this category provide communication links for Actuate reports.

About connection abstract base classesAcConnection and AcDBConnection are abstract base classes. Do not derive directly from them.

About connection concrete classesAcInformixConnection, AcDB2Connection, AcMSSQLConnection, AcODBCConnection, AcOracleConnection, AcProgressConnection, AcProgressSQL92Connection, AcSAPConnection, AcSybaseConnection, and AcSybaseDBLibConnection are concrete classes with which you connect to data sources.

AcReportComponent

AcConnection

AcDBConnection

AcDB2Connection

AcInformixConnection

AcMSSQLConnection

AcODBCConnection

AcDBStatement AcDBCursor

AcOracleConnection

AcProgressConnection

AcSybaseConnection

AcProgressSQL92Connection

AcSAPConnection

AcSybaseDBLibConnection

AcSAPConnection

C h a p t e r 1 , U n d e r s t a n d i n g t h e A c t u a t e F o u n d a t i o n C l a s s e s 9

AcDBStatement and AcDBCursor provide the Actuate Basic interface for working with SQL statements and cursors. The AFC framework creates and uses instances of these classes when your report accesses a SQL database.

About data stream classes

Classes in this category get and process data, create data rows, and send data rows to the report.

About data stream abstract base classesAcDataAdapter is an abstract base class. Typically, you do not derive from it. AcDataSource, AcDatabaseSource, and AcDataFilter are base classes you can subclass to create custom data filters and data sources.

AcReportComponent

AcDataRow

AcDataAdapter

AcDataSource

AcDatabaseSource

AcSQLQuerySource

AcDataFilter

AcSingleInputFilter

AcMemoryBuffer

AcRecordBuffer

AcMultipleInputFilter

AcMemoryDataSorter

AcStoredProcedureSource

AcQuerySource

AcTextQuerySource

10 P r o g r a m m i n g e . R e p o r t s

About data stream concrete classesAcMemoryBuffer, AcMemoryDataSorter, AcSingleInputFilter, and AcMultipleInputFilter are data filters. AcSQLQuerySource is a data source that you use to retrieve data from a SQL database.

About report section classes

Classes in this category manage the data from data streams and build report sections and frames that contain the data. Objects of these classes are non-visual objects that form the report’s structure.

About report section abstract base classesAcSection and AcDataSection are abstract base classes. Typically, you do not derive from them.

About report section concrete classesUse AcReportSection, AcGroupSection, AcSequentialSection, AcConditionalSection, and AcParallelReport to organize data in a report.

AcReportComponent

AcSection

AcDataSection

AcReportSection

AcGroupSection

AcSequentialSection

AcConditionalSection

AcParallelSection

C h a p t e r 1 , U n d e r s t a n d i n g t h e A c t u a t e F o u n d a t i o n C l a s s e s 11

About page layout classes

Classes in this category manage the creation and display of report pages.

About page layout abstract base classesAcBaseFrame, AcBasePage, AcDataFrame, AcFlow, and AcPageList are abstract base classes. You typically do not derive from them.

About page layout concrete classesUse AcSubPage and AcPage to design page styles. Use AcTopDownFlow to determine the placement of report objects on the page. The AcSimplePageList,

AcComponent

AcReportComponent

AcVisualComponent

AcBasePage

AcSubPage

AcPage

AcFlow

AcLinearFlow

AcBaseFrame

AcPageList

AcSimplePageList

AcLeftRightPageList

AcTitleBodyPageList

AcDataFrame

AcFrame

AcTopDownFlow

12 P r o g r a m m i n g e . R e p o r t s

AcLeftRightPageList, and AcTitleBodyPageList classes represent specific page designs.

AcFrame is the container for all controls. In a report design, a frame and its contents are typically associated with a data row. For example, if a data row contains name, address, and telephone data, the report design includes a frame that contains three data controls for the data. In e.Report Designer Professional, each time you drag a frame from a palette and drop it in the report design, you instantiate a subclass of AcFrame.

C h a p t e r 1 , U n d e r s t a n d i n g t h e A c t u a t e F o u n d a t i o n C l a s s e s 13

About control classes

Classes in this category include data controls, crosstabs, charts, and static graphical objects.

AcVisualComponent

AcCrosstab

AcLabelControl

AcDataControl

AcTextControl

AcIntegerControl

AcDoubleControl

AcCurrencyControl

AcDateTimeControl

AcLineControl

AcRectangleControl

AcEllipseControl

AcOLEControl

AcOLEContainerControl

AcChart

AcSummaryChart

AcDetailChart

AcHLCChart

AcTextualControl

AcPageNumberControl

AcBrowserScriptingControl

AcControl

AcDynamicTextControl

AcImageControl

14 P r o g r a m m i n g e . R e p o r t s

About control abstract base classesAcControl, AcCrosstab, AcDataControl, AcOleControl, and AcChart are abstract base classes. Derive from these classes only to create custom controls.

About control concrete classesUse the AcTextControl, AcDynamicTextControl, AcIntegerControl, AcDoubleControl, AcCurrencyControl, and AcDateTimeControl controls to display various types of data from a data row. Use AcLabelControl to display static text.

AcImageControl, AcLineControl, AcRectangleControl, and AcEllipseControl are drawing elements that give a report visual interest.

Use AcOleContainerControl to embed or link OLE objects from other applications into a report.

AcSummaryChart, AcDetailChart, and AcHLCChart display data in various standard chart formats.

About internal tool classes

AcReportController provides the search mechanism for hyperlinks and other search operations. AcPopupMenu provides the services for controlling context menus. For more information about hyperlinks, see Chapter 12, “Working with frames and controls,” in Developing Advanced e.Reports.

About collection classes

AcPopupMenu AcReportController AcReportView AcVisitor

AcXMLDataVisitor

AcList

AcSingleList

AcIterator

AcSingleListIterator

AcCollection

AcOrderedCollection

AcObjectArray

AcBTree

C h a p t e r 1 , U n d e r s t a n d i n g t h e A c t u a t e F o u n d a t i o n C l a s s e s 15

Classes in this category define the way Actuate products store objects and access them in a linked list. For example, frames use lists to manage the controls within them. To work with report content in a list, such as controls in a frame or flows on a page, create a collection class and an iterator class to access the contents.

16 P r o g r a m m i n g e . R e p o r t s

C h a p t e r 2 , W o r k i n g w i t h a c l a s s 17

C h a p t e r

Chapter 2Working with a classThis chapter contains the following topics:

■ About classes

■ Declaring a class

■ Understanding class relationships

■ About class variables

■ About methods

18 P r o g r a m m i n g e . R e p o r t s

About classesThis chapter introduces the concepts that report developers use to declare and work with classes. A class is a specification, or template, for creating an object in a report object instance (.roi) file. The report components with which you work in Design Editor, such as report sections, frames, and controls, are classes. A class contains variables and methods that define the attributes and behavior for objects of the class.

Actuate Foundation Classes (AFC) are written in Actuate Basic. Actuate Basic is an object-oriented programming language, although you instantiate a class in Actuate Basic differently from Java or C++. To instantiate a declared class in Actuate Basic, use an object reference variable with a statement or function such as Set, NewInstance, or NewPersistentInstance. An object reference variable allocates memory for an object. You instantiate the object using Actuate Basic code provided by the Actuate Foundation Classes or your own custom code.

In Actuate e.Report Designer Professional, the design interface accomplishes many programming tasks for you. For example, Design Editor generates class declaration code for each component you place in a report design.

For a list of Actuate Foundation Classes, refer to Actuate Foundation Class Reference. For more information about using e.Report Designer Professional, see Developing Advanced e.Reports.

Declaring a classActuate Basic code defines the structure and behavior of the Actuate Foundation Classes. The user interface of e.Report Designer Professional creates the necessary Actuate Basic code for the classes that correspond to components of a report design. To write a custom class for a report design, declare the class with the Class statement and instantiate it as an object using techniques described in “Creating an object,” in Chapter 3, “Working with an object.”

The Class statement uses the following syntax:

Class <subclass name> Subclass Of <superclass name>

[<variable declarations>]

[<nested class declarations>]

[<method declarations>]

End Class

The body of a class declaration consists of the following optional items:

C h a p t e r 2 , W o r k i n g w i t h a c l a s s 19

■ Variable declarations, which declare variables associated with the class

■ Class declarations for classes nested in the current class

■ Method declarations, which consist of procedures and functions associated with the class

The following example shows class declaration code in an Actuate Basic source (.bas) file, which Actuate e.Report Designer Professional generates when you compile a report object design (.rod) file. This example creates ItemFrame as a subclass of AcFrame, declares four variables for the subclass, and defines procedures and functions for the subclass:

Class ItemFrame Subclass Of AcFrame

' Variable declarations

Dim AlternateColor As AcColorDim AlternateLines As IntegerStatic OriginalColor As AcColorStatic RowNumber As Integer

' Class declarations for nested classes

Class ItemCode Subclass Of AcTextControl...

End Class

' Methods

Sub SetProperties( )Super::SetProperties( )AlternateColor = 15527148AlternateLines = 2BackgroundColor = 14408667Size.Height = 12703Size.Width = 400

End Sub

Sub OnStart( )Super::OnStart( )OriginalColor = BackgroundColorRowNumber = RowNumber + 1If RowNumber > AlternateLines * 2 Then

RowNumber = 1End IfIF RowNumber > AlternateLines Then

BackgroundColor = AlternateColorEnd If

End Sub...

End Class

20 P r o g r a m m i n g e . R e p o r t s

This example shows a nested class, ItemCode. For more information about nested classes, see “About scope,” later in this chapter.

Understanding class relationshipsClasses do not exist in isolation. They co-exist to perform a variety of tasks. Understanding class relationships supports:

■ Working with a class, a variable, or a method

■ Naming and referring to a class, a variable, or a method

■ Managing class modifications to avoid unexpected effects in related classes

The following table explains how classes relate to each other:

About inheritanceIn the AFC class hierarchy, inheritance supports a standard interface for report applications. It also supports code reusability. The classes at the top of the hierarchy typically contain empty method declarations or methods with a few lines of general instructions. These methods enforce a protocol for creating a report using Actuate e.Report Designer Professional. A subclass redefines a higher method by adding implementation details. When you derive a class from an Actuate Foundation Class, the subclass inherits the protocol.

For more information about inheritance, see Chapter 2, “Understanding the design process,” in Developing Advanced e.Reports.

Relationship Description

Inheritance When one class derives another, the derived class, or subclass, inherits variables and methods from the base class, or superclass.

Scope Scope defines a relationship in which the declaration of one class is nested within another class declaration. Scope determines the visibility of classes, static variables, and methods and how you refer to those items in code.

Reference A reference supports accessing an object directly from another object. When ObjectA of Class A refers to ObjectB of ClassB in code, ObjectA has access to the public components of ObjectB, such as its methods and variables. A reference is not a subclass or a new instance of another class.

C h a p t e r 2 , W o r k i n g w i t h a c l a s s 21

About scopeScope is the part of an application in which a symbol exists or is visible. A symbol is the name of an item such as a class, a method, a variable, or a constant. Scope determines how you access or reference a class, when to instantiate a class, when to initialize a variable, and so on.

You can declare a class in either global or class scope. A class has global scope if you do not declare it within another class. A class has class scope if you declare it within another class. A class with class scope is called a nested class. For example, a control in a frame usually is a nested class, scoped to the frame that contains the control. You cannot move the base class into the scope of a nested class.

In the following illustration of a report design, SalesDetail is a subclass of AcReport and has global scope, as the Class page of Sales Detail—Component Editor shows. SalesDetailReport is a nested class of SalesDetail and has class scope because it is declared within SalesDetail.

The following code example also shows the scope and inheritance of SalesDetail. In addition, it shows two nested classes, OfficeTitleFrame and CustomerTitleFrame, which are subclasses of AcFrame and have class scope:

Class SalesDetail Subclass Of AcReport...

Class OfficeTitleFrame Subclass Of AcFrame...End Class

Class CustomerTitleFrame Subclass Of AcFrame...

22 P r o g r a m m i n g e . R e p o r t s

End Class

End Class

Understanding class scope naming conventionsUsing the scope-resolution operator (::), you can refer to any name of a class or static variable, even if it is not visible in the current scope, and build a path leading to the innermost scope. For example, the following class names refer to nested classes:

■ CustomerFrame::AddressControl

■ SalesRepFrame::AddressControl

This convention is similar to specifying a path in a URL using a slash (/). This convention uses the following rules:

■ The class names in one scope are independent of class names in another scope. Just as you can have two files with the same name if they are in different directories, you can have two classes with the same name if they are in different scopes.

■ To reference a class in a different scope, use a qualified name. This convention is analogous to accessing a file in a different directory. For example, to write code for CustomerFrame that references AddressControl in SalesRepFrame, use the full name, SalesRepFrame::AddressControl.

■ To reference a class in the same scope, use only the class name. This convention is similar to specifying another file in the current directory. For example, if CustomerFrame contains two nested controls, CustomerNameControl and CustomerAddressControl, use the class name, CustomerAddressControl, to write code for a method in CustomerNameControl that refers to CustomerAddressControl. The qualified name is not necessary because both controls are in the same frame.

About default class scope in a report designIn Actuate Basic, every class introduces its own scope. e.Report Designer Professional supports an unlimited number of nesting levels. Design Editor applies common sense rules to set the scope of classes when you place components in your report design. The rules are:

■ The report, a subclass of AcReport, has global scope.

■ All other classes except controls take the report’s scope.

■ A control takes its container’s scope. A control typically takes the scope of a frame.

C h a p t e r 2 , W o r k i n g w i t h a c l a s s 23

The following illustration shows how e.Report Designer Professional scopes classes in a report design.

The following table summarizes the default scope that Design Editor assigns to classes:

Default scope provides two key benefits:

■ Easy naming conventions. Nesting a control within a frame supports managing control names. Because a control has class scope, it does not require a unique name.

■ Reusability. Nesting a class within the report object supports reusing the class in another report design without a naming conflict. For example, you can place a frame called CustomerFrame in a report design. In the same report, you can use another frame called CustomerFrame from a different report design or a library without changing the name of either frame. e.Report Designer Professional recognizes one frame as <Report1>::CustomerFrame and the other as <Report2>::CustomerFrame.

Type of class Default scope

Report (AcReport) Global

Section Report

Page list Report

Page Report

Flow Report

Connection Report

Data source Report

Data filter Report

Frame Report

Control Frame or page

CustomerFrame scope

CustomerReportApp scopeGlobal scope

CustomerReportApp

CustomerNameControl

CustomerPhoneControl

CustomerSection

CustomerFrame

24 P r o g r a m m i n g e . R e p o r t s

About the default scope of a class in a libraryBecause a class in a library is available for any report design, it has global scope. If you publish a class that has report scope to a library, e.Report Designer Professional changes the scope to global scope.

About class variablesA class variable defines the state and attributes of an object of a class. The scope of a class variable is within the class in which you declare it. The variable type determines how Actuate e.Report Designer Professional stores it. Actuate Basic supports two types of class variables:

■ Instance. As its name suggests, an instance variable applies to a particular instance of a class. There is one copy of the variable in each instance. For example, each object of a text control class has instance variables, such as Position and Size, that define the object’s appearance.

Declare instance variables with the Dim statement, as shown in the following examples:

Dim Position As AcPointDim Size As AcSize

■ Static. When you declare a variable as static, Actuate Basic maintains only one copy of the variable for all instances of the class and its subclasses. A static variable is like a global variable, except that its scope is within a class. Use a static variable if all instances must share the same data, such as when you create a counter to track the number of times report designers instantiate a particular class.

Declare a static variable with the Static statement, as shown in the following examples:

Static InstanceCount As IntegerStatic RowNumber As Integer

About variables in Component EditorActuate Basic declares instance and static class variables. Component Editor supports specifying additional variables by their usage and visibility.

C h a p t e r 2 , W o r k i n g w i t h a c l a s s 25

The following table describes these types of variables by function.

About visibility of variables in Component EditorAssign either Private or Public visibility to a variable to indicate whether it appears only on the Variables page of the class where you declare it or on the Variables page of subclasses as well.

When you assign Essential Property or Property, the variable appears on the Properties page of Component Editor. If the variable is EssentialProperty, Component Properties prompts for a value when the report designer places

Component Editor supports three types of variables

Functional type Description

Property Defines the attributes for objects of the class. For example, a control has property variables such as BackgroundColor, Font, Size, and Position that define its appearance. You supply initial values for property variables at design time. Only instance variables can be properties.

Parameter Stores values the end user supplies when a report runs to specify the data to include in the report. Requester or the Request web page prompts for these values before report generation begins. Parameters are static variables.

Regular Stores values that e.Report Designer Professional uses to generate a report. For example, the PageNumber variable of any subclass of AcPage stores the current page number, which e.Report Designer Professional updates continuously as it generates the report. This variable ensures that each page displays the correct page number.

26 P r o g r a m m i n g e . R e p o r t s

the component in a report design. The following table shows variable visibility types.

The assignment of Private or Public to variables affects only what you see on the Variables page. Actuate Basic does not differentiate between private and public variables. Whether you specify a variable as private or public, you access it the same way in Actuate Basic code. In other words, using code, a private variable is available to the class and its subclasses.

Using property variablesProperties are the most visible elements of a component because you can see and assign values to them when you design a report. They appear in the Properties page of Component Editor. Many of the variables declared in Actuate Foundation Classes are properties.

You can create your own property variables using the Variables page of Component Editor. For information about creating a variable, see “Creating a class variable” in Chapter 4, “Using Component Editor.”

The following illustrations show property variables as they appear in Component Editor and in code that Actuate e.Report Designer Professional generates when you set properties.

Visibility type Description

Essential Property

Variable is a property that appears in the Properties page of Component Editor. e.Report Designer Professional prompts for a value when you place a component of this type in the report design. EssentialProperty applies only to instance variables.

Private Variable appears in the Variables page of the class in which it is declared. Specify a variable as private if you intend to use the variable only in the class where it is declared and do not want to clutter the Variables page of the subclasses.

Property Variable is a property that appears in the Properties page of Component Editor. Property applies only to instance variables.

Public Variable appears in the Variables page of the class and its subclasses. Specify a variable as public if you intend to use the variable in the class and its subclasses.

Parameter Variable is a parameter that appears in the Properties page of Component Editor. e.Report Designer Professional prompts for a value when the end user runs the report. Parameter applies only to static variables.

C h a p t e r 2 , W o r k i n g w i t h a c l a s s 27

Variable name and data type

The Font variable is an instance variable defined as a property

Property variables appear on the Properties page of Component Editor

SetProperties( ) sets values in code

Sub SetProperties( )Super::SetProperties( )Font.Size = 22Font.FaceName = "Arial"...

End Sub

28 P r o g r a m m i n g e . R e p o r t s

The properties of a subclass reflect property changes you make to the superclass.

Using parametersSpecify a variable as a parameter to gather values when the report runs. Reports typically use parameters to filter the data to retrieve and display. For example, a query can specify that the data stream retrieve all customer records from a Customer table. Parameters support specifying additional filter conditions when the user runs the report, such as retrieving only records for customers in California or only records in a specific date range.

You can also create parameters to set properties such as the font and color of objects when the user runs the report. Variables that you specify as parameters appear in Requester and the Request web page when the user runs the report.

The following illustrations show parameter variables in Component Editor and in Requester:

Parameter variables appear on the Variables page of Component Editor

C h a p t e r 2 , W o r k i n g w i t h a c l a s s 29

For more information about parameters and how to create them, see Chapter 18, “Designing a report parameter,” in Developing Advanced e.Reports.

Using regular variablesA common use for a regular variable is to store values that e.Report Designer Professional needs when generating a report. For example, a frame uses the Container variable to store a reference to its container object. You typically create regular variables to store values that your methods need. For example, if you write a method that sets alternating rows to different colors, you can use a variable to store the current row number.

When the user runs a report, Requester prompts for parameters

30 P r o g r a m m i n g e . R e p o r t s

About methodsMethods are procedures defined within class declarations. They specify the actions an object performs. Most of the predefined methods in the Actuate Foundation Classes support generating a report. You can create new methods to add functionality to a class. Also, if the functionality you require is an extension or a version of an existing method, you can override the method.

For information about creating and overriding methods, see Chapter 4, “Using Component Editor.”

Using methodsThere are three categories of predefined methods in the Actuate Foundation Classes:

■ Methods you can override

■ Methods you can call

■ Private methods the AFC framework calls

For a complete list of AFC methods and an explanation of whether they are callable, overridable, or private, refer to Chapter 1, “The Actuate Foundation Class library,” in Actuate Foundation Class Reference.

It is possible to override a private or callable method but doing so is not advisable. Overriding a private or callable method can adversely impact the report generation process.

Actuate Foundation Class Reference explains what the methods do and how you typically use them. In addition, Method Editor and the Methods page of Component Editor provide a filter that supports viewing methods in these usage categories. The following illustration shows the filtering options.

C h a p t e r 2 , W o r k i n g w i t h a c l a s s 31

About methods you can overrideThe methods designated as overridable support customizing parts of the report generation or report viewing process. For example, methods that have an On prefix support adding code that executes when an event occurs. The methods that are part of a class protocol, such as Start( ), Build( ), Fetch( ), Finish( ), are also overridable.

About methods you can callCallable methods typically provide a defined service or information about an object. For example, a data adapter class provides methods such as SeekTo( ), SeekBy( ), SeekToEnd( ), and Rewind( ) that you can call to access data. Report component classes provide methods such as IsContainer( ), IsLeaf( ), IsVisual( ) and HasContents( ) that you can call to get information about an object. Page list classes define methods such as GetPageCount( ), GetContents, GetCurrentPage( ), and GetFirstPage( ) that you can call to get a value your code requires.

You can, but typically do not, override these methods. If you cannot find a predefined method for a task, create a new method.

Display only overridden and locally defined methods

Methods page displays methods according to the filter option you select

Display all methods

Display local methods and methods you can override and call

Display local and overridable methods

Display the most commonly used local and overridable methods

32 P r o g r a m m i n g e . R e p o r t s

About private methodsThe AFC framework calls private methods to perform internal tasks. Some of these methods call C functions. Overriding private methods is not advisable for two reasons:

■ To work with a private method, you must understand internal implementation details.

■ Actuate Corporation does not guarantee that private methods work the same way in future releases as they do in the current release.

Overloading a methodOverloading is the practice of supplying more than one definition for a given method name in the same scope. In other words, Actuate Basic supports multiple methods with the same name in a single class. You must define different argument lists for the methods, however. In the following example, Sum( ) is an overloaded method:

Function Sum( num1 As Integer, num2 As Integer ) As IntegerFunction Sum( num1 As Double, num2 As Double) As DoubleFunction Sum( num1 As Integer, num2 As Integer, num3 As Integer ) As Integer

The compiler selects the appropriate version of the method based on the arguments with which it is called. You typically create an overloaded method to create a method that accomplishes a particular task but which accepts different arguments.

C h a p t e r 3 , W o r k i n g w i t h a n o b j e c t 33

C h a p t e r

Chapter 3Working with an objectThis chapter contains the following topics:

■ About objects

■ Creating an object

■ Using an object reference variable

■ About object lifetime

34 P r o g r a m m i n g e . R e p o r t s

About objectsAn object is an instance of a class. Everything in a report object instance (.roi) file is an object, including frames, controls, and report sections. Using Component Editor, you set the properties of an object when you design each component’s class in a report design. Sometimes, however, you must modify an object’s properties for a specific report. For example, you can display negative numbers in red and positive numbers in black. To do so, you declare and use variables that reference objects. These variables are called object reference variables. An object reference variable refers to an object that can have different property values from the original class definition.

This chapter describes how to create an object and use an object reference variable. For more information about variables in Actuate Basic, see Chapter 15, “Understanding variables and data types.”

Creating an objectThere are two steps to creating an object:

1 Declare an object reference variable that refers to a class.

2 Take one of the following steps:■ Create the object using the New or New Persistent keyword.■ Access an existing object by calling a function that returns an object of

the appropriate class.

The following sections describe these steps in greater detail.

Declaring an object reference variableYou declare an object reference variable the same way you declare other variables, using:

■ Dim

■ ReDim

■ Static

■ Global

The only difference is that you assign a class or the AnyClass type as the type of the variable, as shown in the following syntax:

{Dim | ReDim | Static | Global} <variable name> As {<class> | AnyClass}

C h a p t e r 3 , W o r k i n g w i t h a n o b j e c t 35

For more information about Dim, ReDim, Static, and Global, see Chapter 2, “Statements and functions,” in Actuate Basic Language Reference.

The following sections describe how to use <class> and AnyClass.

Declaring an object reference variable as a specific classYou typically declare an object reference variable as a specific class. You can specify an Actuate Foundation Class, a subclass of a foundation class, or a custom class. Actuate Basic recognizes an item as a class if you declare it with the Class statement. For information about class declarations, see “Declaring a class,” in Chapter 2, “Working with a class.”

For example, to create an object reference variable of type AcLabelControl, an Actuate Foundation Class, use a declaration similar to the following statement. This object reference variable can refer to any AcLabelControl object or any object of a class that is a subclass of AcLabelControl:

Dim MyLabelControl As AcLabelControl

For a list of classes in the Actuate Foundation Class library, see Chapter 3, “AFC classes,” in Actuate Foundation Class Reference. For a list of classes available to a report, take the following steps:

1 In e.Report Designer Professional, choose View➛Globals Browser.

Globals Browser appears.

2 Right-click in the white space of Globals Browser. Choose Options.

Browser Options appears.

3 Select AFC Symbols and Inherited Symbols. Choose OK.

36 P r o g r a m m i n g e . R e p o r t s

Globals Browser displays the Actuate Foundation Classes available to the report.

Declaring an object reference variable as AnyClass typeIf you need an object reference variable to refer to an object but you do not know the class of the object, declare the object reference variable as AnyClass:

Dim handle As AnyClass

Creating an object using New Declaring an object reference variable does not create the object. The object does not exist in memory until you instantiate the class. To create the object, use the New keyword with Set.

The following syntax shows the syntax for creating objects:

Set <variable name> = New [Persistent] <class> [(<argument list>)]

Set...New creates a new object of <class> and stores the reference to the object in <variable name>. The following example creates a label object and stores the reference to the label in the MyLabelControl object reference variable:

Set MyLabelControl = New AcLabelControl

C h a p t e r 3 , W o r k i n g w i t h a n o b j e c t 37

Use Set...New Persistent to keep the object until the user deletes the report. When e.Report Designer Professional generates the report objects that users view and interact with, it creates persistent objects by default. For more information, see “About persistent objects,” later in this chapter.

For more information about the Set statement, see Chapter 2, “Statements and functions,” in Actuate Basic Language Reference.

Using an object reference variableOnce you create an object or obtain the handle to an existing object, you can work with it using an object reference variable. You can call the object’s methods or access the object’s member variables. You can also work with the object reference variable itself. You can pass an object reference variable to a procedure, make the variable refer to another object, compare an object reference variable, and test it. The following sections describe how to perform these tasks.

When working with objects, it is important to understand the difference between a simple variable, such as an integer or string variable, and an object reference variable. When you use a simple variable, you manipulate a value directly. If you assign the value of one simple variable to another, you copy the value. Subsequent changes to the original variable do not affect the copy. When you use an object reference variable, a change to the original object is visible in all references to the object.

Working with a simple variableA simple variable contains values. For example, a string variable contains a character string, and a numeric variable contains a number.

When you assign one variable (Number1) to another (Number2), you copy the contents of Number1 to Number2. Subsequent changes to the contents of Number1 have no effect on Number2, as the following example demonstrates:

Dim Number1, Number2 As IntegerNumber1 = 7Number2 = Number1 'Number2 contains the value 7Number1 = 77Print Number1 'Prints 77 Print Number2 'Prints 7

The following illustration shows the result of the preceding code:

Number1 Number2

7 77

38 P r o g r a m m i n g e . R e p o r t s

Working with an object reference variableAn object reference variable also contains a value. The value of an object reference variable is the reference to, or address of, an object. The object reference variable does not contain the object itself.

You can assign a object reference variable to an object or to another object reference variable. When you assign one object reference variable to another, you do not copy the object. Instead, you create a second reference to the same object.

The following code creates a label and sets its text property. The object reference variable LabelControl1 refers to the label:

' Declare an object reference variableDim LabelControl1 As AcLabelControl' Create the objectSet LabelControl1 = New AcLabelControl' Set the Text property of the labelLabelControl1.Text = "Annual Sales Report"

The following illustration shows the result of the preceding code:

The following code assigns another object reference variable, LabelControl2, to the first object reference variable, LabelControl1:

Dim LabelControl2 As AcLabelControlSet LabelControl2 = LabelControl1LabelControl2.Text = "Monthly Sales Report"

Print LabelControl2.Text 'Prints "Monthly Sales Report"Print LabelControl1.Text 'Prints "Monthly Sales Report"

The following illustration shows the result of the preceding code:

LabelControl1

Object reference variable

.

.

Text

.Annual Sales Report

Object

LabelControl1

Object reference variables

.

.

Text

.Monthly Sales Report

Object

LabelControl2

C h a p t e r 3 , W o r k i n g w i t h a n o b j e c t 39

These examples demonstrate two points about object reference variables:

■ More than one object reference variable can refer to the same object.

■ When you change an object’s properties, the change is visible in all references to the object.

Referencing an object’s variables and methodsTo change, store, or retrieve an object’s values, you reference its instance variables and methods using dot notation:

<object reference variable>.<variable>

<object reference variable>.<method>

The dot tells Actuate Basic to access an instance variable or method in an object.

For example, to refer to a variable or method in a label control, specify the object reference variable, followed by a dot, followed by the variable or method name;

MyLabel.BackgroundColorMyLabel.Build( )

To change the characteristic of the label, assign a value to one of its variables:

MyLabel.BackgroundColor = Yellow

Object reference variable

Object

BackgroundColor

Start( )

Build( )

BorderStyle

myLabel

...

40 P r o g r a m m i n g e . R e p o r t s

If an object contains an object reference variable that points to another object, as shown in the following illustration, you can use dot notation to build a path of references.

In this case, you can build the following path:

myLabel.Container.CanMoveUp

Referencing a method of a classYou typically reference an object’s methods to execute a task on the object. Sometimes, however, you must reference a method defined in a superclass. For example, if you override a method but must still perform its original task, you can call the method in the superclass.

Referencing a method in a superclassTo call a method in a superclass, use one of the following statements:

Super::<method>

or

<class name>::<method>

When you use Super to access a method from another class, e.Report Designer Professional searches from the superclass of the current class and continues up the hierarchy until it finds the method. You typically use Super to augment the functionality of an overridden method. Call Super to execute the original code and the code you add.

Using Super has the following advantages:

■ Because you do not hard code a class name, your code is more reusable.

■ You do not have to know the name of the superclass.

Using a class nameYou can specify the class containing the method you want to call. Actuate products search only that class. Specify a class name if you modified the

Object reference variable

ObjectA

Object reference var:

Container

BackgroundColor

BorderStylemyLabel

...

CanMoveUp

Position

Build( )

...

ObjectB

C h a p t e r 3 , W o r k i n g w i t h a n o b j e c t 41

method in each successively derived class and you must call a specific version, as described in the following example.

In a hierarchy of classes, ClassC derives from ClassB and ClassB derives from ClassA. Each class has its own version of the Build( ) method. To write code for MyLabel, a subclass of ClassC, and use ClassA’s Build( ) method, use the following statement:

MyLabel.ClassA::Build

If you do not specify ClassA, and write MyLabel.Build instead, the method from MyLabel executes. If MyLabel’s Build( ) method does not contain overridden code, the Build( ) method calls Super::Build( ), which is the Build( ) method of Class C.

Resolving an ambiguous method callInheritance can result in two methods with the same name that execute different tasks because they are in different scopes. When a report contains duplicate method names and you do not qualify the method name when you call the method, e.Report Designer Professional resolves ambiguous method calls by searching within the current instance first, then within the global scope.

In the following code examples, DerivedClass derives from BaseClass. BaseClass defines methods X and Y. DerivedClass defines its own version of method Y. When you call Y( ) from X( ) within MyObject, an instance of DerivedClass, e.Report Designer Professional calls the DerivedClass version of Y( ):

Class BaseClass...Sub X

Y( )...

End Sub...Sub Y

BeepEnd Sub...

End Class

Class DerivedClass Subclass of BaseClass

'DerivedClass inherits method X and redefines method Y...Sub Y

Super::Y

42 P r o g r a m m i n g e . R e p o r t s

MsgBox "This operation is invalid"End Sub

End Class..Dim MyObject As DerivedClassSet MyObject = New DerivedClass

X( ) 'X( ) calls DerivedClass’ version of Y( )

MyObject.Y 'Refers to Y( ) in DerivedClassMyObject.BaseClass::Y 'Refers explicitly to Y( ) in BaseClass

Assigning an object to an object reference variableUse Set to assign an object reference variable to an object, as shown in the following syntax:

Set <object reference variable> = <object expression>

You can assign an object to an object reference variable if the object is of the same type as the object reference variable, or if the object is of a type that derives from the type of the object reference variable. You cannot assign an object to an object reference variable of an unrelated class or a parent class. For example, you cannot assign a report object to a control object reference variable.

In the following example, you can assign Control1 to Control2 because you declare both variables as AcControl:

Dim Control1 As AcControlDim Control2 As AcControl

Set Control1 = New AcControlSet Control2 = Control1

In the following example, although you declare Control1 and Control2 as different types, you can assign Control1 to Control2 because AcTextControl derives from class AcControl:

Dim Control1 As AcTextControlDim Control2 As AcControl

Set Control1 = New AcTextControlSet Control2 = Control1

The following example results in a run-time error because AcControl does not derive from AcTextControl:

C h a p t e r 3 , W o r k i n g w i t h a n o b j e c t 43

Dim Control1 As AcTextControlDim Control2 As AcControl

SetControl2 = New AcControlSetControl1 = Control2 'Runtime error—Illegal handle conversion

Comparing Set and LetYou typically use Set to assign one object reference variable to another. Let, which takes the form x = y, typically assigns one simple variable to another. Because object reference variables do not contain actual values, using Let, as shown in the following example, results in an error:

Dim x As AcLabelControlDim y As AcLabelControl

Set x = New AcLabelControly = x 'Compile time error—Invalid assignment

Setting an object reference variable to NothingWhen an object reference variable does not refer to any object, it has the special value Nothing. This value has a similar purpose as the special value Null has for a simple variable. An object reference variable cannot hold the value Null.

When you declare an object reference variable, it is set to Nothing initially. You can assign Nothing to any object reference variable using Set, as shown in the following example:

Set MyControl = Nothing

Passing an object reference to a procedureAs with other variables, you can pass an object reference to a procedure as a parameter and return it as a return value. The following examples show when to pass an object reference to a procedure as a parameter.

The procedure in the following example receives a reference to an object, AnyControl, as a parameter and sizes it:

Sub SizeObject(AnyControl As AcControl)AnyControl.Size.Width = 5000 'TwipsAnyControl.Size.Height = 1000 'Twips

End Sub

The function in the following example creates a label and returns a reference to it:

Function NewLabel( ) As MyLabelControlSet NewLabel = New MyLabelControl

End Function

44 P r o g r a m m i n g e . R e p o r t s

Getting information about an objectActuate Basic provides the following three functions for getting information about an object:

For more information about these functions, see Chapter 2, “Statements and functions,” in Actuate Basic Language Reference.

Testing an object reference with the Is operatorUse the Is operator to perform the following tasks:

■ Test whether an object reference variable is empty (Is Nothing).

■ Compare two object reference variables.

Testing for NothingUse Is with Nothing to see if an object reference variable is empty.

The procedure in the following example displays different messages depending on whether an object reference variable is empty:

Sub TestContent( element As AcVisualComponent)If element Is Nothing Then

MsgBox "The object reference variable is empty"Else

MsgBox "The object reference variable is set"End If

End Sub

Function Description

GetClassID Returns the unique number that e.Report Designer Professional automatically assigns to all objects. Objects of the same class have the same ID number. Use GetClassID to see whether two objects are of the same class without the overhead of a string compare.

GetClassName Returns the name of the object’s class. Use GetClassName when you must know an object’s class before performing an action.

IsKindOf Tests whether an object is of a specified class or is derived from a specified class. Returns True if the object is an instance of the specified class or is an instance of a subclass of the specified class. Otherwise, this function returns False. Use IsKindOf to test whether an object is of a particular class before performing an action.

C h a p t e r 3 , W o r k i n g w i t h a n o b j e c t 45

Comparing object reference variablesUse Is to compare two object reference variables and determine whether they both refer to the same object. The function in the following example compares controls in a linked list and determines whether they are in a given frame:

Function IsInFrame (frame As AcFrame, control As AcControl) As BooleanDim element As AcVisualComponentDim iter As AcListIteratorSet iter = frame.ContentList.NewIterator( )Do While iter.HasMore( )

Set element = iter.GetNext( )If element Is Control Then

IsInFrame = TrueExit Function

End IfLoopIsInFrame = False

End Function

About object lifetimeThe lifetime of an object depends on whether the object is transient or persistent. The following sections describe transient and persistent objects.

About transient objectsSome of the objects in a report are transient, or temporary. e.Report Designer Professional creates them to perform specialized tasks during report generation and releases them from memory once those tasks finish. Examples of transient objects include data streams and connections.

e.Report Designer Professional automatically releases a transient object from memory when the last reference variable that refers to it is destroyed or is set to reference another object. e.Report Designer Professional keeps track of the reference count. The reference count increases each time a new object reference variable refers to the object. The reference count decreases each time an object reference variable is:

■ Set to Nothing

■ Set to reference another variable

■ Destroyed because it is out of scope or because it is a variable of an object that is destroyed

When the reference count is zero, e.Report Designer Professional deletes the object.

46 P r o g r a m m i n g e . R e p o r t s

About persistent objectsMany of the objects that e.Report Designer Professional creates are persistent. They exist until you delete the report file. All objects that appear in the report at view time are persistent, including data controls, graphical elements, sections, and page layout components. Because the report object instance (.roi) file saves the report data and structure, users can view the report at any time.

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

C h a p t e r

Chapter 4Using Component EditorThis chapter contains the following topics:

■ About Component Editor

■ Getting information about a class

■ Working with a class variable

■ Overriding an inherited method

■ Working with a user-defined method

48 P r o g r a m m i n g e . R e p o r t s

About Component EditorUse Component Editor to accomplish any of the following tasks:

■ Getting information about a class

■ Viewing and setting property values

■ Creating a class variable

■ Editing a variable

■ Creating a method

■ Editing a method

Getting information about a classComponent Editor organizes information in a way that makes it easy to learn about a specific class. As the following illustration shows, Component Editor consists of four pages. Three of the pages correspond to the items that make up a component. The fourth page displays general information about the class that defines the component.

Displays properties Displays methods

Displays variables

Displays general information about the component

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

To inspect a class using Component Editor, use one of the following techniques:

■ In any view that displays the class, double-click the class.

■ Select the class and choose View➛Component Properties.

Viewing general information about a classTo view general information about a class, choose Class in Component Editor. Class identifies the class name, the class from which the selected class derives, the class scope, the module in which the class resides, and comments or a description from a programmer.

A check box labeled Private controls whether a class remains private, which means that the class does not appear in the library view. By default, a class is public. The Private check box applies only to classes with global scope.

Scope of class.

File where component resides if the component is in a library.

Component’s superclass. This component is derived from AcDoubleControl.

Private check box. If checked, the class does not appear in the library view.

50 P r o g r a m m i n g e . R e p o r t s

Inspecting a variable To see the variables of a class, choose Variables in Component Editor. By default, Variables displays all public, inherited, and locally-declared variables in the three usage categories: regular, property, and parameter variables. Use the filter option to display a smaller set of variables.

Use the filter option in Variables to display a set of variables. The following illustration shows default filter settings.

An inherited variable appears in grey.

Specifies the types of variables to display.

Displays information about a selected variable. Appears as Edit and supports editing class variables not inherited from a superclass.

A variable declared in the class appears in black.

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

For information about the different types of variables, see “About class variables,” in Chapter 2, “Working with a class.”

Viewing and setting property valuesTo view the properties of a class, choose Properties in Component Editor. You set the values of properties at design time. For information about how to set properties, see Chapter 4, “Using Design Editor,” in Developing Advanced e.Reports.

Inspecting a methodTo view the methods of a class, choose Methods in Component Editor. By default, Methods displays inherited and locally-declared overridable methods. You can use the filter option to specify a different set of methods to display.

A method declared in the class or an overridden method appears in black

An inherited method appears in grey

Specifies the types of methods to display

Displays information about a selected method

52 P r o g r a m m i n g e . R e p o r t s

Use the filter option in Methods to choose a set of methods to display. The following illustration shows filter options you can specify.

For information about how e.Report Designer Professional classifies methods in the overridable, callable, and private categories, see “Using methods,” in Chapter 2, “Working with a class.”

Working with a class variableYou can create three types of class variables: property, parameter, and regular. Property variables store values that developers supply at design time to modify the attributes of an object. Parameter variables store values that users supply when they run a report. Regular variables typically store values that a method requires.

For more information about variables, see “About class variables,” in Chapter 2, “Working with a class.”

Methods page displays methods according to the filter option you select

Display all methods, including those you normally do not override or call

Display local methods and methods you can override and call

Display local and overridable methods

Display only overridden and locally defined methods

Display inherited methods you can call, but not override

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

Creating a class variableTo create a variable, use the Variables page of Component Editor.

How to add a variable to a class

1 In any of the views that display classes, double-click the class to which you want to add a new variable.

Component Editor appears.

2 Choose Variables.

3 Choose New.

Class Variable appears.

4 Type the variable name. You can also type the name of an array, such as MyArray(10) or MultiArray(1 To 3, 1 To 3, 1 To 3).

5 Select the variable data type.

You can use any of the following data types:■ An Actuate Basic data type, such as integer, Boolean, double, or string,

or a data type you define.

For a list of Actuate Basic data types, see Appendix A, “Actuate Basic data types,” in Actuate Basic Language Reference.

■ An Actuate Foundation Class data type, such as AcColor or AcFont.

For a list of the Actuate Foundation Class data types, see Chapter 2, “AFC data types,” in Actuate Foundation Class Reference.

■ The name of any declared class.

For a list of all classes and methods in the Actuate Foundation Class library, see Chapter 3, “AFC classes,” in Actuate Foundation Class Reference.

1. Enter the variable or array name

2. Select the data type

3. Select Instance, Static, or Externally Defined Data Type

4. Select visibility of the variable

54 P r o g r a m m i n g e . R e p o r t s

For a list of classes available to your report:

1 In e.Report Designer Professional, choose View➛Globals Browser.

Globals Browser appears.

2 Right-click in the white space of Globals Browser. Choose Options.

Browser Options appears.

3 Select AFC Symbols and Inherited Symbols. Choose OK.

Globals Browser displays the Actuate Foundation Classes available to the report.

6 If you defined this data type, select Externally Defined Data Type.

7 Select either Instance or Static.

An instance variable applies to a particular instance of the class. A static variable is the same for all instances of the class and its subclasses.

8 Select the visibility or usage of the variable.

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

The options differ depending on whether you select Instance or Static in step 7. The following table describes the options.

9 Choose OK.

The variable appears in Variables. If you selected Property or Essential Property for an instance variable, it also appears in Properties.

Editing a variableYou can edit only a variable scoped to a class. You cannot edit an inherited variable.

To edit a class variable:

1 In any of the views that display a class, double-click the class that contains the variable to edit.

Component Editor appears.

2 Choose Variables.

3 Select the variable to edit. Choose Edit.

Class Variable appears.

4 Modify the variable and choose OK.

Visibility option Description Applies to

Essential Property

Variable appears in Properties. e.Report Designer Professional prompts the report developer to supply a value at design time.

Instance variable

Parameter Variable appears in Requester when a user runs the report. The user can type or select a value to set additional run-specific filter conditions.

Static variable

Private Variable appears in the Variables page of the class in which it is declared.

Instance and static variables

Property Variable appears in Properties. The report developer can supply a value at design time.

Instance variable

Public Variable appears in the Variables page of the class and its subclasses.

Instance and static variables

56 P r o g r a m m i n g e . R e p o r t s

To revert a variable to its previous definition, immediately after making a change, choose Edit➛Undo.

Deleting a variable You can delete only a variable scoped to a class. You cannot delete an inherited variable.

To delete a class variable:

1 In any of the views that display a class, double-click the class that contains the variable you want to delete.

2 Choose Variables.

3 Select the variable you want to delete. Choose Delete.

To recover a variable immediately after you delete it, choose Edit➛Undo.

Overriding an inherited methodYou typically override an inherited method to extend or replace its functionality. Because most of the predefined methods in the Actuate Foundation Classes perform specific operations in the report-generation process, you must be careful when overriding these methods. You must understand how they are implemented and how they interact with other methods.

When you override a method, the changes apply only to the selected class.

Overriding a methodUse the following guidelines to prepare to override a method:

■ Understand how the method works and the context in which it runs. You must answer the following questions:■ What does the method do? ■ What occurs before and after the user calls the method?■ What are the rules for calling the super class method?■ What value must the method return, if any?

For information that provides answers to these questions, see Actuate Foundation Class Reference.

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

■ Decide whether you are replacing or extending the inherited method.■ To extend the code, you must call the original method in the superclass,

as the following code example shows:

Function Start( ) As BooleanStart = Super::Start( )

' Your new code

End Function

Depending on the method and what you want to accomplish, you can call the superclass method before, between, or after your code.

■ To replace the code, do not call the method in the ancestor class. You must ensure that the replacement code performs all the necessary tasks that the original method performs. For information about how a method implements in Actuate Basic, refer to Actuate Foundation Class Reference.

How to override a method

1 In any view that displays a class, double-click the class containing the method you want to override.

Component Editor appears.

2 Choose Methods.

3 Select the method to override.

4 Choose Override.

Method Editor appears.

5 Add code to the method, following the rules for writing procedures.

To retain and augment the method’s default behavior, keep the Super statement. To replace the method’s default behavior, remove the Super statement.

Working with a user-defined methodYou create a new method for a component to add functionality to a component. If the functionality to add is an extension of an existing method, consider overriding the method instead.

For information about overriding methods, see “Overriding a method” later in this chapter.

58 P r o g r a m m i n g e . R e p o r t s

Creating a methodThere are no restrictions on what you can do with the methods of a component. Methods can significantly affect the behavior of objects. Design, code, and test methods carefully.

Use the following guidelines to create a new method:

■ Confirm that creating a method is a better choice than overriding an existing method.

■ Minimize conditions you impose on other programmers who use the component. For example, be aware of the complexities that arise from creating the following kinds of methods:■ Methods a user must call to use the component■ Methods that must execute in a strict order■ Methods that put the component into a state that could invalidate

another method or event

If you cannot avoid such conditions, write code that manages incorrect use of your methods. For example, if calling a method puts the component into a state that renders another method invalid, program the other method to test the state before executing its main code. At a minimum, display a warning message and a cancellation option if an error occurs. Use the Description field on the Class page of Component Editor to describe any special requirements or preconditions.

How to create a new method

1 In any view that displays a class, double-click the class to which to add a new method.

Component Editor appears.

2 Choose Methods.

3 Choose New.

Add Method appears.

4 Type a name for the method.

For guidelines on naming a method, see “Naming a method,” later in this chapter.

Specify the method name

Specify the method’s return type, if needed

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

5 Specify a return data type for the method, if necessary.

6 Choose OK.

Method Editor appears, displaying the method declaration.

7 Write code for the method. Follow the same rules for writing regular procedures.

8 To save the method, choose Update or Close.

The method saves when you select another method, choose a different page in Component Editor, or select another component in the report design.

Naming a methode.Report Designer Professional imposes no restrictions on what you name a method, other than those imposed by Actuate Basic. You can use duplicate method names within a report if the methods are in different scopes or if they have different argument lists.

For more information about class scope and overloaded methods, see “About scope,” and “Overloading a method,” in Chapter 2, “Working with a class.”

Use the following guidelines to name a method:

■ Begin a method name with a verb.

For example, GetHorizontalPosition is clearer than XPosition, which sounds like a property.

60 P r o g r a m m i n g e . R e p o r t s

■ Use unambiguous descriptive names that reflect the method’s purpose.

For example, a name such as ReadDataRow is more informative than DoDataRow.

Editing a methodYou can edit only a method you create or that is overridden. You cannot edit an inherited method.

How to edit a method you create or override

1 In any of the views that display a class, double-click the class containing the method to edit.

Component Editor appears.

2 Choose Methods.

Methods displays inherited and locally-defined methods.

3 To simplify your search, use the filter options:

1 Choose Filter.

Method Filtering appears.

2 Select Include most commonly used methods. Choose OK.

Methods displays a list of common methods.

4 Select the method to edit. Choose Edit.

Method Editor appears.

5 Insert your code, following the rules for procedure writing.

6 Choose Update or Close.

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

Deleting a methodYou can delete only a method you create or one that is overridden. You cannot delete an inherited method.

How to delete a method you create

1 In a view that displays a class, double-click the class containing the method to delete.

Component Editor appears.

2 Choose Methods.

Methods displays inherited and locally-defined methods.

3 To simplify the search, use the filter options to display only methods defined and redefined in the class:

1 Choose Filter.

Method Filtering appears.

2 Select Only local methods. Choose OK.

Only methods redefined or defined in the class appear in Methods.

4 Select the method you want to delete. Choose Delete.

To recover a method immediately after deleting it, choose Edit➛Undo. This command works only if you do not perform another task after deleting the method.

62 P r o g r a m m i n g e . R e p o r t s

C h a p t e r 5 , U n d e r s t a n d i n g d o c u m e n t g e n e r a t i o n 63

C h a p t e r

Chapter 5Understanding documentgeneration

This chapter contains the following topics:

■ Overview of the Factory service

■ Starting the Factory service

■ Creating content

■ Creating a page

■ Instantiating a class

■ Working with a data stream

■ Connecting to a database

64 P r o g r a m m i n g e . R e p o r t s

Overview of the Factory serviceThe Factory service manages document generation and printing operations. The Factory service generates a document according to choices a user makes in Design Editor. This service runs an executable file and creates either a report object instance (.roi) file or a data object instance (.doi) file. iServer then creates the document file in DHTML. You view the output using a web browser or the Viewer of a product such as Actuate Active Portal or e.Report Designer Professional.

The following illustration shows the document generation operations that occur during the document-building process.

The ROI and DOI files consist of persistent objects. The Factory service deletes all transient objects, such as data sources, data filters, and data rows, when it no longer needs them.

Actuate open server functionality extends the Factory service to use an executable file to generate a document from a third-party vendor. For more information about open server technology, see Chapter 13, “Understanding Actuate iServer options,” in Administering Actuate iServer System.

Factoryservice

Design Generate code

ROIor

DOI

ROX or

DOX

BASROD

Browser

Viewer

ActuateActive Portal

Compile

Server activityresults in DHTML output

PrinterROV

or DOV

C h a p t e r 5 , U n d e r s t a n d i n g d o c u m e n t g e n e r a t i o n 65

The following illustration gives a conceptual overview of activities that occur in the process of generating an Actuate report.

The following illustration shows the major categories of processing, data streams, content creation, and page creation.

The following sections describe how the Factory service generates a document and the class protocols that determine how objects in a document fit together.

Starting the Factory serviceWhen you choose Report➛Build and Run, Actuate software executes a function called Factory( ), which is specific to your document. Factory( ) performs the following tasks:

4. Creates a page as needed

Frame and control

Data stream Section Page list

Page and flow

1. Delivers a data row

ROI

3. Passes a frame

2. Creates contents

Input Source

Data

Input Source

Data

Data stream Content

Page layout

Rows

Data rows Frames

Events

PagesROI

66 P r o g r a m m i n g e . R e p o r t s

■ Creates a report object instance (.roi) file or a data object instance (.doi) file. The Factory service uses either a default name with the same root name as the report object design (.rod) file or the name you type when Requester or the Request web page prompts for the output file name.

■ Creates a component relationship map. The component relationship map stores component reference information derived from the document design’s structure, to show how components connect.

■ Instantiates the document, a subclass of AcReport, the root object that contains all objects in a document.

■ Calls the document’s Build( ) method. This step starts the document-generation process.

■ Closes the ROI or DOI file.

Adding startup and cleanup codeYou can add code that runs before the Factory service initiates the document-generation task and after it generates the document. You do so by overriding the document’s Start( ) and Finish( ) methods. If you override Start( ), you must call Super::Start( ) first. If you override Finish( ), you must call Super::Finish( ) after your code.

Starting the build processOne of the first tasks for the Factory service is to instantiate the Report class. The Report class establishes the document’s content and page structure.

Method Called ... Example of use

Start( ) After the Factory service instantiates the document, before document generation begins

■ Initialize a global variable.

■ Verify or adjust parameter values a user entered.

■ Open a log file to track the objects or the number of pages the document creates.

Finish( ) After the document generates, before the ROI or DOI file closes

■ Send a completion notice to a user.

■ Write statistics to a log file.

C h a p t e r 5 , U n d e r s t a n d i n g d o c u m e n t g e n e r a t i o n 67

The content structure consists of objects that contain data. The page structure consists of objects that determine how to display document content. The following illustration shows examples of the two structures.

After instantiating the Report class, the Factory service calls the document’s Build( ) method, which performs the following tasks:

■ Calls NewPageList( ) to instantiate the page list the document design specifies.

■ Calls NewContent( ) to instantiate the top-level content the document design specifies. In a typical design, the top-level content is a document section.

■ Calls the top-level content’s Build( ) method to build the contents of the document.

Creating contentAll document content, such as a section, a frame, a control, or a chart, follows a protocol that determines how to build the content. The protocol makes it possible to connect document components into a variety of configurations. For example, the top-level content component can be a report, a sequential section, or a frame. You can nest a report within a report, a section within a report, a section within a section, a frame within a frame, and so on.

Report

Report section Page list

Group section Group section Page

Content structure Page structure

Page

Frame FlowFrame Frame Frame

Frame

Frame

Flow Flow Flow

Frame

Frame

Frame

Frame

Frame

Frame

68 P r o g r a m m i n g e . R e p o r t s

Using the core protocol for content creationAcReportComponent is the abstract base class that defines the protocol for creating document components and putting them together to form a document. The following methods, defined in AcReportComponent, form the core protocol for all persistent content objects.

Using a component reference in content creationA component reference plays a critical role in how the Factory service builds document contents. A component reference is the relationship among components in the structure of the document design. When a component uses or contains another component, the first component refers to the other.

A container object initiates the creation of its contents. For example, the report is the top-level container object. It creates the report section contained immediately within it. A report section creates the reports, sections, or frames within it. A frame creates the frames and controls within it.

The following illustration shows how the component reference relationships determine how the Factory service builds document contents.

Method Description

New( ) Initializes the object.

Start( ) Prepares the object for build operations. For example, a report section’s Start( ) method instantiates the connection and the data stream. The frame’s Start( ) method instantiates the controls it contains.

Build( ) or BuildFromRow( )

Builds the object’s contents. For example, a report section’s Build( ) method reads data rows from the data stream, instantiates the contents, and passes the data rows to them. The frame’s BuildFromRow( ) method passes the data rows to the controls it contains.

Finish( ) Prepares the object to write to the report object instance (.roi) file or document object instance (.doi) file. For example, the report section’s Finish( ) method closes the data stream and connection.

C h a p t e r 5 , U n d e r s t a n d i n g d o c u m e n t g e n e r a t i o n 69

The following sections describe how a component implements the core protocol for content creation. Understanding the key methods and the sequence of tasks they perform supports deciding where to place code to add custom processing.

Using a report section to implement the content-creation protocol A report section, a subclass of AcReportSection, is typically the top-level content in a report design. It gets data rows from the data stream and passes the rows to its contents.

The following table describes how the report section implements the core protocol.

Structure Implementation

Report Section

New( )

Start( )

Build( )

Finish( ) Controls

New( )

Start( )

Build( )

Finish( )

Frame

New( )

Start( )

Build( )

Finish( )

Report

Build( )

Method Task

Start( ) 1 Instantiates the connection.

2 Instantiates the data stream.

3 Passes the connection to the data stream.

4 Sets the sort key.

Build( ) 1 Opens the data stream.

2 Creates the Before frame.

3 Reads a row from the data stream.

70 P r o g r a m m i n g e . R e p o r t s

Using a group section to implement the content-creation protocolA group section organizes data by grouping rows on a key field, such as grouping customers by sales representative. A group section is typically the content of a report section. A group section contains other group sections or frames.

Each group section uses a unique sort key to define a group of rows. Set the group section’s sort key, typically the name of a table column, in the Key property.

The group section checks the key of each data row it receives. Rows with the same key value belong in the same group section. A change in a key’s value from one row to the next indicates the end of one group section and the start of another.

4 Processes the row:■ If content already exists, the report verifies that

the content needs the row. The report passes the row to the content if the content needs it.

■ If content does not exist or if an existing content rejects a row, the report instantiates new content and passes the row to the new content.

5 Repeats steps 3 and 4 until it retrieves all data rows.

6 Creates the After frame.

Finish( ) Closes the data stream and connection.

Method Task

Nested group sections in the structure

Sort key value in the Key property

[offices.officeID]

[salesreps.last]

[customers.customName]

[orders.orderID]

C h a p t e r 5 , U n d e r s t a n d i n g d o c u m e n t g e n e r a t i o n 71

The following table describes how the group section implements the core protocol.

Using a frame to implement the content-creation protocolA frame typically contains controls that display data from a data row. A frame gets data rows from its container object, typically a section, and passes those rows to the controls.

The following table describes how a frame implements the core protocol.

Method Task

Start( ) Initializes the group section.

BuildFromRow( ) 1 Accepts a data row from its container object.2 Processes the row.

■ If the row is the first row, the group section determines and stores the value of the sort key. The group section also creates the Before and After frames, passes the row to its contents and returns Continue Building. This return value indicates to the container object that the group section needs the next data row.

■ If the row is not the first, the section verifies that the row’s key is the same as the stored key value. If the keys match, the group section passes the row to its content. If the keys do not match, BuildFromRow( ) returns Rejected Row, indicating the end of a group section.

3 Repeats steps 1 and 2 until it retrieves all data rows, returning Continue Building.

Finish( ) Finishes the group section.

Method Task

Start( ) Instantiates and starts the frame’s contents in the order in which they appear in the structure. The frame’s contents can be other frames or controls.

BuildFromRow( ) Passes data rows to the frame’s contents.

Finish( ) Calls each control’s Finish( ) method.

72 P r o g r a m m i n g e . R e p o r t s

Using a control to implement the content-creation protocolA control typically displays a value from the data row it receives from its container, a frame. A control does not contain other components.

The following table describes how a control implements the core protocol.

Creating a pageThe content-creation process drives the page-creation process. The two processes occur concurrently. As each frame completes, the section that contains the frame passes the frame to the page list. As each page begins or ends, the page list notifies the section and the section generates a page header or footer.

Method Task

Start( ) Typically, a control needs only the default logic.

BuildFromRow( ) Sets the control’s value using data from a data row.

■ If a control, such as a line or label control, does not need the data row, BuildFromRow( ) returns Finished Building.

■ If a control needs only one row, BuildFromRow( ) sets the value of the control and returns Finished Building.

■ If a control is an aggregate control, it uses all data rows. BuildFromRow( ) returns Continue Building.

Finish( ) For an aggregate control, performs final calculations. For other controls, Finish( ) does nothing.

Section

Frame and control

Page list

Page and flow

Creates contents

Passes a frame

Creates a page as needed

Sends an event

C h a p t e r 5 , U n d e r s t a n d i n g d o c u m e n t g e n e r a t i o n 73

As the illustration shows, report sections and the page list work together. There are three page list styles:

■ AcSimplePageList

■ AcLeftRightPageList

■ AcTitleBodyPageList

A section can work with these styles because a page list follows a standard protocol. The protocol, defined in AcPageList, consists of the AddFrame( ) method. For more information about AddFrame( ), see “Determining the page on which to place a frame,” later in this chapter.

Determining the page on which to place a frameA section passes a frame to the page list by calling the page list’s AddFrame( ) method. AddFrame( ) determines the page on which to place the frame by checking the following conditions:

■ If the frame’s PageBreakBefore property is True, AddFrame( ) finishes the current page, if one exists, then starts a new page.

■ If the frame’s PageBreakBefore property is False, AddFrame( ) adds the frame to the page if it fits. If it does not fit, the page list starts a new page.

■ If the frame does not fit on a new page, AddFrame( ) clips the frame to the available space.

■ After placing the frame on a page, AddFrame( ) verifies the value of the frame’s PageBreakAfter property. If PageBreakAfter is True, AddFrame( ) finishes the current page. AddFrame( ) starts a new page when it gets the next frame.

Understanding the page listBefore instantiating a new page, the page list verifies that a section or frame has a specific page style specified in its NewPage( ) method. If a frame or section specifies a page style, the page list uses the specified style. If not, the page list uses its default page style.

A page list sends a notice to a section when one of the following events occurs:

■ StartFlow

■ StartPage

■ FinishFlow

■ FinishPage

74 P r o g r a m m i n g e . R e p o r t s

These events determine whether the content places a header at the start of a new flow or page, or a footer at the end of a flow or page. The following illustration shows the order in which headers and footers go into a report.

Instantiating a classWhen you create a report design using Design Editor, you combine components in a particular order, following a predefined set of component reference rules. For example, AcReportSection supports the following references:

■ Connection

■ DataStream

■ Before

■ PageHeader

■ Content

■ PageFooter

■ After

■ Subpage

A component reference appears as a slot in the Structure pane and as a property in Component Editor, as shown in the following illustration.

Section2 page header

Page header for report

Section2 page footer

Section1 page header

1

2

3

3

2Section1 page footer

Page footer for report 1

C h a p t e r 5 , U n d e r s t a n d i n g d o c u m e n t g e n e r a t i o n 75

Each component reference that a component supports has a corresponding method. This method has a New prefix followed by the name of the reference. For example, AcReportSection’s connection component reference has a corresponding NewConnection( ) method and its data stream component reference has a corresponding NewDataStream( ) method.

A container object uses these New<reference> methods to instantiate its content. To conditionally instantiate a component, you can override the New<reference> method. For example, if a report uses a different connection depending on the data stream it uses, you can override NewConnection( ) to write the conditional logic. For an example of how to conditionally instantiate a component, see “Conditionally creating a component,” in Chapter 6, “Customizing a report.”

Component reference properties

Component references the report section supports

76 P r o g r a m m i n g e . R e p o r t s

Working with a data streamA data stream consists of data adapters that collect, process, and deliver data rows to the report and sections. The report and sections pass these data rows to their contents until all data controls have the values they need. In the Factory service, the report section’s Start( ) method instantiates the data stream as part of its startup tasks before beginning the build process.

About data adaptersA data adapter can be a data source or a data filter. A data source retrieves data from an input source, such as a database or spreadsheet, and creates data rows. A data filter sorts, filters, or performs other computations on a data row.

Data sources, data filters, and data rows are transient objects. The Factory service deletes them after they retrieve, process, and deliver all data rows to a report.

Combining data adapters to form a data streamA data stream has the following characteristics:

■ A data stream must have at least one data source. It can have multiple data sources. If a report uses data from multiple input sources, there must be a data source for each input source.

■ A data stream can have any number of data filters.

The following illustrations show examples of data stream configurations.

Data source

Data row 1

Data stream

Input source

Data

Report section

C h a p t e r 5 , U n d e r s t a n d i n g d o c u m e n t g e n e r a t i o n 77

Data source

Data row 1

Data filter

Data row 2

Data stream

Input source

Data

Report section

Data source

Data row 1

Data filter Data filter

Data row 2 Data row 3

Data stream

Input source

Data

Report section

Data source (customers)

Data row 1

Data row 2

Data row 3

Data row

Data source (orders)

Data source (items)

Multi-input data filter

Data stream

Input source

Data

Report section

Input source

Data

78 P r o g r a m m i n g e . R e p o r t s

About the protocol for a data adapterA data source or data filter follows a common protocol, which the abstract base class AcDataAdapter defines. This protocol supports connecting data adapters. The following table describes the protocol.

Instantiating a data adapter The report section instantiates the data adapter that provides data rows to it. If a data stream consists of multiple data adapters, each data adapter instantiates the component that delivers data rows to it. The order in which you set up component references in the Structure pane determines the order in which data adapters instantiate. In the following illustration:

■ The report section instantiates data filter 2.

■ Data filter 2 instantiates data filter 1.

■ Data filter 1 instantiates the data source.

Method Description

Start( ) Opens the data adapter.

Fetch( ) Retrieves a single row. To retrieve all rows, the data adapter calls Fetch( ) repeatedly until there are no more rows. Fetch( ) returns Nothing after it retrieves all rows.

Finish( ) Closes the data adapter.

C h a p t e r 5 , U n d e r s t a n d i n g d o c u m e n t g e n e r a t i o n 79

Sequential and random access to dataTypically, an input source supports only sequential access to data. A SQL database, for example, returns a set of records based on your query and sends one input record at a time to the data source sequentially. Sometimes, however, your report requires random access to data. A report, for example, can use the same data multiple times to present data in both tabular and chart formats. A data filter can also require multiple passes over a set of rows for sorting or calculating totals.

To support random access, AcDataAdapter defines the following methods:

■ CanSeek( )

■ GetPosition( )

■ Rewind( )

■ SeekBy( )

■ SeekTo( )

■ SeekToEnd( )

Data source Data filter1 Data filter2 Report section

Flow of data

Order of instantiation

80 P r o g r a m m i n g e . R e p o r t s

e.Report Designer Professional provides two data filter classes, AcMemoryBuffer and AcRecordBuffer, that implement the random access methods. Use these classes in a data stream to create a data filter that processes rows in any order.

About data sourcesA data source retrieves data from an input source and creates data rows. It does so in three standard steps:

1 Open the input source.

2 Fetch the data. Each time the data source retrieves an input row, it instantiates a data row.

3 Close the input source.

Actuate software provides the data sources AcSQLQuerySource and AcTextQuerySource to retrieve data from SQL databases. If a report uses data from a different source, such as a flat file, you must create a custom data source. For an example of how to do so, see “Retrieving data from a flat file,” in Chapter 5, “Understanding document generation.”

AcStoredProcedureSource retrieves data from a stored procedure. For connections to SAP data sources, Actuate software uses other data source classes.

A data source typically requires a connection in order to access an input source. For more information about connections, see “Connecting to a database,” later in this chapter. The following table describes the methods for opening, using, and closing a data source.

About data filtersA data filter receives data rows from one or more data adapters, processes the data, then passes it to the next data adapter or to the report. There are two abstract classes of data filters:

■ AcSingleInputFilter, which accepts input from one data adapter

■ AcMultipleInputFilter, which accepts input from multiple data adapters

Method Description

Start( ) Opens the input source. If the input source is a SQL database, Start( ) opens the database cursor. If the input source is a spreadsheet or other flat file database, Start( ) opens the file.

Fetch( ) Retrieves a single input row and creates a data row.

Finish( ) Closes the input source.

C h a p t e r 5 , U n d e r s t a n d i n g d o c u m e n t g e n e r a t i o n 81

Unlike data sources, data filters are optional. If a report uses data from a SQL database, the database sorts and filters the data using criteria you specify in a query. Use a data filter only to process the data rows in ways that the database does not provide. For example, you can use a sort filter if the indexes in the database do not support the row order your report requires.

Typically, you use a data filter to process data from a non-SQL database or data that originates from several different external sources. For example, if a data stream has multiple query data sources, you can merge the resulting data through a multiple-input filter before passing it to the report. The processing algorithm always implements in the Fetch( ) method. For examples of creating a data filter, see “Creating a select filter” and “Creating a sort filter,” in Chapter 6, “Customizing a report.”

The following table describes the methods for working with a data filter.

About data rowsThe data source creates a data row instance for each input record it retrieves. A data row consists of variables, each corresponding to a single field or column of the input record.

If you use Query Editor to write a SQL query, the data source creates the data row. If you create a custom data source or a custom data filter, you must create a custom data row that works with the data source or filter. For an example of how to do so, see “Retrieving data from a flat file,” in Chapter 6, “Customizing a report.”

Understanding the data row life cycleThis section describes how Actuate software creates, assigns values to, and uses data rows.

1 The data source instantiates a data row each time it retrieves an input record using Fetch( ).

Method Description

Start( ) Instantiates and opens the input adapter, the data adapter that provides data rows to it.

Fetch( ) Retrieves a single data row and processes it. Optionally, the data filter creates a new data row.

Finish( ) Closes the input adapter.

82 P r o g r a m m i n g e . R e p o r t s

2 The data source copies the input record’s column values to the data row’s variables. If a report uses a SQL query data source, the SetupDataRow( ) method of the SQL query source performs this task.

3 A data control gets its value from the data row. The control’s SetValue( ) method retrieves from the data row the value of the column, variable name, or method name specified in the control’s ValueExp property.

4 The build process generates the code in SetValue( ) and matches the control’s ValueExp value with the corresponding data row variable when the report generates. SetValue( ) returns the value of the data row variable.

Input recordColumns

Variables

Data row

The Factory service generates CustomerName::SetValue taking “customers.customName” and finding the matching name in the data row. When the report generates, SetValue( ) returns the variable value.

C h a p t e r 5 , U n d e r s t a n d i n g d o c u m e n t g e n e r a t i o n 83

Connecting to a databaseA connection establishes a communication link to a database. You can place the connection in either a section or the data stream. Where you place the connection depends upon whether data adapters must share a connection.

Placing the connection in a data streamThe standard way to work with a database connection is to place the connection in the data stream. This approach groups the connection and the data stream together, making it easy to publish and reuse the data stream. This technique is efficient only if a report uses a single data stream or if each data stream in the report requires a different connection.

When you place a connection in a data stream, the data adapter instantiates the connection by calling NewConnection( ) and opens it by calling OpenConnection( ). You can override NewConnection( ) to customize the selection of a connection. You can override OpenConnection( ) to customize the connection before opening it.

Placing a connection in a sectionPlace a connection in a section if multiple data streams can or must share the connection. For example, if a report contains multiple subreports, each containing a data stream, you can place a single connection in the section common to all subreports. By sharing connections whenever possible, you improve the application’s performance.

When you place a connection in a section, the section’s Start( ) method instantiates the connection and passes it to the data source. The following illustration shows the relationships among the data source, report section, and a connection in a report section.

84 P r o g r a m m i n g e . R e p o r t s

About connection precedenceIf the report contains multiple connections, the data stream uses the connection closest to it in the report structure. For example, a connection in a data stream takes precedence over a connection in a section. If a data stream does not contain its own connection, e.Report Designer Professional searches upward in the report structure until it finds a connection.

About SQL supportAcConnection establishes the protocol for connecting, disconnecting, and generating error messages if a connection fails. The connection-specific classes shown in the following table define variables, such as user name and password, that are necessary to establish a connection.

The following table shows the databases to which you can connect and the Actuate Foundation Classes that support connecting to these databases. These classes derive from AcDBConnection. For more information about these classes, see Actuate Foundation Class Reference.

Data source Connection class

DB2 AcDB2Connection

Informix AcInformixConnection

Microsoft SQL AcMSSQLConnection

ODBC AcODBCConnection

Oracle AcOracleConnection

Data source

Class uses another class. For example, the data source uses the connection.

Class instantiates and owns another. For example, the data source owns the data row.

Input Source

Data

Report Section

Data Row

Connection

C h a p t e r 5 , U n d e r s t a n d i n g d o c u m e n t g e n e r a t i o n 85

To connect to any other type of input source, subclass AcConnection, the abstract base class for all connection classes, to create a connection.

Using statements and cursorsTo access data in a SQL database, you typically use a SQL query data source. The SQL query data source assembles the SQL SELECT statement you build using Query Editor and sends the statement to the database.

To communicate with the database, the data source uses statements (AcDBStatement) and cursors (AcDBCursor). The statement provides a way to execute a SQL SELECT statement. The result of a SELECT statement is typically a set of records. When a SQL SELECT statement returns table data, you need a database cursor. The cursor manages the retrieval of data rows. It also keeps track of the row position in the record set as the database sends each row to the data source.

About connection relationships The following describes the interactions among the report section, data source, connection, statement, and cursor:

■ The report section owns the data source and instantiates and deletes it. If the connection is in the report section, the report section owns the connection.

■ The data source instantiates and deletes the statement and cursor. The data source calls the connection’s Prepare( ) method to instantiate the statement. Then the data source calls the statement’s AllocateCursor( ) method to instantiate the cursor. If the connection is in the data source, the data source instantiates and deletes the connection.

■ The data source uses the connection.

■ The statement uses the connection.

■ The cursor uses the statement.

Progress AcProgressConnectionAcProgressSQL92Connection

SAP AcSAPConnection

Sybase AcSybaseConnectionAcSybaseDBLibConnection

Data source Connection class

86 P r o g r a m m i n g e . R e p o r t s

Creating and executing a custom SQL statementYou can create and send your own SQL statements to a database. For example, you can send a SQL statement to update a database record, drop a table, and so on. To do so, call the statement’s Execute( ) method after Prepare( ) to execute the SQL statement.

Use the statement’s Execute( ) method only to execute statements such as UPDATE, DELETE, or DROP TABLE that do not return data rows. To execute a SQL statement that returns rows, use a database cursor.

How to execute a SQL statement that does not require a cursor

1 Establish the connection.

2 Prepare the SQL statement using the connection’s Prepare( ) method.

Prepare( ) returns a reference to the DB statement object.

3 If the SQL statement accepts parameters whose values are provided later, use the statement’s BindParameter( ) method to bind the parameters with the values.

4 Execute the statement using the statement’s Execute( ) method.

Execute( ) returns True or False, depending on whether the statement runs successfully.

5 The statement is deleted.

6 The connection is deleted.

Report section

SQLQuery Data

Source

DB Statement

DB Cursor

Class uses another class

Class instantiates and owns another class

Connection

P a r t 2 , C u s t o m i z i n g r e p o r t d e s i g n s 87

P a r t

Part 2Customizing report designs

88 P r o g r a m m i n g e . R e p o r t s

C h a p t e r 6 , C u s t o m i z i n g a r e p o r t 89

C h a p t e r

Chapter 6Customizing a reportThis chapter contains the following topics:

■ Customizing a data stream

■ Customizing the report layout

■ Customizing report data

90 P r o g r a m m i n g e . R e p o r t s

Customizing a data streamThis section describes some of the common customization tasks for data streams. e.Report Designer Professional’s data stream model does most of the standard work of retrieving and filtering data for a report, particularly if the report uses data from a SQL database. You can customize the data stream if your report requires a special data source or data filter, to retrieve and process data from a text file, for example.

The methods you typically override are in the data adapter’s core protocol:

■ Start( ). e.Report Designer Professional calls Start( ) to open the data adapter. Override this method, for example, to open files from which the data stream gets data.

■ Fetch( ). e.Report Designer Professional calls Fetch( ) to retrieve each row. Override this method to populate the variables in a data row with the retrieved data row or to provide custom filtering.

■ Finish( ). e.Report Designer Professional calls Finish( ) to close the data adapter. Override this method, for example, to close files you might have opened in Start( ).

If you change a data row after the data stream populates it with data from the input record, override the data row’s OnRead( ) method. e.Report Designer Professional calls OnRead( ) after the data row gets its data.

Creating a computed data row variableTo create a variable in a data row that contains values that other variables compute:

■ Create the data source component and its data row component.

■ Add variables to the data row to store the computed values. To do so, use the Variables page of Component Editor.

■ Override the OnRead( ) method of the data row to compute the new values.

The following code overrides the data row’s OnRead( ) method to calculate values for the ExtendedCost and DaysLate variables. These values are computed from values in three other variables in the data row, Cost, Quantity, and DueDate.

C h a p t e r 6 , C u s t o m i z i n g a r e p o r t 91

Sub OnRead( )Super::OnRead( )ExtendedCost = Cost * QuantityDaysLate = Date( ) - DueDateIf DaysLate < 0 Then

DaysLate = 0End If

End Sub

You can also create a method that calculates and returns the value. For example, instead of creating the DaysLate variable and writing code in OnRead( ) to calculate the value, you can encapsulate the code in a method in the data row class. You can then use the method name in the ValueExp property of the control with which to display the days late value.

The data source calls OnRead( ) once for each data row right after the row receives its data from the input record. The call to the OnRead( ) method of the superclass is not necessary but it is a good programming habit in case of future functionality changes.

Filtering out a selected data rowThis section describes how to conditionally filter out a row from a set of input records by adding custom code to the data source. The simplest way to filter a row is to use Query Editor. Use the technique described in this section when using Query Editor is not feasible.

■ First, create the data source component.

■ Override the data source’s Fetch( ) method to specify which rows to retrieve.

In the following example, the Fetch( ) method of the data source calls Fetch( ) for the base class to get each row. When each row is retrieved, Fetch( ) verifies that the state column contains the correct value. If it does, Fetch returns the row. This process repeats until Fetch( ) retrieves all rows:

Function Fetch( ) As AcDataRowDim row As CustomerRowDo

Set row = Super::Fetch( )If row Is Nothing Then

Exit FunctionEnd if

Loop until row.State = "CA"Set Fetch = row

End Function

To filter a row when you run a report, create parameters that accept run-specific conditions. For more information about filters, see “Creating a select filter,” later in this chapter.

92 P r o g r a m m i n g e . R e p o r t s

Creating a select filterThis section describes how to create a data filter that conditionally selects rows by overriding a method. You can also use Query Editor to filter rows. Use the technique described in this section only when using Query Editor is not feasible.

You can write the filter code in the Fetch( ) method of the data source, as described in “Filtering out a selected data row,” earlier in this chapter. If, instead, you encapsulate the filter code in a data filter, you can use the data filter in other data streams. If you publish the filter to a library, you can use the same filter in other report designs.

How to create a select data filter

1 If your report design already has a data source, move the data source to Scratch Pad.

2 Place a data adapter in the DataStream slot.

A list of data adapters appears.

3 Select Single Input Filter from the list.

4 Move the data source from Scratch Pad to the Input slot of the filter. The data source becomes the input source for the filter. The filter is the data adapter that provides the report section with the data rows.

5 Override the filter’s Fetch( ) method to specify which rows to retrieve.

In the following example, the data filter’s Fetch( ) method calls the input source’s Fetch( ) method to retrieve the row. The InputAdapter variable stores a reference to the input source. When each row is retrieved, Fetch( ) verifies that the State column contains the requested value. If it does, Fetch( ) returns the row. This process repeats until Fetch( ) retrieves all rows:

C h a p t e r 6 , C u s t o m i z i n g a r e p o r t 93

Function Fetch( ) As AcDataRowDim row As CustomerRow

DoSet row = InputAdapter.Fetch( )If row Is Nothing Then

Exit FunctionEnd if

Loop until row.State = "CA"Set Fetch = row

End Function

Creating a sort filterThis section describes how to create a data filter that sorts data rows by overriding a method. Although you can create a sort filter using Query Editor, it is not always be feasible to do so.

How to create a sort filter

1 If your report design already has a data source, move it to Scratch Pad.

2 Place a data adapter in DataStream.

3 Select Disk-based Data Row Sorter from the list of data adapters that appears.

4 Move the data source from Scratch Pad to the Input slot of the filter. The data source becomes the input source for the filter. The filter is the data adapter that provides a report section with data rows.

5 Override the filter’s Compare( ) method to specify how to sort the rows. Compare( ) takes two rows as arguments and returns one of the following values:■ A positive number if the first row goes after the second row■ 0 if both rows are the same■ A negative number if the first row goes before the second row

Use the CompareKeys( ) method to compare field values. CompareKeys( ) performs data type-independent comparisons. For a descending sort order, negate the value CompareKeys( ) returns.

94 P r o g r a m m i n g e . R e p o r t s

In the following example, Compare( ) compares rows by their state and customer ID:

Function Compare( row1 As AcDataRow, row2 As AcDataRow ) As Integer

Dim cust1 As AcCustomerRowDim cust2 As AcCustomerRow

Set cust1 = row1Set cust2 = row2

' Compare the state. CompareKeys( ) is a predefined methodCompare = CompareKeys( cust1.State, cust2.State )If Compare <> 0 Then

Exit FunctionEnd If

' Compare the customer id. Compare two integers by subtracting themCompare = cust1.ID - cust2.ID

End Function

Retrieving data from a flat fileTo retrieve data from a flat file:

■ Create the basic report

■ Create a custom data source by subclassing AcDataSource

■ Define the custom data source to your report

■ Process the flat file data

The Report Wizard generates a SQL data source. To create a custom data source, create a report design without using a wizard. Then create a custom data stream component by subclassing AcDataSource from the AFC library.

How to create the basic report

1 Select File➛New➛Blank Report. Choose OK.

The blank report opens in Design Editor.

2 Choose File➛Save As.

Save As opens.

3 Name the file and place it in a directory. For example:

C:\Program Files\Actuate7\ErdPro\MyReports\FlatFile.rod

The following illustration shows the basic report design.

C h a p t e r 6 , C u s t o m i z i n g a r e p o r t 95

The report design contains Connection and DataStream components. Next, you define two new variables for the DataStream component to facilitate connection to the flat file.

How to create a custom data source

Create the custom data source by changing the superclass of the data stream. In this case, you change the superclass to AcDataSource. To change the superclass:

1 In Design Editor, double-click the DataStream component.

Component Editor appears.

2 Choose Class.

3 In Super Class, type:

AcDataSource

4 Choose Close.

How to define a custom data source

To ensure that the DataStream component connects to the flat file, define the following two variables:

■ Channel, which contains the file number used by the operating system to identify the flat file

■ DataInputFile, which contains the name of the custom data source

Define the Channel and DataInputFile variables using the following steps:

1 Double-click the DataStream component.

Component Editor appears.

96 P r o g r a m m i n g e . R e p o r t s

2 Choose Variables.

3 Choose New.

Parameter Attributes appears.

4 Define Channel as follows:■ Name: Channel■ Type: Integer■ Storage: Instance

■ Visibility: Public

5 DefineDataInput File as follows:■ Name: DataInputFile■ Type: String■ Storage: Static ■ Visibility: Parameter

Choosing Static ensures that the variable is available to the entire report. You define DataInputFile as a parameter so users can enter a file name when they run the report.

6 Choose OK.

7 In Variables, select the DataInputFile variable. Choose Builder.

Parameter Attributes appears.

8 Set the Default Value for the parameter, DataInputFile, to the full path name of your flat file. For example:

C:\FlatFile.txt

The report uses this default file name as the name of the custom data source but a user can enter a value for file name at the Requester prompt. Default Value is case-sensitive.

9 Choose OK.

10 Close Component Editor.

How to define a data row variable for a custom data source

When you develop a report using a standard SQL data source, e.Report Designer Professional defines variables on the data row corresponding to the database columns you select for your report. For a custom data source, you must define data row variables that correspond to the columns in your flat file.

1 In the Structure pane, double-click DataRow.

Component Properties appears.

C h a p t e r 6 , C u s t o m i z i n g a r e p o r t 97

2 Choose Variables.

3 Choose New to create new data row variables. These variables must correspond exactly to the fields in the flat file.

The following illustration shows the settings for a flat file that contains two string fields, First and Second, and an integer field, Figures.

4 After you create all data row variables, choose Close.

How to define the data display

After you define the custom data source and create data row variables, include those variables in your report design.

1 In the Structure pane, select the frame for the Report Content section and choose Field List.

2 Drag the data row variables you created from Field List and drop them in the frame.

3 Resize and align the controls in the frame as needed.

4 Add text labels in the Before and PageHeader frames.

How to process the flat file data

To process the data from the flat file, override the Start(), Fetch(), and Finish() methods.

1 Double-click the DataStream component.

Component Editor appears.

98 P r o g r a m m i n g e . R e p o r t s

2 Choose Methods.

3 Select the Start( ) method. Choose Override.

4 In Method Editor, override the Start( ) method to open the flat file. Enter the following code:

Function Start( ) As BooleanStart = Super::Start( )

Channel = FreeFile( )Open DataInputFile For Input As Channel

End Function

5 Choose Close.

6 Override the Fetch method. Type the following code:

Function Fetch() As AcDataRowDim rowAs DataRow

If EOF (Channel) ThenExit Function

End If

Set row = New DataRow

Input #Channel, row.First, row.Second, row.Figures

Set Fetch = rowAddRow( Fetch )

End Function

7 Override the Finish() method to close the flat file. Type the following code:

Sub Finish( )Super::Finish( )Close #Channel

End Sub

8 Run the report.

Working with data from multiple sourcesTo retrieve data from multiple sources, use AcMultipleInputFilter and override its methods to indicate how to retrieve and process the data. AcMultipleInputFilter accepts input from any number of data adapters, processes the data, and passes it to the next data adapter or to the report.

This section describes two different ways to customize AcMultipleInputFilter to process data from two or more input adapters:

■ Create a union filter that processes all the data rows from one input adapter before processing data rows from the second input adapter.

C h a p t e r 6 , C u s t o m i z i n g a r e p o r t 99

■ Create a merge filter that combines the data rows from two input adapters.

Use the following steps to create a multiple input filter:

1 Remove the DataStream component from the report, if there is one.

2 Place a data filter component into the DataStream slot.

Select Component appears.

3 Select Multiple-Input Filter. Choose OK.

4 Place a data source into the Input slot of the multiple input filter.

The multiple input filter gets its data from these data sources. If you use a SQL query data source, use Query Editor to select the data to retrieve.

5 Place another data source into the multiple input filter.

The new data source appears as a second Input slot for MultipleInputFilter.

6 Override the multiple input filter’s Fetch( ) method to code the filter algorithm.

How to create a union filter

To display data from two tables, use two SQL query data sources. In the following example, the multiple input filter processes all the data from the first data source, then all data from the second data source. The finished report displays data in the same order.

The following illustration shows the report design.

This data source is the first input adapter that gets and sends order ID data to the filter

This data source is the second input adapter that gets and sends customer name data to the filter

This filter accepts input from two data sources (input adapters)

100 P r o g r a m m i n g e . R e p o r t s

Use the following steps to create the union filter:

1 For the filter to access each input adapter in order, create an iterator. Define two variables for the filter: ■ UnionIter of type AcIterator ■ CurrentInput of type AcDataAdapter.

UnionIter stores a reference to the iterator you create in the filter’s Start( ) method. CurrentInput stores a reference to the input adapter that sends data to the filter.

2 Override the filter’s Start( ) method to create an iterator that accesses the first input adapter and prepares it to get data:

Function Start( ) As Boolean Start = Super::Start( )

If Not Start Then Exit Function

End If

' Create an iterator to access the input adapterSet UnionIter = InputAdapters.NewIterator' Initialize CurrentInput to the first input adapterSet CurrentInput = UnionIter.GetNext()

End Function

3 Override the filter’s Fetch( ) method to retrieve each row of data from the first input adapter and pass it to the report. When the first input adapter retrieves all rows, retrieve rows from the second input adapter:

Function Fetch( ) As AcDataRowDo While True

If CurrentInput Is Nothing ThenExit Function

End If

Set Fetch = CurrentInput.Fetch()If Not Fetch Is Nothing Then

Exit FunctionEnd If

Set CurrentInput = UnionIter.GetNext()Loop

End Function

4 Override the filter’s Finish( ) method to write cleanup code:

Sub Finish( )Set UnionIter = Nothing

Super::Finish( )End Sub

C h a p t e r 6 , C u s t o m i z i n g a r e p o r t 101

The following illustration shows the first page of the generated report. The report displays all the data from the first data source, then all data from the second source.

How to create a merge filter

A report displays data from two tables: customer names from the Customers table, and order IDs from the Orders table. To get data from these two tables, two SQL query data sources are used. In this example, the multiple input filter creates a new data row by merging the data rows retrieved by each data source.

Data from the Orders table

Data from the Customers table

102 P r o g r a m m i n g e . R e p o r t s

The following illustration shows the report design.

Use the following steps to create the merge filter:

1 Create a new data row for the multiple input filter and define the following variables: ■ customName (string)■ orderID (integer)

2 Override the filter’s Fetch( ) method to retrieve one row of data from each input adapter, create a new data row with the merged data, and pass the data row to the report. This process continues until there are no more rows to retrieve:

Function Fetch( ) As AcDataRowDim adapter As AcDataAdapter' Start the first input adapterSet adapter = InputAdapters.GetAt(1)

' Retrieve a row from the first input adapterDim aOrderDataRow As OrderDataRowSet aOrderDataRow = adapter.Fetch()

' Start the second input adapter

This data source is the first input adapter that gets and sends order ID data to the filter

This data source is the second input adapter that gets and sends customer name data to the filter

This filter accepts input from two data sources (input adapters)

The filter creates a new data row that merges data from the two input adapters

C h a p t e r 6 , C u s t o m i z i n g a r e p o r t 103

Set adapter = InputAdapters.GetAt(2)

' Retrieve a row from the second input adapterDim aCustomerDataRow As CustomerDataRowSet aCustomerDataRow = adapter.Fetch()

' Create the new data rowDim aMergedDataRow As MergedDataRowSet aMergedDataRow = New DataRow( )

' Assign the data from the first row to a variable in the new data rowIf Not aOrderDataRow Is Nothing Then

aMergedDataRow.orderID = aOrderDataRow.orders_orderIDElse

aMergedDataRow.orderID = NullEnd If

' Assign the data from the second row to a variable in the new data rowIf Not aCustomerDataRow Is Nothing Then

aMergedDataRow.customName = aCustomerDataRow.customers_customName

End If

If aOrderDataRow Is Nothing And aCustomerDataRow Is Nothing ThenExit Function

End If

Set Fetch=aMergedDataRowEnd Function

The following illustration shows the first page of the generated report. Each row contains data from the Customers and Orders tables.

104 P r o g r a m m i n g e . R e p o r t s

Customizing the report layoute.Report Designer Professional generates a report according to a design you create using Design Editor. You can, however, dynamically change the contents of the report as it generates. This section covers the following topics:

■ Conditionally creating a component

■ Dynamically embedding an image control

Conditionally creating a componentBy default, Design Editor generates code to instantiate a component based on component references you create in the Structure pane. As described in Instantiating a class in Chapter 5, “Understanding document generation,” container objects use New<reference> methods to instantiate their contents. You can, however, instantiate a component based on specific conditions. For example, you can create different frames depending on the value of a data row variable.

How to conditionally create a component

1 Determine the container class of the component containing the item to control. Add custom code to this container class. For example, to conditionally instantiate a frame, add code to the group section that contains it.

2 Determine the component reference over which you want to take control. For example, to conditionally instantiate a frame in a group section, determine if that frame is a Before, PageHeader, Content, PageFooter, or After component in the group section. The name of the component reference appears in the Structure pane as the name of the slot.

3 Override the New<reference> method of the container class. For example, if the component you want to conditionally instantiate is the Content component of its container class, override NewContent( ).

The report in the following illustration uses data from the Office table. One of the columns is officeID. When the framework generates the report, it creates different frames depending on the officeID value, as follows.

officeID value Frame

1 BostonContents

2 NewYorkContents

3 PhiladelphiaContents

C h a p t e r 6 , C u s t o m i z i n g a r e p o r t 105

The following illustration shows the report design.

How to implement a report

Use the following steps to implement the report:

1 Open the report design’s project view and create the three city-specific frames there: ■ BostonContents■ NewYorkContents■ PhiladelphiaContents

You can subclass from the generic frame, OfficeContents, and add controls or features specific to each frame.

2 Override the NewContent( ) method of the frame’s container class, OfficeGroup:

Generic frame to replace with one of three city-specific frames when the report runs

106 P r o g r a m m i n g e . R e p o r t s

Function NewContent( ) As AcReportComponentSet NewContent = Super::NewContent( ) Dim row As ConditionalExampleDataRow

'Get the current row for the group sectionSet row = GetCurrentRow()If row Is Nothing Then

' Creating a content for use in detecting two-pass aggregates' This report has no aggregates, so just return NothingExit Function

End If'Check the value of officeID to create the appropriate frame:Select Case row.offices_officeID

Case 1Set NewContent = New Persistent BostonContents

Case 2Set NewContent = New Persistent NewYorkContents

Case 3Set NewContent = New Persistent PhiladelphiaContents

End SelectEnd Function

Dynamically embedding an image controlThis section describes how to create a report that displays different, embedded images in each report instance, depending upon some criteria. For example, when you generate reports for different customers using the same report object executable (.rox) file, you can include a different customer’s company logo at the top of each report.

To dynamically embed images in a report:

■ Open the report in e.Report Designer Professional.

■ Select the image control.

■ In Component Editor—Properties, set Embedded to False.

■ In Component Editor—Variables, add a string parameter to the image control.

■ Add parameters to the report that support determining the image to include when the report runs. For instance, add an ad hoc parameter, Customer, that supports requesting a report for a specific customer.

■ In the image control’s Finish( ) method or another report-generation method, use ConvertBFileToString( ) to convert the image file to a string value and set the string parameter to the converted string value.

■ Override the image control method that determines whether to display or print the control:

C h a p t e r 6 , C u s t o m i z i n g a r e p o r t 107

■ Call ConvertStringToBFile( ). ConvertStringToBFile( ) converts the image’s string value back into an image, then stores the image in a temporary file. The Viewer uses this file to display the image. For example, override the ShowWhenPrinting( ) or ShowWhenViewing( ) methods to convert the string.

■ Remove the temporary file.

How to create a dynamic image control using ShowWhenViewing( )

1 In Component Editor, choose Variables.

2 Add a string parameter called CorpLogo.

3 Override the image control’s Finish( ) method:

Sub Finish( )Super::Finish( )‘Insert your code hereDim ImageFile As StringImageFile = CompanyName & “.bmp”CorpLogo = ConvertBFileToString( ImageFile )

End Sub

4 Override the ShowWhenViewing( ) method to prepare the image for display, display the file, and remove the temporary file. The following example removes the temporary file by:■ Creating a subclass of the Viewer class called CleanupViewer with a

custom method, GetCleanupViewer( )■ Directing the subclass to remove the temporary file in its destructor

Function ShowWhenViewing( ) As Boolean ShowWhenViewing = Super::ShowWhenViewing( ) ' Insert your code here

If ShowWhenViewing = True ThenFileName = ConvertStringToBFile( CorpLogo )GetCleanupViewer.RemoveFileAtTheEnd( FileName )

End IfEnd Function

To include a dynamic image in a printed report, override the ShowWhenPrinting( ) method in a similar way.

To see a sample report with dynamic images, open roiimage.rod in \Program Files\Actuate7\ErdPro\Examples.

For more information about the Actuate Basic functions ConvertStringToBFile( ) and ConvertBFileToString( ), see Chapter 2, “AFC data types,” in Actuate Foundation Class Reference.

108 P r o g r a m m i n g e . R e p o r t s

Customizing report dataActuate e.Report Designer Professional generates a report using data you specify in Design Editor. You can, however, customize the data values or properties of controls as the report generates. The following are examples of some customization tasks:

■ Display a control’s data value in a different style depending on the value, such as positive numbers in red text and negative numbers in black.

■ Change the property of a control based on the value of another. For example, set the text of a label control to Payment overdue if the value of a currency control is greater than 0.

Conditionally setting properties of a controlThis section describes how to change the properties of a control based on its value. Actuate stores the control’s value in the DataValue variable.

How to conditionally set the properties of a control

Override one of the control’s methods to write the conditional code. Choose a method that the Factory service can call any time after the control’s data value is available. The control’s OnRow( ) method is a good choice because it sets the value of the control. Another option, for an aggregate control, is the control’s Finish( ) method.

The following example overrides an integer control’s OnRow( ) method so that the value appears in green when it is greater than 20:

Sub OnRow( row As AcDataRow ) OnRow = Super::OnRow( row ) If DataValue > 20 Then

Font.Color = greenEnd If

End Sub

Creating a custom control to display a group section keyThis section describes how to create a custom control to display a group section key. The following example shows how to use a text control to refer to a group section’s key value. You drop a text control in a frame in the group section, add a function to return the value of the group key, and call the function from the text control’s ValueExp property. The example works for controls in frames in group section Before, Content, or After slots.

C h a p t e r 6 , C u s t o m i z i n g a r e p o r t 109

To use the example:

1 Open the report design in e.Report Designer Professional.

2 Place a text control in the Before, Content, or After frame of the group section:

1 Drop a text control component in the Before, Content, or After frame of the group section.

Component Properties appears.

2 Enter GetKeyValue( ) in the ValueExp field. Choose OK.

3 Add the GetKeyValue( ) function to the text control:

1 Right-click the control. Choose Properties.

2 Choose Methods.

Methods appears.

3 Choose New.

Add Method appears.

4 In Name, enter:

GetKeyValue

5 In Type enter:

String

6 Choose OK.

Method Editor appears.

7 Type the following function code into Method Editor:

Function GetKeyValue( ) As String' Gets the key value of the Group Section containing this control.Dim section As AcGroupSection

Set section = FindContainerByClass( "AcGroupSection" ) If Not section Is Nothing Then

GetKeyValue = section.GetKeyString() End If

End Function

8 Choose Close.

4 Recompile and run the report.

The group key value appears in the specified section of the group section. The code is generic to any group section. You can publish this control to a library and use it in any report design.

110 P r o g r a m m i n g e . R e p o r t s

Changing a control property based on another control’s value This section describes how to access the value of one control to change the properties of another. Actuate provides several ways to access the value of a control:

■ GetControlValue( ) method

■ FindContentByClass( ) method

■ ObjectVariable property

■ A global variable

The following sections discuss each approach.

In the following illustration, the content frame of a report design contains controls to display data about cars and their prices. The frame includes a currency control, PriceCurrencyControl, that displays the price of the car, and a label control, CodeLabelControl, in which the text and text color depend on the value in PriceCurrencyControl. If the price of the car exceeds $35,000, CodeLabelControl displays Luxury in red. Otherwise, CodeLabelControl displays default text settings.

The following illustration shows the report design.

Using GetControlValue( )GetControlValue( ) returns the value of another control within the same frame. To get the value of PriceCurrencyControl, override one of CodeLabelControl’s methods to call GetControlValue( ). Choose a method that the Factory service can call anytime after the data value is available, such as BuildFromRow( ) or, for an aggregate control, Finish( ).

In the following code example, the control’s OnRow( ) method contains the conditional code. To see the OnRow( ) method:

1 Open Component Editor by double-clicking a component.

If the value of PriceCurrencyControl exceeds $35000, CodeLabelControl displays Luxury in red

C h a p t e r 6 , C u s t o m i z i n g a r e p o r t 111

2 Choose Methods.

Methods appears.

3 Choose Filter.

Method Filtering appears.

4 Select the Show all methods filter. Choose OK.

All methods available to the control appear in Methods, including the OnRow( ) method:

Sub OnRow( row As AcDataRow ) Super::OnRow( row )If GetControlValue("PriceCurrencyControl") > 35000 Then

Text = "Luxury"Font.Color = Red

End IfEnd Sub

If you use GetControlValue( ) with this approach, you must be aware of the order in which controls generate, or GetControlValue( ) can return a Null value. Typically, the controls in a frame are built in the same order in a frame’s slot information.

In the previous example, the code assumes PriceCurrencyControl generates before CodeLabelControl. If CodeLabelControl generates first, GetControlValue( ) returns Null because the value of PriceCurrencyControl is not yet set. In such a case, override the OnRow( ) method of the containing frame and access PriceCurrencyControl using its ObjectVariable property. “Using the ObjectVariable property,”later in this chapter, explains this technique.

Using the ObjectVariable propertyA second approach to changing one control based upon the value of another involves working with two Actuate Basic elements:

■ Set the ObjectVariable property of each control. You can think of the ObjectVariable property as a kind of alias for each of the controls. More precisely, when you assign a value to ObjectVariable, the framework generates a function to access the control.

■ To write the conditional code, override a method in the frame that contains both controls. Choose a method that the Factory service calls any time after the data values are available, such as the frame’s OnRow( ) method or, for accessing an aggregate control, the frame’s Finish( ) method.

The following steps explain this technique:

1 Using Component Editor, assign SalesPrice to the ObjectVariable property of PriceCurrencyControl.

112 P r o g r a m m i n g e . R e p o r t s

Do not use the name of a existing method or control when you assign a value to ObjectVariable. If you do so, an error occurs when the report compiles.

2 Assign LuxuryFlag to the ObjectVariable property of CodeLabelControl.

3 Override the OnRow( ) method of the containing frame to write the conditional code:

Sub OnRow(row As AcDataRow)Super::OnRow( row )

If SalesPrice.DataValue > 35000 Then

LuxuryFlag.Text = "Luxury"LuxuryFlag.Font.Color = Red

End IfEnd Sub

Using ObjectVariable, you can access a control only from its containing frame, not from another control. For more information about accessing a control from another control, see “Using GetControlValue( ),” earlier in this chapter.

Using FindContentByClass( )FindContentByClass( ) is a method in a container component, such as a frame or a page. It locates and returns a reference to a content component using the class name of that component.

To access the values of CodeLabelControl and PriceCurrencyControl with FindContentByClass( ), override a method in the frame that contains both controls. Choose a method that the Factory service calls anytime after the data values are available, such as the frame’s OnRow( ) method or, for accessing an aggregate control, the frame’s Finish( ) method.

In the following code example, the frame’s OnRow( ) method contains the conditional code:

Sub ORow( row As AcDataRow )Super::OnRow( row )

Dim priceControlVar As AcControl, lblControlVar As AcLabelControl

Set priceControlVar = FindContentByClass( "PriceCurrencyControl" )Set lblControlVar = FindContentByClass( "CodeLabelControl" )

If priceControlVar.GetValue( ) > 35000 ThenlblControlVar.Text = "Luxury"lblControlVar.Font.Color = Red

End IfEnd Sub

C h a p t e r 6 , C u s t o m i z i n g a r e p o r t 113

Using FindContentByClass( ), you can access a control only from the containing frame, not from another control. For information about accessing a control from another control, see “Using GetControlValue( ),” earlier in this chapter.

Using a global variableThe other three approaches to accessing a control work only with controls that are in the same frame. If you must access a control’s value from a control in a different frame, use a global variable to store the control’s value. Doing so makes the value available to any component in the report.

The following steps show how to set the properties of CodeLabelControl based on the value of PriceCurrencyControl using a global variable:

1 In an included Basic source module, declare a global variable, gintPriceValue:

DeclareGlobal gintPriceValue As Integer

End Declare

2 Override PriceCurrencyControl’s OnRow( ) method to assign PriceCurrencyControl’s data value to the global variable. Doing so makes the data value available to any component in the report:

Sub OnRow( row As AcDataRow )Super::OnRow( row )gintPriceValue = DataValue

End Sub

3 Override CodeLabelControl’s BuildFromRow( ) method to set the properties of CodeLabelControl based on the value of PriceCurrencyControl, which the global variable gintPriceValue stores:

Sub OnRow( row As AcDataRow )Super::OnRow( row )If gintPriceValue > 35000 Then

Text = "Luxury"Font.Color = Red

End Sub

Although this approach works well enough, it is generally good practice to avoid using a global variable. It can contribute to the creation of complex state machines and make the logic of an application hard to understand. Often you can access a control’s value by using an object reference variable.

114 P r o g r a m m i n g e . R e p o r t s

C h a p t e r 7 , D e b u g g i n g a r e p o r t 115

C h a p t e r

Chapter 7Debugging a reportThis chapter contains the following topics:

■ About debugging

■ Understanding the types of errors

■ Starting a debugging session

■ Controlling program execution

■ Examining variable values

■ Viewing the stack of method calls

116 P r o g r a m m i n g e . R e p o r t s

About debuggingDebugging is the process of locating and eliminating errors in a program. Typically, debugging involves executing specific portions of a computer program and analyzing the operation of those portions. Actuate e.Report Designer Professional contains debugging tools to identify and fix compile-time and run-time errors. Using e.Report Designer Professional, you can debug the following items in your report application:

■ An Actuate Basic source file (.bas) in the report design

■ An Actuate Foundation Class method

Using the debugging tools in e.Report Designer Professional, you can perform the following tasks:

■ Set breakpoints to execute instructions up to a specified point then stop and view the result.

■ Inspect or watch variables to check that values are being set as you expected.

■ Execute a method one line at a time, or step over methods that you know are error-free.

■ View the current execution stack.

e.Report Designer Professional also provides a tool to set parameters for successive debugging runs of a report application.

The following sections describe the debugging tools and how to use them.

Understanding the types of errorsThe first step in fixing bugs is understanding the three kinds of errors your code can contain:

■ Compilation, or syntax, errors

■ Run-time errors

■ Logic errors

About compilation errorsCompilation errors result from incorrectly constructed statements. Typical errors include mistyping a reserved word, omitting necessary punctuation, or failing to balance pairs of statements such as If and End If. The compiler

C h a p t e r 7 , D e b u g g i n g a r e p o r t 117

detects these errors and generates a list of error descriptions in the Actuate Output window. When you double-click an error description or press F4, Actuate Basic displays the method containing the error and an arrow points to the line where the error occurred.

Run-time errorsYour document can be free of compilation errors but still fail to generate because it contains run-time errors. These errors occur while the code executes. Run-time errors result when e.Report Designer Professional tries to perform an impossible task, such as opening a file that does not exist or trying to divide a number by zero. Like compilation errors, run-time errors are easy to find and fix. When Actuate Basic encounters a run-time error, it stops document generation and displays the method containing the error. An arrow points to the line where the error occurs.

Logic errorsIf your code is syntactically correct and runs without errors, it can still produce incorrect results. For example, you can expect your code to calculate a particular value but it results in an erroneous value. These errors, called logic errors, occur if, for example, you use the wrong operator or function, forget to initialize a variable, or assign an incorrect value to a variable.

Actuate Basic cannot identify logic errors as it can compile and run-time errors. Much of your debugging effort typically goes into solving logic errors. Debugging tools help you identify logic errors by letting you monitor the values of your program variables and objects as the program executes.

About the Actuate Output windowThe Actuate Output window displays document generation progress, status, and compilation error messages. Using Actuate Output, you can double-click a compilation error message and jump directly to the Actuate Basic statement that caused the error.

Occasionally, a document design includes a reference to an obsolete property. This condition can arise, for example, when you run a report design developed using an earlier release of e.Report Designer Professional and a property no longer exists in the current release. When you run the report, e.Report Designer Professional presents informational error messages about the obsolete properties. To remove references to these obsolete properties from the design, choose Report➛Verify Design.

118 P r o g r a m m i n g e . R e p o r t s

Starting a debugging sessionYou can debug methods and Actuate Basic source files. The following sections provide step-by-step instructions for starting a debugging session for each type of file.

How to start a debugging session for a method

1 Select the method to debug and display it in Method Editor:

1 In the structure pane, double-click the class containing the method you want to debug.

Component Editor appears.

2 Choose Method.

The list of methods associated with the class, both inherited and declared, appears. You can debug only methods that are declared or overridden in the class. To debug any of the inherited methods that appear in this list, access them from the class in which they are declared.

3 Choose Filter.

Method Filtering appears.

4 Select Only local methods, then choose OK.

Methods displays only methods redefined or defined in the class.

5 Choose the method you want to debug.

The code for the method appears in Method Editor.

2 Set a breakpoint at the line of code where you want to stop execution by choosing Debug➛Toggle Breakpoint or pressing F9.

For more information about using a breakpoint, see “Running to a breakpoint,” later in this chapter.

C h a p t e r 7 , D e b u g g i n g a r e p o r t 119

3 Close Method Editor and Component Editor.

4 Choose Report➛Build and Run to start code execution.

When Actuate Basic reaches the breakpoint, it stops program execution. You can then use Actuate’s debugging features to manipulate code execution or inspect variable values. These features are explained later in this chapter.

How to start a debugging session for an Actuate Basic source file

1 Choose File➛Open.

Select File appears.

2 Navigate to the Actuate Basic source file you want to debug. Choose Open.

The code appears in the source file window.

3 Set a breakpoint at the line of code where you want to stop execution by choosing Debug➛Toggle Breakpoint or pressing F9.

For more information about using breakpoints, see “Running to a breakpoint,” later in this chapter.

4 Close the source file window.

5 Choose Report➛Build and Run to start code execution.

When Actuate Basic reaches the breakpoint, it stops program execution. You can then use Actuate’s debugging features to manipulate code execution or inspect variable values. These features are explained later in this chapter.

120 P r o g r a m m i n g e . R e p o r t s

How to debug reports with page security

You can simulate the effects of viewing a report that uses page security by using report design properties to specify:

■ Access control lists, sets of users who share the same privilege levels

■ Whether the users have permissions to view the reports with full read privilege

You can specify up to four sets of users in access control lists for your simulated page security runs. You build the report, select the access control list, and observe the page security effects when you view the report.

If you do not choose an access control list, page security does not apply. You will be able to view the entire report.

1 Open the secure report design in e.Report Designer Professional and build the report.

2 Choose Report➛Design Properties.

Design Properties appears.

Design Properties consists of two sections, the Parameters section, and the Simulated Page Security Viewing section.

3 Enter the required data in Simulated Page Security Viewing.

1 If the users have full read privileges, choose View with Full Read privilege.

2 User1, User2, User3, and User4 represent access control lists. Specify the set of user names for users who share the same privilege levels in your database. Separate the user names with commas as shown in the following illustration.

C h a p t e r 7 , D e b u g g i n g a r e p o r t 121

You do not have to specify users for all four access control lists.

4 Select an access control list for the simulation run. Choose OK.

5 Observe the effects in the secure report:

1 Choose Report➛View from the menu bar.

The report appears.

2 Choose View➛Table of Contents.

The report’s table of contents appears.

3 Note the available pages for this set of users. Determine whether the available pages correspond to the users’ privilege level.

122 P r o g r a m m i n g e . R e p o r t s

How to save parameters for successive debugging runs

You can avoid having to enter parameters for successive test runs of a report application by saving the test parameters to a report object value (.rov) file. Use the Report Debug Options dialog to specify that e.Report Designer Professional reads the parameters from the ROV.

To set up the parameters for successive debugging runs:

1 Open the report in e.Report Designer Professional.

2 Choose Report➛Build and Run.

Requester appears.

3 Specify the parameters to use for debugging and choose Save As.

Specify Parameter File Name appears.

4 Choose the ROV:

1 Type the full path name of the of the report parameter file.

2 Select the check box for Use this parameter file instead of prompting. Selecting this check box ensures that e.Report Designer Professional uses the report parameter file to provide the report application’s parameters.

3 Choose Save.

e.Report Designer Professional saves the report parameter file to the specified path name.

To set the Report Debug options:

1 Choose Report➛Design Properties.

Design Properties appears.

2 Select Read from a File. Type the full path name for the ROV or choose Browse to locate the file.

If you use Browse, click Open after selecting the ROV to display the file name in Design Properties.

3 Choose OK.

When you choose Build and Run, Requester closes. The report runs using the parameters in the ROV.

C h a p t e r 7 , D e b u g g i n g a r e p o r t 123

Controlling program executionUsing e.Report Designer Professional’s debugging tools, you can control whether Actuate Basic executes a single line of code, an entire method, or a larger program block. By specifying when the program should run and when it should pause, you can move quickly over the areas you know work correctly and focus on the areas that require attention. The following sections describe how to control program execution.

Running to a breakpointUse breakpoints to pause program execution at specific locations so you can see what is happening. For example, if you have a complex method that is not working and you do not want to trace through each line, set a breakpoint at the beginning of the method. When Actuate Basic encounters a breakpoint, it suspends execution just before the line with the breakpoint. You can then use the other debugging tools to inspect the state of the method or trace execution line by line from that statement.

To set and clear breakpoints:

1 In Method Editor or Actuate Basic source file window, place the insertion point on the line of code where you want to set or clear a breakpoint.

2 Take one of the following actions:■ Press F9.■ Choose Debug➛Toggle Breakpoint.

■ Choose the Breakpoint icon on the toolbar.

A red dot appears to the left of the line of code to indicate that a breakpoint has been set. Clearing a breakpoint removes the red dot.

Stepping through codeSetting a breakpoint helps you get to and stop at the location where you suspect a problem occurs. Once there, you can step through your code and execute it line by line to monitor the effect of each statement. When you step through code, Actuate Basic executes the current statement, advances to the next statement, and suspends execution.

There are two ways to step through code:

■ Step into each line of code, including code in called procedures

■ Step over code in called procedures

124 P r o g r a m m i n g e . R e p o r t s

In a debugging session, you typically use both techniques, depending on which portions of code you want to analyze at any given time. For example, if you are stepping through method A and method A calls method B, you can step over method B if you have already determined that method B is bug-free. When you step over method B, Actuate Basic executes it as one unit instead of stopping after each line in method B. Conversely, you step into a called procedure if you are not sure the code is executing properly.

By stepping through code, you can observe how the Factory service generates a report. You can trace through the Actuate Basic source files that make up the Actuate Foundation Classes, and determine the sequence of method calls the Factory service makes to create the report.

How to step into procedures

Take one of the following actions to step into a procedure:

■ Press F8.

■ Choose Debug➛Step Into.

■ Choose Step Into on the toolbar.

How to step over procedures

Take one of the following actions to step over a procedure:

■ Press F10.

■ Choose Debug➛Step Over.

■ Choose Step Over on the toolbar.

Resuming code executionAfter suspending code execution with a breakpoint, you can step through each line of code as described in the previous section, or resume code execution at full speed until the next breakpoint or until the end of the program. If there are parts of the code you do not want to debug, it is more efficient to execute those portions normally.

To resume code execution, take one of the following actions:

■ Press F5.

■ Choose Debug➛Continue.

■ Choose Continue on the toolbar.

C h a p t e r 7 , D e b u g g i n g a r e p o r t 125

Stopping code executionYou can stop code execution at any time. When you do so, Actuate Basic clears the program from memory. You cannot resume code execution or debugging once you stop code execution.

To stop code execution, take one of the following actions:

■ Press Shift+F5.

■ Choose Debug➛Halt.

Examining variable valuesThe ability to examine the value of a variable is essential in debugging a report. For example, you can track the value of a variable in a data row as each Fetch( ) method executes or inspect the property variables of a component as they instantiate. Using e.Report Designer Professional’s debugging tools, you can monitor the values of variables as they change during code execution or check the value of a specified variable.

Monitoring a variable as its value changesTo monitor variables during code execution, use the Variables window. The Variables window shows the values of all current variables, organized by the following scopes:

■ Global. A global variable is accessible to the whole report. For example, the variables that store the names of the report object executable (.rox) file and report object instance (.roi) file are global.

■ Local. A local variable is a variable declared within the method currently executing.

■ Instance. An instance variable is accessible to an object. For example, if the current object is a frame, its instance variables can include the BackgroundColor, BackgroundIsClear, and BorderStyle variables.

The set of variables that appears in the Variables window changes depending on the portion of code that is executing. As you step through the code, you will notice that the information in the Variables window is updated continuously.

126 P r o g r a m m i n g e . R e p o r t s

How to open the Variables window

Choose Debug➛Variables Browser.

Interpreting the icons in the Variables windowThe icons in the Variables window indicate the different types of variables.

Variable or array of a fundamental data type such as string or integer.

Structure. For information about structures, see “Using a structure,” in Chapter 15, “Understanding variables and data types.”

Object reference variable. For information about object reference variables, see Chapter 3, “Working with an object.”

Tracing object reference variables In Actuate reports, objects typically contain object reference variables that contain references to other objects. For example, a control has an object reference variable called Container that contains a reference to the object the control is contained within. A frame has several object reference variables, including Container, DisplayContainer, and ContentList, that contain references to the frame’s container object in the content hierarchy, the frame’s container in the display hierarchy, and the frame’s contents, respectively.

A feature of the Variables window is the capability to see the contents of object reference variables and see how these variables point to other objects as the report is being generated. The following illustration shows how you expand successive levels of object reference variables to trace through a control’s container and the list of controls in the container.

Global variables

Local variables

Instance variables

C h a p t e r 7 , D e b u g g i n g a r e p o r t 127

Checking the value of a specific variableWhile you can monitor the values of variables in the Variables window, you might find it more convenient to specify the variable containing the value you want. To do so, use the Watch window.

If the variable you want to check is a local or instance variable, the code must be in that context. For example, if the code being traced is in Method A, you can only check variables associated with that method. You can, however, always check the values of global variables.

Control has a variable that contains a reference to its container frame

Object in current code context

Use and to show and hide nested levels of object reference variables

128 P r o g r a m m i n g e . R e p o r t s

How to check the value of a specific variable

To check the variable containing a specific value:

1 From the source code, select the variable containing the value you want to check.

2 Choose Ctrl+C to copy the selected text.

3 Choose Alt+F9 or choose Debug➛Watch.

Watch appears. The variable you copied in step 2 appears in the first text box, and the variable’s value appears in the second text box.

Viewing the stack of method callsAs you step through code execution, Actuate Basic keeps track of the method calls up to the current line. You can view this information in the Stack window. Each line in the Stack window indicates the method name and line number of the method in the source file. You can double-click any of the lines in the Stack window to get to the method in the source code.

A line in the Stack window that is highlighted in yellow shows the location where code execution is suspended. A line highlighted in green shows the current context, that is, where you last double-clicked to display the method in the source code. Variables in the Variables and Watch windows reflect the current context.

The following illustration shows how the contents of the Stack, source code, and Variables windows are related when code execution is suspended.

C h a p t e r 7 , D e b u g g i n g a r e p o r t 129

Actuate Basic sets a run-time stack limit of 200. A report that exceeds this limit causes a fatal error in e.Report Designer Professional and e.Report Designer. A report using recursion with a large number of iterations can exceed this limit.

How to open the Stack window

Choose Debug➛Call Stack.

Last line executed

Last method called before code execution was suspended

Variables associated with AcODBCConnection

130 P r o g r a m m i n g e . R e p o r t s

C h a p t e r 8 , D e s i g n i n g a r e p o r t w i t h p a g e - l e v e l s e c u r i t y 131

C h a p t e r

Chapter 8Designing a report withpage-level security

This chapter contains the following topics:

■ About personal views

■ About page-level security

■ Designing a report with page-level security

■ Testing a report design security example

■ Testing a security requirement example

■ Customizing the Security ID

■ Customizing the Access Control List

■ About the secure read privilege

132 P r o g r a m m i n g e . R e p o r t s

About personal viewsA manager can control access to the data in a large report by creating personal views of the data. A personal view is a subset of pages visible to an individual user. For example, the report illustrated here consists of six pages. Some report users can see all pages and some users can see only a subset of pages.

This report contains a list of customers in a sales region. The VP user can access every page in the report and can see the name of every customer in the region. The state managers, CTMgr and MAMgr, can see only the names of customers in their states. User CTMgr can access pages 1, 2, and 3. User MAMgr can access pages 4, 5, and 6. The sales representatives can access only one page and can see only the names of their customers.

About page-level securityPage-level security supports controlling access to a report page user by user. In a report with page-level security, a report user can view, search, and print only pages to which he or she has access or pages that do not use page-level security. Using page-level security, you can create a single report object instance (.roi) file that presents different subsets of pages to different report users.

Page-level security is available only for reports published on the Actuate iServer and viewed in a web browser using the DHTML viewer. You can test a report with page-level security in e.Report Designer Professional. Page-level security is not available for documents viewed with the Actuate Viewer or ActiveX controls.

VPCTMgr

VPCTMgrRep1102

1 2

VPCTMgrRep1337

3

VPMAMgr

4

VPMAMgr

5

Rep1002

VPMAMgr

6

Rep1076

C h a p t e r 8 , D e s i g n i n g a r e p o r t w i t h p a g e - l e v e l s e c u r i t y 133

Page-level security works by comparing the report user’s Security IDs (SIDs) to the Access Control List (ACL) for a page in the report. If any of the report user’s Security IDs matches any Security ID on the page’s Access Control List, the report user has access to the page.

About the Security IDA Security ID is a report user’s alias that is used for page-level security. A Security ID can be based on any of the following items:

■ The user’s name

■ An iServer security role assigned to the user

■ A name provided by the Report Server Security Extension (RSSE)

■ A name provided by a report-specific function

iServer maintains a list of user Security IDs, other than names provided by report-specific functions, for the entire login session. Report-specific Security IDs are valid only for the report that defines them. For more information about report-specific Security IDs, see “Using GetUserACL( ) to create a Security ID,” later in this chapter.

For more information about the Report Server Security Extension, see Chapter 3, “Configuring the Actuate server,” in Administering Actuate iServer System.

About the Access Control ListThe Access Control List for a page is determined by the Access Control List for the section that creates the page. The Access Control List for a section is the list of Security IDs returned by the section’s Security➛GrantExp property plus the Access Control Lists for any sections that contain the section. When the report runs, Actuate software places a page break between sections that have different Access Control Lists. For more information about the Access Control List, see “Customizing the Access Control List,” later in this chapter.

134 P r o g r a m m i n g e . R e p o r t s

About the GrantExp property for a secure reportThe following illustration shows the design for the report discussed in the topic “About personal views,” earlier in this chapter. For each section in the report, the Security➛GrantExp property returns one or more Security IDs that determine which users can access the pages in the section. If a user can access a section, he or she can access any subsections within that section. For example, a user with the Security ID VP can access the report section and the group sections StateGroup and RepSection. For information about overriding this behavior, see “Using the GetFullACL( ) method,” later in this chapter.

For more information about GrantExp, see “How to grant access to the pages in a section,” later in this chapter.

Viewing a report with page-level securityWhen a report user views a report with page-level security, iServer determines which pages to display by comparing the user’s Security IDs and the Security IDs in each page’s Access Control List. You can use the Report Server Security Extension to add Security IDs that are based on external security information, as shown in the following illustration.

GrantExp = [State] & "Mgr"

GrantExp = "Rep" & CStr( [repID] )

GrantExp = "VP"

C h a p t e r 8 , D e s i g n i n g a r e p o r t w i t h p a g e - l e v e l s e c u r i t y 135

Designing a report with page-level securityTo design a report with page-level security, perform the following tasks:

■ Determine which report users can access each section of the report:■ Determine the security requirements for the pages in each section.■ Identify the Security IDs that grant access to these pages.■ Determine how to correlate these Security IDs with values in the

database that contains the report data.

■ For each section, set the Security➛GrantExp property to return the appropriate Security ID or list of Security IDs. If a section has no security requirements:■ Do not set GrantExp.■ Ensure that the section does not inherit Security IDs from a container

section by overriding the GetFullACL( ) method.

■ Using the page number control, number the pages in the report based on the set of pages visible to the report user.

GrantExp

Access Control List

(one per page)

iServer

User’s Security

IDs

List of visible pages

Report

Encyclopediavolume

RSSE

Report data

Security data

136 P r o g r a m m i n g e . R e p o r t s

■ Test the report design using the Report Settings page of Design Properties in e.Report Designer Professional. Access Design Properties by choosing Report➛Design Properties.

■ Debug the report design.

How to grant access to the pages in a section

1 Double-click a section in the structure pane.

Component Editor appears.

2 Enter a value for the Security➛GrantExp property.

C h a p t e r 8 , D e s i g n i n g a r e p o r t w i t h p a g e - l e v e l s e c u r i t y 137

GrantExp can return a single Security ID or a list of Security IDs separated by commas. GrantExp must be an Actuate Basic expression and must evaluate to a string. If necessary, use the CStr function to convert the expression to the String data type. GrantExp can reference database columns and use string functions.

3 Choose Close.

How to number pages in a report using page-level security

In a report using page-level security, you can number pages sequentially or you can number them relative to the total number of pages in the report. Relative numbering ensures that a page displays the same page number for every report user. Relative page numbering is useful when many users share a report and they need a convenient way to refer to the pages in the report.

To number the pages in a report sequentially, use the page number control and set the PageNumberType property to VisiblePageNumber. VisiblePageNumber displays the page number relative to the set of visible pages for the report user. For example, if the report user can see four pages of a report, the second of the four pages is Page 2.

To number the pages in a report relative to the total number of pages in the report, use the page number control. Set the PageNumberType property to ActualPageNumber. ActualPageNumber displays the same page number on a page for every report user.

1 Drag a page number control from the Pages palette and drop it in the page.

2 Component Properties appears.

138 P r o g r a m m i n g e . R e p o r t s

3 Choose VisiblePageNumber or ActualPageNumber from the PageNumberType drop-down list.

4 Choose OK.

How to test a report design that uses page-level security

You can test a report design that uses page-level security by creating a simulated report user and assigning one or more Security IDs to the user. When you view the report in e.Report Designer Professional, the result is the same as when a report user with the specified Security IDs runs the report in the Encyclopedia volume.

1 Choose Report➛Build and Run.

The report appears with page-level security disabled.

2 Choose File➛Close.

3 Choose Report➛Design Properties.

Design Properties appears.

4 In Report Settings, choose View with full Read privilege to view the report without page-level security or choose one of the four simulated report users.

5 If you choose one of the simulated report users, enter one or more Security IDs for the user.

C h a p t e r 8 , D e s i g n i n g a r e p o r t w i t h p a g e - l e v e l s e c u r i t y 139

6 Choose OK.

7 Choose Report➛View.

The report appears.

8 Verify that the report is correct. If you chose one of the simulated report users, the report contains only pages that the simulated user can access.

How to debug a report design that uses page-level security

When you debug a report design that uses page-level security, display the Access Control List for each page in the report and the Security IDs for the current report user.

To display the Access Control List:

1 Drag a text control from the palette and drop it in the page.

Component Properties appears.

2 Set ValueExp to GetPageList( ).GetCurrentPageACL( ).

140 P r o g r a m m i n g e . R e p o r t s

To display the report user’s Security IDs:

1 Double-click the top-level report component.

Component Editor appears.

2 In the Variables page, choose New.

Class Variable appears.

3 Create the variable CurrentUserACL.

4 Override the report component’s GetUserACL( ) method as shown in the following example:

Function GetUserACL( acl AS String ) As StringGetUserACL = Super::GetUserACL( acl )

'Get the list of security IDs fo rthe userCurrentUserACL = GetUserACL

End Function

5 Drag a text control and drop it into the page.

6 Override the text control’s GetText( ) method as shown in the following example:

Function GetText( ) As String'Displays a list of security IDs for the user'Uses custom variable CurrentUserACL and'Overridden GetUserACL in the report component

GetText = GetValue( GetReport( ), "CurrentUserACL" )End Function

If the report is viewed with secure read privilege, the GetText( ) function returns a list of Security IDs for the current user. If the report is viewed with standard read privilege, the GetText( ) function returns nothing.

C h a p t e r 8 , D e s i g n i n g a r e p o r t w i t h p a g e - l e v e l s e c u r i t y 141

To ensure better performance when designing a secure report of more than 10,000 pages, set up the table of contents (TOC) to limit the number of entries at the first level to approximately 100. For information about changing the TOC properties, see “Class AcReportComponent” in Chapter 3, “AFC classes,” in Actuate Foundation Class Reference.

Testing a report design security exampleThis section examines the security implementation in a report.

Understanding the security scenario exampleThe report design in the following illustration generates a list of customers grouped by state and by sales representative. A state manager can access pages that list customers in his or her state. A sales representative can access pages that list his or her customers. The Encyclopedia volume has security roles for each state manager and each sales representative. For example, the security role for the Massachusetts state manager is MAMgr and the security role for sales representative 1102 is Rep1102. These security roles serve as Security IDs. The Security IDs are correlated with the report data using database columns, as described in “Examining the GrantExp property for the security example,” later in this chapter.

The report design has an outer group section, StateGroup, and an inner group section, RepSection.

142 P r o g r a m m i n g e . R e p o r t s

Examining the report component for the security exampleThe variable CurrentUserACL is declared on the report component SecureReport.

The report component’s GetUserACL( ) method is overridden as shown in the following illustration.

Reviewing the query for the security exampleThe following illustration shows the SQL tab of Query Editor for the example report.

C h a p t e r 8 , D e s i g n i n g a r e p o r t w i t h p a g e - l e v e l s e c u r i t y 143

Examining the GrantExp property for the security exampleThe Security➛GrantExp property for StateGroup is set to [State] & "Mgr". [State] is a database column. For each value of [State] in the database, GrantExp returns a Security ID that corresponds to a security role in the Encyclopedia volume. For example, for MA, GrantExp returns MAMgr.

The GrantExp property for RepSection is set to "Rep" & CStr( [repID] ), where [repID] is a database column. For each value of [repID] in the database, GrantExp returns a Security ID that corresponds to a security role in the Encyclopedia volume. For example, for 1102, GrantExp returns Rep1102. The CStr function converts the expression to the String data type.

144 P r o g r a m m i n g e . R e p o r t s

Examining the page layout for the security exampleThe page layout contains a label control, two text controls, and four page number controls.

The label control is the title, Page Security Example. One text control displays the page’s Access Control List at the top of each page of the report. This text control’s ValueExp property is set to GetPageList( ).GetCurrentPageACL( ).

The page number controls display the visible page count, visible page number, actual page count, and actual page number for each page of the report. The page number controls’ PageNumberType property determines which number appears. For example, for the visible page number, the PageNumberType property is VisiblePageNumber.

C h a p t e r 8 , D e s i g n i n g a r e p o r t w i t h p a g e - l e v e l s e c u r i t y 145

The other text control displays the report user’s Security IDs at the bottom of each page of the report if the report is viewed with secure read privilege.

This text control’s GetText( ) method is overridden.

Examining the report security exampleUsing the Report Settings page of Design Properties, you can view the report without page-level security or as a simulated report user. In this example, there are two simulated report users, User 1 and User 2. User 1 has one Security ID, MAMgr. User 2 has one Security ID, Rep1102. Both Security IDs correspond to security roles in the Encyclopedia volume.

146 P r o g r a m m i n g e . R e p o r t s

How to view the report without page-level security

To view the report without page-level security, choose View with full read privilege.

When you view the report using the read privilege, the visible page count is the same as the actual page count.

How to view the report as User 1

To view the report as User 1, choose User 1 in the Report Settings page of Design Properties.

C h a p t e r 8 , D e s i g n i n g a r e p o r t w i t h p a g e - l e v e l s e c u r i t y 147

The visible page count is less than the actual page count. The report contains only pages whose Access Control List includes the Security ID MAMgr.

User 1’s Security ID appears at the bottom of each page.

148 P r o g r a m m i n g e . R e p o r t s

How to view the report as User 2

To view the report as User 2, choose User 2 in the Report Settings page of Design Properties.

The visible page count is less than the actual page count. The report contains only the page whose Access Control List includes the Security ID Rep1102.

User 2’s Security ID appears at the bottom of the page.

C h a p t e r 8 , D e s i g n i n g a r e p o r t w i t h p a g e - l e v e l s e c u r i t y 149

Testing a security requirement exampleThe example report design in this section includes information about product sales for each customer. Product managers can access information about products for which they are responsible, regardless of the state or the sales representative. The Encyclopedia volume has security roles for each product. For example, the security role corresponding to the 8-bit programmable controller, item code MP1608s, is ProdMP1608s. Each product manager is assigned the security roles that correspond to his or her products.

For another example of a report design that uses page-level security, see \Program Files\Actuate7\ErdPro\Examples\PageSecurity\Securedetail.rod.

Examining the report design and GrantExp propertyThe following illustration includes values for the Security➛GrantExp property for StateGroup, RepSection, and ProductGroup. The GrantExp property for ProductGroup is "Prod" & [items.itemcode]. [items.itemcode] is a database column. For each value of [items.itemcode] in the database, GrantExp returns a Security ID that corresponds to a security role in the Encyclopedia volume. For example, for MP1608s, GrantExp returns ProdMP1608s.

150 P r o g r a m m i n g e . R e p o r t s

In this example, there is a third simulated report user, User 3. User 3 has one Security ID, ProdMP1608s. This Security ID corresponds to a security role in the Encyclopedia volume.

How to view the report as User 3

To view the report as User 3, choose User 3 in the Report Settings page of Design Properties.

GrantExp = [State] & "Mgr"

GrantExp = "Rep" & CStr( [repID] )

GrantExp = "Prod" & [items.itemcode]

C h a p t e r 8 , D e s i g n i n g a r e p o r t w i t h p a g e - l e v e l s e c u r i t y 151

The visible page count is less than the actual page count. The report contains only pages whose Access Control List includes the Security ID ProdMP1608s.

Customizing the Security IDA Security ID can be the user’s user name or a security role with which the user is associated. A Security ID can also be a name provided by the Report Server Security Extension (RSSE) or by a report-specific function.

152 P r o g r a m m i n g e . R e p o r t s

Using GetUserACL( ) to create a Security IDYou can create a report-specific Security ID using AcReport::GetUserACL( ). A report-specific Security ID is valid only for the report that defines it.

For example, assume the Encyclopedia volume defines the security roles Eastern Manager and Product Category 12. In your report, certain pages are visible only to users who have both security roles. Using the GetUserACL method, you can create a new Security ID, Eastern Manager Product Category 12, to represent users who have both security roles. Set the Security➛GrantExp property for the appropriate sections to return an Access Control List that contains the Security ID Eastern Manager Product Category 12.

Function GetUserACL( acl As String ) As StringDim tail As StringDim mgr As StringDim prod As StringDim posn As IntegerDim sid As String

' Loop to get each SID and check whether we want it.

tail = aclDo While tail <> ""

posn = InStr( tail, "," )If posn = 0 Then

sid = Trim$( tail )tail = ""

Elsesid = Trim$( Left$( tail, posn - 1 ) )tail = Trim$( Mid$( tail, posn + 1 ) )

End If

' Check whether it is a manager SID or a product' category SID.

If InStr( sid, "Manager" ) > 0 Thenmgr = sid

ElseIf InStr( sid, "Product Category" ) > 0 Thenprod = sid

End IfLoop

' Build the special ACL, and add it to the list.

If mgr <> "" And prod <> "" Thenacl = acl & ", " & mgr & " " & prod

End IfGetUserACL = acl

End Function

C h a p t e r 8 , D e s i g n i n g a r e p o r t w i t h p a g e - l e v e l s e c u r i t y 153

Customizing the Access Control ListYou can customize the Access Control List using the Security➛CascadeSecurity property, the GetFullACL( ) method, or the SetSecurity( ) method.

Using the CascadeSecurity propertyBy default, a user who can access a report section also can access any subsections within that section. You can override this behavior by setting the section’s Security➛CascadeSecurity property to false. When CascadeSecurity is false, the Access Control Lists for subsections do not contain the Security IDs specified by the container section’s GrantExp property.

Using the GetFullACL( ) methodIf you override GetFullACL( ), the Access Control List for the subsection contains only the Security IDs specified by the subsection’s GrantExp property.

Function GetFullACL( ) As StringGetFullACL = GetComponentACL( )

End Function

Using the SetSecurity( ) methodActuate e.Report Designer Professional generates code for the Security➛GrantExp property with the SetSecurity( ) method on AcSection. If you override this method, your code must assign the result to the ACL variable in the section. Actuate e.Report Designer Professional ignores the value of GrantExp for the section.

For example, assume you want to grant access to a group section depending on the account type. Assume also that the account types in the database that contains the report data do not correspond to the security roles defined in the Encyclopedia volume. You can override SetSecurity( ) as shown in the following example:

Sub SetSecurity( row As AcDataRow )Dim myRow As MyDataRow

Set myRow = rowIf myRow.AccountType = "Commercial" Then

ACL = "MajorAccts"ElseIf myRow.AccountType = "Private" Then

ACL = "PrivateBanking"Else

154 P r o g r a m m i n g e . R e p o r t s

ACL = "Accounting"End If

End Sub

Alternatively, you can create an Actuate Basic function to map the account types to the security roles and call this function from GrantExp. For example, if the name of the function is MapAcctTypes(row), you can set the Security➛GrantExp property as shown in the following illustration:

The following illustration shows the code for the function MapAcctTypes(row):

Function MapAcctTypes( row As AcDataRow ) As StringDim myRow As MyDataRow

Set myRow = rowIf myRow.AccountType = "Commercial" Then

MapAcctTypes = "MajorAccts"ElseIf myRow.AccountType = "Private" Then

MapAcctTypes = "PrivateBanking"Else

MapAcctTypes = "Accounting"End If

End Function

About the secure read privilegeFor page-level security to take effect, you must publish the report on iServer and the report user must have secure read privilege to the report. If the report is on the client machine or the report user has standard read privileges, page-level security is not in effect.

For more information about the secure read privilege, see Chapter 9, “Managing Encyclopedia volume security,” in Administering Actuate iServer System.

C h a p t e r 9 , P r o g r a m m i n g f o r r e p o r t v i e w i n g e v e n t s 155

C h a p t e r

Chapter 9Programming for reportviewing events

This chapter contains the following topics:

■ About report viewing events

■ Creating a context menu

■ Providing help

156 P r o g r a m m i n g e . R e p o r t s

About report viewing eventsReport viewing events occur in the ActuateViewer. A user triggers these events when he or she selects an object, presses or releases the mouse button, or chooses Help. When you program a report to respond to these events, the resulting action can be displaying context-sensitive help, displaying a custom context menu, and so on.

This chapter includes references to overriding Actuate’s methods for viewing events. You can override a method in a visible component only when the report user will view the document in an Actuate native format.

Objects that respond to report viewing eventsYou can manage viewing events for the following objects:

■ Frames

■ Controls

■ Graphs

■ Pages

■ Flows

Mouse eventsA visual object in a report can respond to the following four mouse actions:

■ Mouse button down (press)

■ Mouse button up (release)

■ Click (Mouse button down plus mouse button up)

■ Double-click

C h a p t e r 9 , P r o g r a m m i n g f o r r e p o r t v i e w i n g e v e n t s 157

The following table summarizes the methods associated with mouse events and the default action the methods execute in response to each event.

For more information about each mouse event method, see Class AcVisualComponent in Chapter 3, “AFC classes,” in Actuate Foundation Class Reference.

Responding to mouse eventsActuate Viewer responds to the OnLButtonDown and OnRButtonDown events. You can override the corresponding methods, either to augment the default functionality or replace it completely. e.Report Designer Professional’s default responses for OnLButtonDown and OnRButtonDown are standard responses for Windows applications. OnLButtonDown selects an object and OnRButtonDown displays a context menu.

When your report detects a mouse action, it calls the method associated with the corresponding event and passes four parameters to the method. You can use the information in those parameters to customize your report’s responses to the events.

The following table describes the four parameters the report sends to the mouse event methods when a mouse action occurs:

Mouse button Press Release Click Double-click

Left OnLButtonDown( )Default action: Selects the object

OnLButtonUp( )Default action: Nothing

OnLButtonClick( )Default action: Nothing

OnLButtonDblClk( )Default action: Nothing

Right OnRButtonDown( )Default action: Displays a context menu

OnRButtonUp( )Default action: Nothing

OnRButtonClick( )Default action: Nothing

OnRButtonDblClk( )Default action: Nothing

Parameter Description

View The window in which the report user view the report

Shift Indicates the state of the Alt, Ctrl, and Shift keys at the time of the mouse event

x The horizontal position of the mouse cursor at the time of the mouse event, measured in pixels relative to the left of the view

y The vertical position of the mouse cursor at the time of the mouse event, measured in pixels relative to the top of the view

158 P r o g r a m m i n g e . R e p o r t s

The Shift parameter gives you additional control over mouse events, as described in the next section.

About the Shift value in mouse event methodsThe Shift parameter contains one of the following values:

Using the Shift valueUsing the Shift value, you can assign different actions to the different key and mouse action combinations. For example, the OnLButtonDown( ) method assigns default functionality to key and mouse actions, as described in the following table.

The following example shows how AcVisualElement::OnLButtonDown( ) uses the different Shift values to implement different actions:

Keys Value Shift value

None 0 NoKeys

Shift 1 ShiftKey

Ctrl 2 ControlKey

Shift + Ctrl 3 ShiftKey Bor ControlKey

Alt 4 AltKey

Shift + Alt 5 ShiftKey Bor AltKey

Ctrl + Alt 6 CtrlKey Bor AltKey

Shift + Ctrl + Alt 7 ShiftKey Bor CtrlKey Bor AltKey

User action OnLButtonDown action

Press left mouse button on object Select the object and deselect other objects, if any were previously selected

Press left mouse button on object + press Shift key

Select the object, adding it to the set of previously selected objects, if any

Press left mouse button on object + press Ctrl key

Toggle the selection state of the object

Press left mouse button on object + press Shift + Ctrl keys

Toggle the selection state of the object

C h a p t e r 9 , P r o g r a m m i n g f o r r e p o r t v i e w i n g e v e n t s 159

Function OnLButtonDown( view As AcReportView, Shift As AcShiftKeyState, x As Integer, y As Integer ) As Boolean

Dim point As AcPointpoint.X = xpoint.Y = y

If Not Selectable ThenOnLButtonDown = FalseExit Function

End If

If view.IsSelected( me ) ThenIf Shift BAND ControlKey Then

OnLButtonDown = Trueview.SelectElement( me, False )

ElseOnLButtonDown = False

End IfElse

OnLButtonDown = TrueIf Not ( Shift BAND ControlKey Or Shift BAND ShiftKey ) Then

view.DeselectAllEnd Ifview.SelectElement( me, True )

End IfEnd Function

Creating a context menuA context menu contains commonly-used commands specific to a particular object or window. By default, when a user presses the right mouse button, the OnRButtonDown( ) method displays a context menu. The following illustration shows the methods Actuate Viewer calls to create a context menu when the right mouse down event occurs.

Context menus are only available when the user views the report in the Actuate Viewer.

OnRButtonDown( ) OnContextMenu( ) AddMenuCommands( )

Displays context menu Adds menu items to the context menu

160 P r o g r a m m i n g e . R e p o r t s

About default context menu itemsThe context menu displays two items that AddMenuCommands( ) creates as default values, Default Action and Help.

About the Default Action context menu itemWhen a user chooses Default Action from the context menu, the OnActuate( ) method executes and calls OnFollowLink( ).

Override OnFollowLink( ) to implement hyperlinks between objects. If you do not implement the hyperlink or do not assign a different action to OnActuate( ), nothing happens when users choose Default Action. For information about implementing hyperlinks, see Chapter 12, “Working with frames and controls,” in Developing Advanced e.Reports.

About the Help context menu itemWhen a user chooses Help from the context menu, the OnHelp( ) method executes and displays the help string you specify in the HelpText property. If you do not specify a help string, OnHelp( ) displays the following message:

There is no help for this item.

For information about how to implement context-sensitive help, see “Providing help,” later in this chapter.

About the Copy Link context menu itemWhen a user right-clicks on a hyperlink in a report, the context menu appears. The context menu for hyperlinks includes a Copy Link command, which copies the current hyperlink to the Windows clipboard. For information about implementing hyperlinks, see Chapter 12, “Working with frames and controls,” in Developing Advanced e.Reports.

AddMenuCommand( )Default Action

Help

OnActuate( )

OnHelp( )

Context menu

Default Action

Help

Context menu

OnActuate( ) OnFollowLink( )

C h a p t e r 9 , P r o g r a m m i n g f o r r e p o r t v i e w i n g e v e n t s 161

Customizing context menusIf you do not change or add code to OnRButtonDown( ), OnContextMenu( ), or AddMenuCommands( ), pressing the right mouse button causes the default context menu to display. Similarly, if you do not override OnActuate( ) or OnFollowLink( ), or if you do not set the LinkToExp property, Actuate Viewer performs the default action, nothing, when users choose Default Action.

The structure for creating context menus exists. It is up to you to implement the details. The following table provides examples of how to customize a context menu.

The following code illustration shows how to create a menu item for the context menu.

To... Override

Link one object to another and make this capability accessible through the Default Action menu item.

OnFollowLink( ) or set the LinkToExp property

Assign a different action to the Default Action menu item. For example, a more appropriate default action for a control that contains a sound file would be to play the sound.

OnActuate( )

Add menu items to the default context menu. AddMenuCommands( )

Omit the context menu. If you do not want to provide help or let users perform any actions through the context menu, it would be better to get rid of the menu altogether.

OnRButtonDown( )

Sub AddMenuCommands( menu As AcPopupMenu)' Execute the default processingSuper::AddMenuCommands( menu )

' Create a line to separate the new menu item from the previous item menu.AddSeparator

' Create the menu item menu.AddItem( "Evaluate Discount", me, "OnEvaluateDiscount" )End Sub

The name of the menu item as it appears in the context menu

The method to execute when users choose the menu item

162 P r o g r a m m i n g e . R e p o r t s

The following illustration shows the context menu the code creates.

Providing helpYou can provide two types of help for objects in a report:

■ Balloon help appears when the user hovers the cursor over an object.

■ Context-sensitive help appears when the user chooses the Help button or right-clicks and chooses Help from the context menu. Context-sensitive help is available only in the Actuate Viewer.

You can display different text for context-sensitive and balloon help.

Providing balloon helpBalloon help text appears when a user hovers 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:

■ Right-click an object in the report design and specify the help text to display by typing the string in the BalloonHelp property on the Properties page.

■ Override the BalloonHelp( ) method.

If you specify the text in BalloonHelp and then override the BalloonHelp( ) method, the return value of the method appears instead of the property string.

The following illustration shows how the string you type in BalloonHelp appears when a user hovers the cursor over a component.

Default Action

Help

Evaluate Discount

C h a p t e r 9 , P r o g r a m m i n g f o r r e p o r t v i e w i n g e v e n t s 163

Providing context-sensitive helpYou can provide context-sensitive help for any object in a report. Context-sensitive help appears only in the Actuate Viewer. It does not appear in a DHTML report. The HelpText property does not support Unicode and cannot display some languages. By default, the Actuate 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. The user positions the help icon over the object for which to obtain help, then presses the right mouse button.

3. The browser displays BalloonHelp

1. In Component Editor, type a string in the BalloonHelp property of the Status component

2. Hover the cursor over Status Status

In EvaluationClosedPending

Status of sales

164 P r o g r a m m i n g e . R e p o r t s

To provide context-sensitive help, right-click the object in the report design. In Properties, type the help text beside Windows Viewers Only➛HelpText, as shown in the following illustration.

The following illustration shows the method calls that implement context-sensitive help when a user presses the right mouse button.

The following illustration shows how the HelpText string appears when a user chooses Help.

AddMenuCommands( )

OnContextMenu( )OnRButtonDown( )

Displays context menu

Builds context menu with Help as a default menu item

Displays the string specified in HelpText

OnHelp( )

C h a p t e r 9 , P r o g r a m m i n g f o r r e p o r t v i e w i n g e v e n t s 165

3. Help text appears

1. In Component Editor, enter a string in the HelpText property of Status

2. Right-click Status then choose Help from the Context menu

Status

In EvaluationClosedPending

Default Action

Status of sales Closed, Pending, or in Evaluation

Help

166 P r o g r a m m i n g e . R e p o r t s

C h a p t e r 1 0 , U s i n g a n d c u s t o m i z i n g a s t o r e d p r o c e d u r e 167

C h a p t e r

Chapter 10Using and customizing astored procedure

This chapter contains the following topics:

■ About stored procedures

■ Designing a report with stored procedures

■ Working with stored procedures dialogs

■ Working with data from a stored procedure

■ Working with sample values for input parameters

■ About input and output parameters

■ About Oracle8 and Oracle9i stored procedures

■ Customizing a stored procedure

168 P r o g r a m m i n g e . R e p o r t s

About stored proceduresA stored procedure is a block of SQL statements that perform a specific task. A stored procedure is stored in the database and, like a standard procedure, it can be called by name from an application.

An Actuate report can call a stored procedure in a database that supports stored procedures, including ODBC, Oracle, Progress, and Sybase databases. Use of stored procedures improves database performance by reducing the amount of information sent over a network. You can use stored procedures to execute any database task, such as modifying, inserting, or deleting records, exchanging data between the database and an Actuate report, and so on.

Actuate e.Report Designer Professional supports the automated stored procedure features for the following databases:

■ ODBC databases, including PeopleSoft

■ Sybase databases connected by Sybase ctlib drivers

■ Oracle 8 and Oracle9i databases used with Oracle 8 and Oracle9i clients, respectively

■ Progress9 databases

■ IBM DB2 databases

About stored procedure result setsYou can work with a stored procedure in the following ways:

■ Use the automated design facilities in e.Report Designer Professional.

■ Override Actuate Basic methods to customize stored procedures.

This chapter covers both methods. In the first method, using Actuate e.Report Designer Professional, you log in to the database and view a list of stored procedure names in a browser. The Stored Procedure Data Source Builder supports stored procedures that return a single result set.

You also can process multiple result sets by overriding a method that modifies the SQL statement. For information about overriding a method to work with a stored procedures see “Customizing a stored procedure,” later in this chapter.

Using stored procedure toolsActuate e.Report Designer Professional provides a set of tools to work with stored procedures. These tools include:

C h a p t e r 1 0 , U s i n g a n d c u s t o m i z i n g a s t o r e d p r o c e d u r e 169

■ The stored procedure data stream component supports connecting to a data source that contains stored procedures. You can add this component to an existing report or insert it into the report design when you build a blank report.

■ Stored procedure component.

■ Stored Procedure Data Source Builder supports viewing and modifying details about the stored procedure.

To access this window, choose View➛Data Source in the Design Editor of a report that displays the stored procedure component in the data stream.

170 P r o g r a m m i n g e . R e p o r t s

■ Stored Procedure Browser.

Stored Procedure Browser opens when Stored Procedure Data Source Builder opens. Select a stored procedure and choose OK.

■ Stored Procedure Name Editor.

Stored Procedure Name Editor supports modifying the name of the stored procedure component. If you edit the name, be sure the stored procedure’s parameter and result columns are consistent with the new name.

■ Use Synchronize Stored Procedure With Schema to determine whether the content of a stored procedure in your design is consistent with its definition in the database. You can access this icon from the toolbar in Stored Procedure Data Source Builder.

■ Sample Parameter Values.

C h a p t e r 1 0 , U s i n g a n d c u s t o m i z i n g a s t o r e d p r o c e d u r e 171

Sample Parameter Values supports using a sample input value for a parameter with a stored procedure to help you define the boundaries of your report. You can access Sample Parameter Values by choosing View➛Parameter Sample Values in Store Procedure Data Source Builder.

Designing a report with stored proceduresA report with stored procedures requires a connection to a data source that contains the stored procedures. It also requires the Stored Procedure Source data stream. You can place this data stream in an existing report and you can insert it when you create a blank report.

For information about how to build a report using stored procedures, see “Working with stored procedures dialogs,” later in this chapter.

How to design a report with stored procedures

To build a new report that accesses and works with stored procedures from a database, do the following:

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

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

172 P r o g r a m m i n g e . R e p o r t s

3 Double-click the connection component to check the connection.

When you work with stored procedures, the database connection must access the data source that contains the procedures. If the connection is not the one you want, do the following:

1 Choose Tools➛Database Connection to modify your existing database connection properties or create a new connection.

2 Choose the appropriate option, and choose Next.

3 Respond to the prompts. Choose Finish.

e.Report Designer Professional connects to the database.

4 In Design Editor, right-click DataStream. Choose Delete.

C h a p t e r 1 0 , U s i n g a n d c u s t o m i z i n g a s t o r e d p r o c e d u r e 173

The DataSource is deleted from DataStream.

5 Drag Database Source from the Data palette and drop it in DataStream.

174 P r o g r a m m i n g e . R e p o r t s

6 In Select Component, select Stored Procedure Data Source. Choose OK.

You are now ready to work with your report. For more information, see “Working with stored procedures dialogs,” later in this chapter.

Working with stored procedures dialogsAfter your report design is set up in Design Editor, you can begin working with the stored procedures dialog.

1 In e.Report Designer Professional, choose View➛Data Source.

2 Depending on your database connection, Login might appear. If so, type any required information to log in.

3 In Stored Procedure Browser, which opens with Stored Procedure Data Source Builder, double-click the name of the stored procedure you want to use.

C h a p t e r 1 0 , U s i n g a n d c u s t o m i z i n g a s t o r e d p r o c e d u r e 175

In the following illustration, the stored procedure produces results in the Result Columns page. Some stored procedures, however, are internal functions that do not return data to users.

If any of the stored procedure’s result columns have the same name, Actuate e.Report Designer adds a suffix to each duplicate column name so that every column name is unique. For example, if two result columns have the name MYCOL, e.Report Designer renames one of them MYCOL_1.

176 P r o g r a m m i n g e . R e p o r t s

Working with data from a stored procedureAfter you build your report, access the stored procedure, and select a stored procedure, you can proceed with your report design. For information about setting up your Actuate report for stored procedures, see “Working with stored procedures dialogs,” earlier in this chapter.

1 Select the frame in the Content slot of your report design to make it active.

2 Choose View➛Field List.

The controls from the stored procedure are now available to drag from the list and drop into the frame of your report design.

The list of controls in the Field List matches the list in the Result Columns of the Stored Procedure Data Source Builder. The Field List shows the controls in alphabetical order. The Result Columns table shows them in the order defined in the stored procedure.

3 From the Field List, drag each item you would like to appear in your report and drop it into the Content frame.

Consult the designer of the stored procedure for the definitions of the result column fields.

4 Arrange controls in the frames. In Before and After frames, place the column headers and controls for totals.

5 Choose Report➛Build and Run.

C h a p t e r 1 0 , U s i n g a n d c u s t o m i z i n g a s t o r e d p r o c e d u r e 177

Depending on the stored procedure, you might be asked to enter an input parameter as the run begins. In this example, 3 is the value of the input parameter.

6 View your report.

You might want to verify that the stored procedure you are using has not changed since you first worked with it. For more information, see “Synchronizing the stored procedure design,” later in this chapter.

Synchronizing the stored procedure designStored procedures defined in your database can change between the time of the original report design and when you run them in a report. You can check to see whether the stored procedure design has remained constant by using the Synchronize procedure tool. To access the tool, choose SQL➛Synchronize Stored Procedure.

If the stored procedure definition is consistent, a message verifies that fact. If the design of the stored procedure has become corrupt or has changed since you originally used it, a message to that effect appears.

Narrowing a search and matching patterns in stored proceduresSubgroups of the stored procedures are available, as is the full list of stored procedures. A feature in Options on the Stored Procedure page supports narrowing the list of stored procedures. To work with this feature, take the steps:

178 P r o g r a m m i n g e . R e p o r t s

1 Choose View➛Options➛Stored Procedure.

2 In Stored Procedure, specify whether you want to view and work with user procedures, system procedures, or both.

If your database cannot distinguish between user procedures and system procedures, this feature is transparent.

3 You can narrow your list of stored procedures. Type a search expression for Stored procedure pattern match, such as:

"*Salary*"

The Stored Procedure Browser now lists only stored procedures with Salary in the name.

For information about search syntax, see Chapter 5, “Working with an information object for Actuate Query,” in Using e.Reports.

C h a p t e r 1 0 , U s i n g a n d c u s t o m i z i n g a s t o r e d p r o c e d u r e 179

Working with sample values for input parametersStored Procedure Data Source Builder prompts for parameter values if the stored procedure requires input parameters.

1 To determine whether the stored procedure uses parameters, choose Parameters in Stored Procedure Data Source Builder.

If parameters are used or required, the following information is available in Parameters:■ The name of the field from the stored procedure that uses a parameter

■ Whether the parameter is input or output■ The Actuate type, which could be any of the following:

- Integer- Double- DateTime- Currency - Text, which sometimes appears as String

If an input value for a stored procedure is needed to determine the result column, Sample Parameter Values appears.

180 P r o g r a m m i n g e . R e p o r t s

2 Type a parameter, such as 3, in the Value column.

Be aware that sometimes a stored procedure is designed to return different types of result sets, according to the input parameter value. The Stored Procedure Data Source Builder could determine the type of result set returned based on the sample parameter value(s). If so, use the same type of input value used in the Actuate report design when running the Actuate report. For more information about result sets, see “About stored procedure result sets,” earlier in this chapter.

About input and output parametersIf you are using ODBC, Actuate software sets parameters to the correct type. Some vendors’ database systems, such as those from Sybase, do not provide information about whether a stored procedure parameter is an input or output type. If this is the case, UNKNOWN might appear next to the parameter name in the Parameters page, under Input/Output. If UNKNOWN appears, you need to designate input or output parameters in the Stored Procedure Data Source Builder.

How to designate parameter types

To designate input or output parameter types for a stored procedure, do the following:

1 In Stored Procedure Data Source Builder, select a stored procedure using the browser.

C h a p t e r 1 0 , U s i n g a n d c u s t o m i z i n g a s t o r e d p r o c e d u r e 181

2 Choose Parameters and review the data there.

3 In the Input and Output column, indicate whether a parameter is an input parameter, an output parameter, or both.

The named field items you specify as input parameters appear in the Requester or Request page when the user runs the report.

e.Report Designer Professional generates the name of an input parameter variable. The name is usually the same as the parameter name in the stored procedure. e.Report Designer Professional then attempts to match the name of the input parameter variable with the following:■ A local parameter that you or e.Report Designer Professional define.■ An inherited parameter that you or e.Report Designer Professional

define.■ A global parameter that you define.

182 P r o g r a m m i n g e . R e p o r t s

If the parameter is not defined, e.Report Designer Professional defines a local parameter. If the name of the input parameter variable conflicts with the name of a variable that is not a parameter, e.Report Designer Professional appends an underscore and a number to the name, for example MYPARAM_1.

Output parameters are stored as variables on the stored procedure component.

About Oracle8 and Oracle9i stored proceduresThe Stored Procedure Data Source Builder supports Oracle8 and Oracle9i stored procedures and stored functions. You must execute a stored procedure or stored function to determine the columns in the result set. To execute a stored procedure or stored function, enter sample values for the input parameters in the Sample Parameter Values dialog. For information about Sample Parameter Values, see “About stored procedure result sets,” earlier in this chapter.

In some cases, a stored procedure or stored function returns different columns depending on the values of the input parameters and on how the stored procedure or stored function is defined. The columns in the result set, therefore, might not correspond to the controls in your report design. The Stored Procedure Data Source Builder supports a weak cursor type definition if it always returns the same set of result columns. A weak cursor allows the return type to be determined at runtime.

About stored functionsA stored function is a stored procedure that returns a function value. The returned value can have any data type supported by Oracle, and it can be a cursor variable. If a stored function returns a cursor variable, the Stored Procedure Data Source Builder can process the result set.

Using the Stored Procedure Browser The Stored Procedure Browser displays the type and scope of each stored procedure and stored function. A stored function is identified by the following icon:

A stored procedure or a stored function can be part of a packaged procedure. Its full name appears in the Stored Procedure Browser as qualifier.package.procedurename. The Oracle schema maps to the Actuate qualifier.

C h a p t e r 1 0 , U s i n g a n d c u s t o m i z i n g a s t o r e d p r o c e d u r e 183

Overriding the OpenCursor methodStored Procedure Data Source Builder supports only stored procedures and stored functions that return one result set. If a stored procedure or stored function has multiple cursor parameters defined, Actuate software processes the first cursor parameter and ignores the others. Actuate software can process a cursor parameter other than the first if the cursor parameter has a set of result columns that matches the default set displayed in the Stored Procedure Data Source Builder. To process a cursor parameter other than the first, override the AcStoredProcedureSource::OpenCursor method. The cursor parameter name must not include a colon (:).

Stored function

Stored procedure

184 P r o g r a m m i n g e . R e p o r t s

For information about processing multiple result sets, see “Customizing a stored procedure,” earlier in this chapter.

Understanding the data retrieval exampleThe report design in the following example uses the stored function REFCUR3.GETMGRDATA to retrieve data from the EMP table in the SCOTT database schema. The report user determines which data to retrieve by entering a value for the DEPTNO column as an input parameter in the request page.

About the EMP table in the exampleThe EMP table contains the following data.

About the stored function in the exampleThe code for the stored function REFCUR3.GETMGRDATA follows. This stored function defines two cursor parameters, EMPCURSOR and MGRCURSOR. The Stored Procedure Data Source Builder processes the first cursor, EMPCURSOR.

package refCur3 ascursor c1 is select ename, deptno from emp;cursor c2 is select ename, ename AS manager, hiredate from emp;type empCur is ref cursor return c1%ROWTYPE;type mgrCur is ref cursor return c2%ROWTYPE;

function GetMgrData(indeptno IN NUMBER,EmpCursor in out empCur,deptAcct OUT NUMBER )

RETURN mgrCur;END;package body refCur3 as

function GetMgrData(indeptno IN NUMBER,EmpCursor in out empCur, deptAcct OUT NUMBER )RETURN mgrCur is

C h a p t e r 1 0 , U s i n g a n d c u s t o m i z i n g a s t o r e d p r o c e d u r e 185

MgrCursor mgrCur;begin

open EmpCursor for select ename, deptno from emp where deptno = indeptno;open MgrCursor for select e.name, n.ename AS MANAGER, e.hiredatefrom emp n, emp ewhere e.mgr= n.empno and e.deptno= indeptno ;

deptAcct := indeptno + 100;return MgrCursor;

end;end;

The report structure is shown below.

Stored procedure component

Result columns

Oracle connection

186 P r o g r a m m i n g e . R e p o r t s

About the Stored Procedure Data Source Builder in the exampleThe Stored Procedure Data Source Builder displays the result columns and the parameters for the stored function REFCUR3.GETMGRDATA.

About parameters in the exampleActuate creates variables on the stored procedure component for the DEPTACCT and INDEPTNO parameters.

C h a p t e r 1 0 , U s i n g a n d c u s t o m i z i n g a s t o r e d p r o c e d u r e 187

The Actuate Basic code generated for the report design declares a CPointer parameter type for EMPCURSOR and assigns the cursor parameter to an Actuate cursor, AcDBCursor.

Class DataSource Subclass Of AcStoredProcedureSource

Dim DEPTACCT_output As DoubleStatic INDEPTNO As Double

Sub SetProperties ( )Super::SetProperties ( )ProcedureName = "REFCUR3.GETMGRDATA"OwnerName = ""QualifierName = "SCOTT"QualificationOption = "UNQUALIFIED"ReturnParameter = ":acProcStatus"ActualParameters = " :INDEPTNO , :EMPCURSOR , :DEPTACCT"CursorParameter = "acProcStatus"

End Sub

Sub BindStaticParameters( stmt As AcDBStatement )stmt.DefineProcedureInputParameter ( "INDEPTNO" , INDEPTNO )stmt.DefineProcedureOutputParameter ( "EMPCURSOR" ,

V_CPOINTER, NULL )stmt.DefineProcedureOutputParameter ( "DEPTACCT" , V_DOUBLE )stmt. DefineProcedureReturnParameter ( "acProcStatus" ,

V_CPOINTER )End Sub

Sub BindDataRow( cursor As AcDBCursor )cursor.BindColumn( 1, "NewReportApp::DataRow" , "ENAME" )cursor.BindColumn( 3, "NewReportApp::DataRow" , "HIREDATE" )

188 P r o g r a m m i n g e . R e p o r t s

cursor.BindColumn( 2, "NewReportApp::DataRow" , "MANAGER" )End Sub

Sub GetOutputParameters( cursor As AcDBCursor )DEPTACCT_output = cursor.GetOutputParameter( "DEPTACCT" )

End Sub

About the Requester in the exampleWhen a user runs the report, the Requester or Request page prompts the user to enter a value for the input parameter INDEPTNO. In the EMP table, the DEPTNO column contains the values 10, 20, and 30.

About the report in the exampleThe report displays the data in the result columns ENAME, MANAGER, and HIREDATE based on the value of INDEPTNO.

Customizing a stored procedureTypically, you use the Stored Procedure DataSource Builder in e.Report Designer Professional to create data sources that use a stored procedure as a source of data. In some cases, however, you work with stored procedures that return multiple data sets or with databases that the Stored Procedure DataSource Builder does not support. In these cases, you override certain methods in Actuate Basic to customize the way your application handles the stored procedures and their resulting data.

Accessing a stored procedureThe following are general steps for calling a stored procedure from an Actuate application:

1 Connect to the database.

C h a p t e r 1 0 , U s i n g a n d c u s t o m i z i n g a s t o r e d p r o c e d u r e 189

2 Create and prepare the statement to execute the stored procedure using the connection’s Prepare( ) method.

3 If you are passing a value or values to the stored procedure, define the procedure input parameters using the statement’s DefineProcedureInputParameter( ) method. Do not embed the input parameter definitions in the statement itself.

4 If you are getting a value or values from the stored procedure:

1 Define output parameters using the statement’s DefineProcedureOutputParameter( ) method.

2 Call the StartNextSet( ) method.

3 Execute the stored procedure using Execute( ).

4 Get the output parameter value or values using GetOutputParameter( ).

5 If the stored procedure returns rows:

1 Create a cursor using the statement’s AllocateCursor( ) method.

2 Bind the columns to data-row variables using the cursor’s BindColumn( ) method.

3 Create the data-row object using New( ).

4 Retrieve the rows using the cursor’s Fetch( ) method.

6 If the stored procedure returns a status, get the return status value using GetProcedureStatus( ).

Working with a Sybase stored procedure

The following example shows the code for a Sybase stored procedure and a section of a program written in Actuate Basic that passes input parameters to and retrieves rows from the Sybase database.

The following stored procedure takes an input parameter value and uses that value to determine which rows to retrieve. It returns output parameters and the procedure status:

/* Create the procedure inproc */create proc inproc

/* Declare the input parameter */@charin char(20)/* Declare the output parameters */@int_out int output, @charboy char(20) output

/* Specify which rows are to be fetched */as begin select id, name from syscolumns where name > @charin

190 P r o g r a m m i n g e . R e p o r t s

/* Assign values to output parameters */Select @charboy = "foobox"Select @int_out = 88/* Return procedure status */return 99

end

The following Actuate Basic code executes the stored procedure and supplies the input parameter value that the stored procedure uses to determine the set of rows to return to the Actuate Basic application:

' Prepare the statement and execute inprocSet statement = connection.Prepare("exec inproc")If statement Is Nothing Then

Print #1, "Failed to prepare statement."Exit sub

End If

' Define the procedure input parameter; pass the value "v” to the procedurestatement.DefineProcedureInputParameter("@charin", "v")' Define the procedure’s output parametersstatement.DefineProcedureOutputParameter( "@charboy", V_STRING )statement.DefineProcedureOutputParameter( "@int_out", V_INTEGER )

' Open a cursor, which is required when returning rowsSet cursor = statement.AllocateCursor( )If cursor Is Nothing Then

Print #1, "Failed to allocate cursor."Exit sub

End If

' Bind the database columns to data row variablesMsgBox ("binding" )cursor.BindColumn( 1, "syscolRow", "Id" )cursor.BindColumn( 2, "syscolRow", "theName" )MsgBox( "bound" )

' Create the data rowset sRow = New syscolRow( )

' Fetch rows from databasedo while cursor.Fetch( sRow )

MsgBox( "Name: " & sRow.theName & " Id: " & sRow.Id )loop

MsgBox( "Expecting false for next set: got: " & cursor.StartNextSet( ) )' Return the values of the stored procedure’s output parametersrpcParam1 = cursor.GetOutputParameter("@charboy")

C h a p t e r 1 0 , U s i n g a n d c u s t o m i z i n g a s t o r e d p r o c e d u r e 191

MsgBox( "Rpc param 1 is " & rpcParam1 )rpcParam2 = cursor.GetOutputParameter("@int_out")MsgBox( "Rpc param 2 is " & rpcParam2 )

'Display procedure status valueMsgBox( "Rpc return val is " & cursor.GetProcedureStatus( ) )set cursor = Nothing

connection.Disconnect( )

Working with an Oracle stored procedureThe following example shows the code in Actuate Basic that prepares, passes input parameters to, executes, and obtains output parameters from an Oracle stored procedure that does not return a cursor:

Function Start( ) As BooleanDim stmtText As StringDim stmt As AcDBStatementDim Conn As AcDBConnectionDim arg_in_date As Date, arg_out_date As Date, tempDate As Dat

Start = Super::Start( )Set Conn = GetConnection()stmtText = "BEGIN sp_date_test(:arg_in_date, :arg_out_date); END;"Set stmt = conn.Prepare(stmtText)If stmt Is Nothing Then

Exit FunctionEnd If

arg_in_date = CDate("01/01/2000")If stmt.DefineProcedureInputParameter("arg_in_date", arg_in_date) = 0Then

Exit FunctionEnd If

If stmt.DefineProcedureOutputParameter("arg_out_date", V_DATE) = 0 ThenExit Function

End If

If stmt.Execute() = 0 ThenstmtText = Conn.GetSpecificErrorText()Exit Function

End If

tempDate = stmt.GetOutputParameter("arg_out_date")

End Function

192 P r o g r a m m i n g e . R e p o r t s

Working with a stored procedure’s return valueThe following example shows the code for a stored procedure and a section of a program written in Actuate Basic that passes input parameters to and extracts the return value of the stored procedure.

The following stored procedure takes an input parameter value (a name) and uses that value to determine the value (the associated ID) to return to the Actuate application:

-- Create the procedure spfuncCREATE OR REPLACE FUNCTION spfunc ( p_name IN VARCHAR )-- Declare output parameterRETURN NUMBERAS

l_id NUMBER;-- Declare input parameterBEGIN

SELECT id INTO l_id FROM sproctable WHERE name = p_name;RETURN ( l_id );

END spfunc;/

Working with a stored procedure to return an IDThe following Actuate Basic code executes the stored procedure to determine the ID associated with a name. The code passes the input parameter value (the name) to the stored procedure. The stored procedure uses the name to determine its associated ID, and returns that ID to the Actuate Basic program:

Sub TestSPStatement( connection As AcDBConnection )Dim statement As AcDBStatementDim id As LongDim newId As LongDim name As Variant

' Prepare the statementSet statement = connection.Prepare("BEGIN :p_id := spfunc (:p_name);

END;" )If statement Is Nothing Then

PrintString ( "Failed to prepare statement." )PrintString ( connection.GetSpecificErrorText( ) )PrintString ( connection.GetGeneralErrorText( ) )Exit sub

End If

' Define the input parameter; pass the value "John Smith" to the procedurename = "John Smith"If statement.DefineProcedureInputParameter ( "p_name", name ) = 0 Then

C h a p t e r 1 0 , U s i n g a n d c u s t o m i z i n g a s t o r e d p r o c e d u r e 193

PrintString ( "Failed to define input parameter" )PrintString ( connection.GetSpecificErrorText( ) )PrintString ( connection.GetGeneralErrorText( ) )Exit sub

End If

' Define the output parameterIf statement.DefineProcedureOutputParameter ( "p_id", V_INTEGER ) = 0 Then

PrintString ( "Failed to define output parameter" )PrintString ( connection.GetSpecificErrorText( ) )PrintString ( connection.GetGeneralErrorText( ) )Exit sub

End If

' Execute spfunc procedureIf statement.Execute( ) = 0 Then

PrintString ( "Stored function spfunc execution failed." )PrintString ( connection.GetSpecificErrorText( ) )PrintString ( connection.GetGeneralErrorText( ) )

Else PrintString ( "Stored function spfunc execution success." )

End if

' Get the output parameter value, the id associated with "John Smith"newId = statement.GetOutputParameter ( "p_id" )Print #1, "Function Return Value - id = ", newId

End Sub

Accessing Sybase SQL Server multiple result setsActuate e.Report Designer Professional includes an example showing how to access multiple result sets for a stored procedure using native drivers. This example is available from the Examples directory in your e.Report Designer Professional installation.

The stored procedure returns three result sets:

■ The first select statement returns a result set with information about the name, owner, and type of the database object, the syslocks table.

■ The second select statement returns a result set that contains the name of the Data Segment the table is on and the date and time it was created.

■ The third select statement returns a result set with the name of the columns in the table and their type, length, and other miscellaneous information.

The example works with Sybase SQL Server. It shows the subclasses to create, as well as the methods to override, to process multiple result sets for an Actuate report. It includes the report design, library, and Actuate Basic files.

194 P r o g r a m m i n g e . R e p o r t s

Accessing Oracle8 and Oracle9i stored procedure multiple result setsThis section describes how to access multiple result sets returned by Oracle8 and Oracle9i stored procedures or stored functions. This section applies only to Oracle8 and Oracle9i runtime clients.

Actuate’s Stored Procedure DataSource Builder supports only stored procedures that return one result set. To process multiple result sets, you customize Actuate Basic methods. You use the stored procedure’s output parameter, declared as a cursor variable of type CPointer. You then open and fetch data rows from the cursor variable. Each cursor variable provides access to a single result set.

Before writing the custom Actuate Basic code to execute a stored procedure or stored function, you must know the definition of that procedure or function. The definition includes the data type of each parameter and the type of result set returned by a cursor variable. If you are processing multiple result sets, you must call the appropriate Actuate Basic methods for each result set’s cursor variable. You also must know the structure and definition of the stored procedure to write custom code to execute it and process its result sets.

Cursor variables can be of type strong or weak. A strong cursor specifies a return type with the exact table and columns or row structure to be returned. A weak cursor allows the return type to be determined at runtime.

A stored procedure or stored function returns different columns depending on the values of the input parameters and on how they are defined. If this is the case, the columns in the result set might not correspond to the controls in your report design.

Adding support in Actuate Basic methodsSpecify the call to the Oracle8 or Oracle9i stored procedure in the AcDBStatement::Prepare( ) method. For example:

stmtText = “BEGIN :mgrCursor := refcur3.GetMgrData (:DEPTNO, :empCursor, :deptAcct ); END;”Set stmt = New AcDBStatement ( GetDBConnection( ) )If Not stmt.Prepare( stmtText ) Then...

To declare an Oracle stored procedure’s output parameter for a result set:

AcDBStatement::DefineProcedureOutputParameter ("CursorParameterName", V_CPOINTER )

where CursorParameterName is the name of the output parameter, without the colon (:). Enclose the parameter name in double quotes.

C h a p t e r 1 0 , U s i n g a n d c u s t o m i z i n g a s t o r e d p r o c e d u r e 195

Assign the output parameter to an Actuate cursor, so you can use AcDBCursor methods to bind, open, and fetch data rows. For example:

AcDBStatement::AllocateCursor ( "CursorParameterName" )

where CursorParameterName is the name of the cursor parameter, without the colon (:). Enclose the cursor parameter name in double quotes.

Actuate Basic automatically closes any special cursor variables when you close the associated AcDBCursor. Note that these methods work only with a native Oracle8 or Oracle9i connection to an Oracle8 or Oracle9i run-time client.

Specify the expected return row structure of a cursor variable by calling AcDBCursor methods. For example:

AcDBCursor::BindColumn ( ColumnPositionID, DataRowClassName, DataRowVarName )

Oracle stored functions return a value. Use either of the following methods to access the stored function’s return value:

■ AcDBStatement::GetProcedureStatus( )

■ AcDBCursor::GetProcedureStatus( )

The return value’s data type is any data type supported by Oracle, except for REF_CURSOR. Actuate maps supported Oracle data types to Actuate data types.

If the return value is a REF_CURSOR, use:

AcDBStatement::AllocateCursor ( "CursorParameterName" )

where CursorParameterName is the name of the return parameter specified in the call to the stored function, without the colon (:).

Using the CPointer type with another stored procedure function

You cannot use the cursor variable CPointer type with the following methods:

■ AcDBStatement::GetOutputParameter( )

■ AcDBStatement::GetProcedureStatus( )

■ AcDBCursor::GetOutputParameter( )

■ AcDBCursor::GetProcedureStatus( )

The following example displays the names of department employees, the employees’ managers, and the employees' hire dates. Users enter the department number to display the data for that department. The example uses the Oracle sample database installed with the Oracle product.

The example shows the code for an Oracle stored function, and a section of the Actuate Basic program that calls it. The Actuate Basic program calls the Oracle stored function with two cursor parameters defined. One of the cursors is the function’s return value.

196 P r o g r a m m i n g e . R e p o r t s

Define the cursors as variables in a subclass of AcDatabaseSource. For example:

Dim theEmpCursor As AcDBCursorDim theMgrCursor As AcDBCursor

The example defines two variables in the DataStream-DataSource component:

■ INDEPTNO, an input parameter to specify the department number that the user enters

■ DEPTACCT_output, an output parameter that returns the department’s account number

Here is the Oracle stored procedure:

-- ref cursor stored function in scott/tiger database -- where a cursor is returned as a stored function value, in addition-- to a result set in the output parametercreate or replace package refCur3 as cursor c1 is select ename, deptno from emp; cursor c2 is select ename, ename AS manager, hiredate from emp; type empCur is ref cursor return c1%ROWTYPE; type mgrCur is ref cursor return c2%ROWTYPE; function GetMgrData(indeptno IN NUMBER,EmpCursor in out empCur,

deptAcct OUT NUMBER ) RETURN mgrCur;END; / create or replace package body refCur3 as function GetMgrData(indeptno IN NUMBER,EmpCursor in out empCur, deptAcct OUT NUMBER ) RETURN mgrCur is

MgrCursor mgrCur;begin open EmpCursor for select ename, deptno from emp

where deptno = indeptno; open MgrCursor for select e.ename, m.ename AS MANAGER, e.hiredate

from emp m, emp e where e.mgr= m.empno and e.deptno= indeptno;

deptAcct := indeptno + 100; return MgrCursor;end; end;

Fetching the data row

Override the Fetch( ) method to fetch rows from the MgrCursor variable:

C h a p t e r 1 0 , U s i n g a n d c u s t o m i z i n g a s t o r e d p r o c e d u r e 197

Function Fetch( ) As AcDataRow' Set Fetch = Super::Fetch( ) Set Fetch = myFetch( theMgrCursor )End Function

Calling the Oracle stored procedure with result sets

Add custom Actuate Basic code to call the stored procedure. Add the code in the DataStream-Data Source component of the report design.

The following code snippet declares the input and output parameters, the result set cursors, and calls the Oracle stored procedure:

Sub OracleSPSample( )

Dim stmtTextAs StringDim stmtAs AcDBStatementDim id As IntegerDim deptAcctNoAs IntegerDim messageAs StringDim theEmpCursor As AcDBCursor' Dim theMgrCursor As AcDBCursorDim myDataRowAs AcDataRowstmtText = "BEGIN :mgrCursor := refCur3.GetMgrData (:DEPTNO, :empCursor, :deptAcct ); END;"

' Prepare the statementSet stmt = New AcDBStatement( GetDBConnection( ) )If Not stmt.Prepare( stmtText ) Then GetDBConnection( ).RaiseError( ) Exit FunctionEnd If

' Define Input and output parameters id= 10 stmt.DefineProcedureInputParameter ( "DEPTNO", id ) stmt.DefineProcedureOutputParameter( "empCursor", V_CPOINTER, NULL )

stmt.DefineProcedureOutputParameter( "deptAcct", V_INTEGER ) stmt.DefineProcedureReturnParameter( "mgrCursor", V_CPOINTER ) ' optionally call Execute() in order to have access to ' output parameter values before calling OpenCursor() If Not stmt.Execute() Then ShowFactoryStatus( "Stored procedure execution failed." ) Exit FunctionElse ShowFactoryStatus( "Stored procedure execution succeeded." )End if

198 P r o g r a m m i n g e . R e p o r t s

' Get and print the output parameter valuesdeptAcctNo = stmt.GetOutputParameter ( "deptAcct" )message = "Output parameter- deptAcct = " & str$(deptAcctNo)ShowFactoryStatus( message )' now allocate an AcDBCursor for the defined cursor parameter Set Cursor = stmt.AllocateCursor( "empCursor" )If Not Cursor.OpenCursor( ) Then GetDBConnection( ).RaiseError( ) Set theEmpCursor = Nothing Exit FunctionEnd If' bind the first result set columns to a data rowCursor.BindColumn( 1, "StoredProcedureExampleApp::DataRow", "ename" )Cursor.BindColumn( 2, "StoredProcedureExampleApp::DataRow", "deptno" )' allocate another AcDBCursor for the other result setSet theMgrCursor = stmt.AllocateCursor( "mgrCursor" )If Not theMgrCursor.OpenCursor( ) Then GetDBConnection( ).RaiseError( ) Set theMgrCursor = Nothing Exit FunctionEnd If' bind the second result set columns to the data rowtheMgrCursor.BindColumn( 1, "StoredProcedureExampleApp::DataRow", "empName" )theMgrCursor.BindColumn( 2, "StoredProcedureExampleApp::DataRow", "mgrName" )theMgrCursor.BindColumn( 3, "StoredProcedureExampleApp::DataRow", "hireDate" )End Sub

Mapping Actuate variable types and Visual Basic type codesWhen you use the DefineProcedureOutputParameter( ) method, you must specify the appropriate Actuate type code. This type code maps to the database data type of the stored-procedure parameter referenced in the define call.

C h a p t e r 1 0 , U s i n g a n d c u s t o m i z i n g a s t o r e d p r o c e d u r e 199

The following table shows the Actuate variable types and the equivalent Visual Basic type code.

The following statements are examples of how to map the data types in DefineProcedureOutputParameter( ):

statement.DefineProcedureOutputParameter("@charboy", V_STRING)statement.DefineProcedureOutputParameter("@int_out", V_INTEGER)

Actuate variable type Type code to use

Currency or Variant V_CURRENCY

Date or Variant V_DATE

Double or Variant V_DOUBLE

Integer or Variant V_INTEGER

Long or Variant V_LONG

Single or Variant V_SINGLE

String or Variant V_STRING

200 P r o g r a m m i n g e . R e p o r t s

C h a p t e r 1 1 , W r i t i n g c u s t o m b r o w s e r c o d e 201

C h a p t e r

Chapter 11Writing custom browsercode

This chapter contains the following topics:

■ About custom browser code

■ About the browser scripting control

■ Including global custom browser code

■ Creating an HTML form

■ Generating custom browser code dynamically

■ Printing and viewing a report using the PDF converter

■ Printing and viewing a report using the Actuate Viewer

■ Creating an example library for Internet Explorer

■ Creating a report for viewing in Netscape

202 P r o g r a m m i n g e . R e p o r t s

About custom browser codeA browser scripting control supports writing code for your web browser inside an Actuate report. Consequently, in your Actuate report you can display and use any type of item that you might see in a web page.

You must provide code for the browser scripting control to instruct the browser to display items, interact with the user or perform specific actions. You can write the code in Actuate or use another tool to generate an external source code file or an applet. The code can be in any form that a web browser can interpret, including:

■ HTML

■ JavaScript

■ Java applets

■ VBScript

Custom browser code in an Actuate report design is interpreted by the web browser when the user views the report in DHTML format.

You can also use browser code elsewhere in e.Report Designer Professional:

■ Global custom browser code supports calling browser code functions from anywhere in your report.

■ You can make an Actuate frame into an HTML form.

About the browser scripting controlYou include custom browser code in a report design using the browser scripting control, which is located on the Drawing/Graphics palette.

The DHTML converter treats the browser scripting control differently from other Actuate controls. Ordinarily, the DHTML converter escapes characters that have special meaning for the web browser, such as:

■ <

■ >

■ "

C h a p t e r 1 1 , W r i t i n g c u s t o m b r o w s e r c o d e 203

■ \n

■ Spaces

For a browser scripting control, however, the DHTML converter does not convert special characters. For example, assume a label control contains the string:

<b>MyText</b>

The DHTML converter converts this string to:

&lt;b&gt;MyText&lt;/b&gt;

This string is sent to the web browser. The web browser converts this string back to:

<b>MyText</b>

This conversion process is shown in the following illustration.

Now assume a browser scripting control contains the string:

<b>MyText</b>

The DHTML converter creates a block of HTML code called the context block. The context block contains the string:

<b>MyText</b>

Label control

<b>MyText</b>

DHTMLconverter

&lt;b&gt;MyText&lt;/b&gt;

Web browser <b>MyText</b>

204 P r o g r a m m i n g e . R e p o r t s

Special characters are not converted. The following illustration shows this conversion process.

If the web browser is Internet Explorer, the context block might look like the following:

<DIV ID="I732" CLASS=C141STYLE="position:absolute;left:171.00pt; top:0.00pt;height:46.00pt; width:136.00pt;border-style:double; border-width:1.00pt;font-size:12.00pt; text-align:left;overflow:hidden; padding-top:0.00pt;">

< !— [START Custom browser code -- ><b>MyText</b>< !— END] Custom browser code -- >

</DIV>

The control’s visual properties, such as background color and border style, are specified in the report design and included in the context block. In this context block, the background color, yellow, is specified by the class attribute and the border style, double, is specified by the border-style attribute. The output of the context block is the string MyText in bold enclosed by a yellow rectangle with a double-line border.

Browser scriptingcontrol

<b>MyText</b>

DHTMLconverter

Context block containing<b>MyText</b>

Web browser

Output ofcontext block

MyText

C h a p t e r 1 1 , W r i t i n g c u s t o m b r o w s e r c o d e 205

Including custom browser code in a report design1 Drag the browser scripting control icon from the Drawing/Graphics

palette and drop it in a frame.

2 Double-click the control.

Component Editor appears.

3 Choose BrowserCode.

Builder appears.

4 Choose Builder.

Custom Browser Code Editor appears.

5 Enter the custom browser code and choose OK.

If you selected Display Sample Data in the Options dialog, the control displays the value of the SampleValue property. Otherwise, the control displays the value of the AlternateText property.

About the context blockThe DHTML converter generates a block of HTML code called the context block that contains the custom browser code specified by the BrowserCode property. The context block is the custom browser code’s immediate parent in the HTML document’s hierarchy of objects. The context block applies the browser scripting control’s visual properties such as background color and border style. In Microsoft Internet Explorer, the context block is in the DIV element. In Netscape Navigator, the custom browser code is in the DIV element and the context block is in the LAYER element.

206 P r o g r a m m i n g e . R e p o r t s

The following example shows a context block in Microsoft Internet Explorer:

<DIV ID="I550" CLASS=C148onMouseOver="mouseOver (...) "STYLE="position:absolute;left:36.00pt; top:54.00pt; height:73.00pt; width:127.00pt;font-size:8.00pt;text-align:left;overflow:hidden;padding-top:0.00pt;">

<!— [START Custom browser code -- ><SCRIPT LANGUAGE="JavaScript">

document.write("...")</SCRIPT><!— END] Custom browser code -->

</DIV>

The following example shows a context block in Netscape Navigator:

<LAYER LEFT=108 TOP=420 HEIGHT=27 WIDTH=109ID="I578" CLASS=C150STYLE="position:absolute;layer-background-color:transparent;background-color:transparent;font-size:14.00pt;overflow:hidden;clip:rect(0px 109px 27px 0px) ;"><DIV ALIGN="left">

<!— [START Custom browser code -- ><SCRIPT LANGUAGE="JavaScript">

document.write("...")</SCRIPT><!— END] Custom browser code -- >

</DIV></LAYER>

Clipping the output of custom browser codeYou can specify the clipping for custom browser code output using the browser scripting control’s BrowserClipping property. For Microsoft Internet Explorer, the setting of the BrowserClipping property maps to the overflow CSS attribute for the DIV element. For Netscape Navigator, the setting of the BrowserClipping property maps to the clip:rect(top right bottom left) CSS attribute for the LAYER element.

C h a p t e r 1 1 , W r i t i n g c u s t o m b r o w s e r c o d e 207

The following table shows how the setting of the BrowserClipping property maps to the overflow CSS attribute for Internet Explorer.

The following table shows how the setting of the BrowserClipping property maps to the clip:rect(top right bottom left) CSS attribute for Netscape Navigator. If BrowserClipping is set to AutoScrollbar, Scrollbar, or ClipToControlSize, the output of the custom browser code is clipped to the control size. If BrowserClipping is set to NoClipping, the DHTML converter does not generate a clip:rect(top right bottom left) CSS attribute for the LAYER element.

Aligning the output of custom browser codeYou can specify the alignment of custom browser code output using the browser scripting control’s TextPlacement properties. The Horizontal and Vertical properties behave as they do for other textual controls. The following properties, however, are ignored by the DHTML converter:

■ Clip

■ Ellipsis

■ FillPattern

Setting of BrowserClipping property

Setting of overflow CSS attribute

Behavior inInternet Explorer

AutoScrollbar Auto Scroll bars shown when necessary.

Scrollbar Scroll Scroll bars always shown, active when necessary.

ClipToControlSize Hidden Clip to control size.

NoClipping Visible No clipping. DIV block is resized as necessary.

Setting of BrowserClipping property

Setting of clip:rect() CSS attribute

Behavior inNetscape Navigator

AutoScrollbar Control size Clip to control size.

Scrollbar Control size Clip to control size.

ClipToControlSize Control size Clip to control size.

NoClipping Not generated No clipping.

208 P r o g r a m m i n g e . R e p o r t s

■ MultiLine

■ WordWrap

If a browser scripting control displays the value of the AlternateText property, all TextPlacement properties apply. A browser scripting control displays the value of the AlternateText property in a PDF viewer or in a web browser if DebugOption is set to true.

For more information about viewing PDF output, see “Printing and viewing a report using the PDF converter” later in this chapter. For more information about the DebugOption, see “Debugging custom browser code” later in this chapter.

Debugging custom browser codeBecause Actuate does not parse or check custom browser code for errors, there might be cases where custom browser code output causes a problem in a DHTML report page. Problems might include visual distortion or a JavaScript error message. To troubleshoot this type of problem, do one of the following:

■ Set the browser scripting control’s DebugOption property to true.

Setting DebugOption to True tells the web browser to display the value of the browser scripting control’s AlternateText property rather than interpret the custom browser code.

■ Check the value of the BrowserCode property at view time.

You can locate custom browser code in the browser source viewer by searching for the tags that the DHTML converter inserts before and after custom browser code:

<!— [START Custom browser code -- >...<!— END] Custom browser code -- >

You can also display the custom browser code specified by a browser scripting control in the client Viewer by right-clicking the control and choosing View Browser Code.

For example, assume a report that contains a browser scripting control generates a JavaScript error when you view the report in a web browser. You want to determine if the custom browser code is causing the error. Regenerate the report with DebugOption set to true and view it in the web browser again. Now the web browser displays the value of the AlternateText property instead of interpreting the custom browser code. If the browser does not raise the JavaScript error this time, you know that the custom browser code is causing the error.

C h a p t e r 1 1 , W r i t i n g c u s t o m b r o w s e r c o d e 209

Including global custom browser codeYou can include global custom browser code in a report design, such as:

■ JavaScript functions and variables

■ Common event handlers

■ CSS STYLE elements

Global custom browser code can be referenced from browser scripting controls located in the frames of a report design. It is not practical, however, to include a browser scripting control containing global custom browser code in a frame. Because the DHTML converter generates a separate document for every page in the report, placing global custom browser code in a frame can cause unresolved references when a web browser interprets the report page. For example, suppose you have a three-page report. Page 1 contains a report header frame that contains a browser scripting control that defines a global onChange event handler. Pages 2 and 3 contain content frames that contain browser scripting controls that refer to the global onChange event handler. The DHTML documents for Pages 2 and 3 raise JavaScript errors because the definition of the onChange event handler is in a different document.

For this reason, you must use the GlobalDHTMLCode property of the root component of the report design to include global custom browser code in a report design. For ease of maintenance, you can set the GlobalDHTMLCode property to refer to a file that contains global custom browser code. Global custom browser code is appended to the <HEAD> element of every DHTML page generated by the DHTML converter. For information about what can be placed in the <HEAD> element, see your DHTML documentation.

How to include global custom browser code in a report design

1 Double-click the AcReport component.

Component Editor appears.

2 Choose GlobalDHTMLCode.

Builder appears.

3 Choose Builder.

Custom Browser Code Editor appears.

4 Type the global custom browser code or a reference to a file that contains this code.

5 Choose OK.

210 P r o g r a m m i n g e . R e p o r t s

Creating an HTML formYou can create an HTML form using browser scripting controls, such as combo boxes and lists, and a frame component. Actuate software places the custom browser code specified by the controls inside a <FORM> element. You can create a library containing frequently used browser scripting controls.

How to create an HTML form using browser scripting controls

1 Drag browser scripting controls for the form elements from the library to a frame.

2 Double-click the frame.

Component Editor appears.

3 In Properties, choose CustomDHTMLHeader.

Builder appears.

4 Choose Builder.

Custom Browser Code Editor appears.

5 Type the <FORM> tag in the following format:

<FORM METHOD=POST ACTION=http://roadrunner/acweb/roadrunner/MyReport.rox?Submit>

6 Choose OK to return to Properties.

7 Choose CustomDHTMLFooter.

Builder appears.

8 Choose Builder.

Custom Browser Code Editor appears.

9 Type:

</FORM>

10 Choose OK.

Generating custom browser code dynamicallyYou can generate custom browser code dynamically at view time by overriding the browser scripting control’s BrowserCode( ) method. You can control the value of AlternateText at view time by overriding the browser scripting control’s GetText( ) method. You can also set BrowserCode and AlternateText at report generation time by overriding the BuildFromRow( ) or OnRow( ) methods.

C h a p t e r 1 1 , W r i t i n g c u s t o m b r o w s e r c o d e 211

Overriding BrowserCode( ) and GetText( )You can generate output specific to the current viewing environment by overriding the BrowserCode( ) and GetText( ) methods. You can use the following functions:

■ GetAppContext indicates the Actuate application that is currently running.

■ GetReportContext indicates whether the report is in the factory, viewing, or printing stage.

■ GetUserAgentString returns the unparsed user agent string sent by the web browser with every HTTP request.

■ GetReportScalingFactor returns the current scaling factor.

For more information about these functions, see Chapter 2, “AFC data types,” in Actuate Foundation Class Reference.

Determining the application execution contextYou can determine the application execution context using the GetAppContext and GetReportContext functions, as shown in the following example:

Function GetText( ) As StringDim rptCtx As IntegerDim appCtx As IntegerDim str As StringDim NL As StringNL = Chr$(10)appCtx = GetAppContext( )rptCtx = GetReportContext( )str = "Application context: " + Str$(appCtx) + NLstr = str + "Report context: " + Str$(rptCtx) + NL + NLIf appCtx = ServerContext And rptCtx = ViewerReportContext Then

GetText = str + "We are in ViewServer! "Else

GetText = str + Super::GetText( )End If

End Function

Generating output for different browsersTo generate different output for Microsoft Internet Explorer and Netscape Navigator, for example, you can use the GetUserAgentString function as shown in the following example:

Function GetText( ) As StringDim str As StringDim NL As StringNL = Chr$(10)str = GetUserAgentString( )If Len(str) = 0 Then

212 P r o g r a m m i n g e . R e p o r t s

GetText = "...Not in a web browser."Else

If InStr(str, "MSIE") = 0 Then'Not MSIE.

GetText = str + NL + "...In Netscape"Else

GetText = str + NL + "...In MSIE"End If

End IfEnd Function

Adjusting for the current scaling factorWhen the report user changes the scaling factor while viewing a report page in a web browser, the view process regenerates the page. The DHTML converter scales the controls on the report page but it does not scale or change the output of custom browser code. You should therefore ensure that the output of custom browser code can use different scaling factors, especially 75% and 100%. You can adjust the size of the browser scripting control’s rectangle to accommodate the output of custom browser code at different zoom levels.

To adjust the size of the browser scripting control’s rectangle based on the current scaling factor, override the BrowserCode( ) method and use the GetReportScalingFactor function. By overriding BrowserCode( ), you can change the height and width of the HTML element produced by the custom browser code. The GetReportScalingFactor function returns the scaling factor. A value of 1.0 corresponds to a 100% zoom. For example, you can override BrowserCode( ) as shown in the following example:

Function BrowserCode( ) As StringDim dhtmlCode As StringDim zoom As Doublezoom = GetReportScalingFactor()dhtmlCode = "<SPACER TYPE=""block"" HEIGHT=" + Str$(150 * zoom)dhtmlCode = dhtmlCode + " WIDTH=" + Str$(250 * zoom) + ">"BrowserCode = dhtmlCode

End Function

Overriding the BuildFromRow( ) and OnRow( ) methodsYou can set AlternateText and BrowserCode by overriding BuildFromRow( ) or OnRow( ) when you generate a report. Override OnRow( ) when the browser scripting control is in a content frame to display values from a single row in the control. Override BuildFromRow( ) when the browser scripting control is in a header or footer frame to display values from multiple rows.

You manage AlternateText and BrowserCode differently. Because AlternateText is a property, you can assign a value to it. To generate custom

C h a p t e r 1 1 , W r i t i n g c u s t o m b r o w s e r c o d e 213

browser code dynamically when you generate a report, you must do the following:

■ Create a string variable at the class or instance level.

■ Override BuildFromRow( ) to set the string variable.

■ Override BrowserCode( ) to return the string variable as a result.

The following code shows how to set AlternateText and BrowserCode at report generation time:

'Declare dhtmlStr in Component Editor as new class variableDim dhtmlStr As StringFunction BrowserCode( ) As String

BrowserCode = dhtmlStrEnd FunctionSub OnRow( row As AcDataRow )

Super::OnRow( row )AternateText = "Scripting Control Placeholder"dhtmlStr = "<P>Headline News</P>"

End Sub

Printing and viewing a report using the PDF converter

The PDF converter does not interpret DHTML code. When a report prints or appears in PDF format, e.Report Designer Professional substitutes a string for custom browser code output. To specify this string, take one of the following steps:

■ Specify a value for the browser scripting control’s AlternateText property.

The string appears in the PDF output as the content of the browser scripting control.

■ Override the GetText( ) method.

GetText( ) is called at view time. By default, GetText( ) returns the value of the AlternateText property.

■ Override the BuildFromRow( ) or OnRow( ) method.

The Factory service calls these methods.

The string is clipped to the size of the control. If the AlternateText property is empty, the PDF converter does not display anything for the browser scripting control.

214 P r o g r a m m i n g e . R e p o r t s

For more information about setting AlternateText at view time or at report generation time, see “Generating custom browser code dynamically,” earlier in this chapter.

Displaying different controls in DHTML and PDF outputYou can display different controls in a report’s DHTML and PDF output by stacking one control on top of another in the report design and setting the ShowInDHTML property for one control and the ShowInPDF property for the other. For example, assume you want the report to display the output of custom browser code when the report is viewed in a web browser but you want the report to display an image control when the report is printed in PDF format. You can place a browser scripting control on top of an image control in the report design. For the browser scripting control, you can set ShowInDHTML to true and ShowInPDF to false. For the image control, you can set ShowInPDF to true and ShowInDHTML to false.

ShowWhenPrinting and ShowWhenViewingIf a control’s ShowWhenPrinting property is false, the control does not appear in the report’s PDF output. If ShowWhenPrinting is true, the setting of ShowInPDF determines if the control appears in the PDF output. Likewise, if a control’s ShowWhenViewing property is false, the control does not appear in the DHTML output. If ShowWhenViewing is true, the setting of the ShowInDHTML property determines if the control is displayed in the report’s DHTML output.

A control’s ShowWhenPrinting and ShowWhenViewing properties are set to true by default.

Printing and viewing a report using the Actuate Viewer

In the Actuate Viewer, a browser scripting control displays the value of the AlternateText property. You can change this behavior by overriding the GetText( ) method. GetText( ) is called at view time.

Other display properties, such as background color and border style, apply to a browser scripting control just as they apply to other textual controls. Settings for ShowWhenPrinting and ShowWhenViewing also apply.

C h a p t e r 1 1 , W r i t i n g c u s t o m b r o w s e r c o d e 215

You can display the custom browser code specified by a browser scripting control in the Viewer by right-clicking the control and choosing View Browser Code.

To hide a browser scripting control in the Viewer, take one of the following steps:

■ Make the height and width of the control very small.

■ Place another control on top of the browser scripting control.

■ Set ShowWhenPrinting and ShowWhenViewing to false.

■ Set BackgroundColor and Border Color to TransparentColor. Then set AlternateText to an empty string or set Font Color to TransparentColor.

Creating an example library for Internet ExplorerIt is helpful to create a library containing:

■ A frame component that can be used to create a DHTML form

■ Frequently-used browser scripting controls

An example of this type of library is shown in the following illustration. The frame’s class name is DHTMLForm. DHTMLMenuControl is a browser scripting control that generates a menu in a web browser.

Using DHTMLFormDHTMLForm defines several new variables and overrides two methods.

216 P r o g r a m m i n g e . R e p o r t s

Working with DHTMLForm variablesDHTMLForm defines several new variables.

FormAction, FormName, and FormOnSubmit have a Visibility of Property, and FormMethod has a Visibility of Essential Property. For this reason, these variables appear on the Properties page.

Working with DHTMLForm methodsDHTMLForm overrides the CustomDHTMLHeader( ) and CustomDHTMLFooter( ) methods as shown in the following illustrations. These methods generate a <FORM> element.

C h a p t e r 1 1 , W r i t i n g c u s t o m b r o w s e r c o d e 217

Subclassing DHTMLFormWhen you subclass DHTMLForm from the library and use it in a report design, you can set the FormAction, FormMethod, and FormName properties as shown in the following table. The CustomDHTMLHeader( ) method uses values of these properties to generate a FORM element.

This example submits a request for immediate execution in iServer. The report user typically submits a request by clicking a button in a form. For more information about Actuate Active Portal JavaServer Pages, see Creating Custom Web Applications using Actuate Active Portal.

Property Value

FormAction http://radium:8700/acweb/executereport.do?__requesttype=immediate&__executableName=%2fSales%20Conferences%2fSummaryTimeSeries%2erox

FormMethod POST

FormName FormBasedForm

218 P r o g r a m m i n g e . R e p o r t s

Working with DHTMLMenuControlDHTMLMenuControl defines several new variables and overrides several methods.

Working with DHTMLMenuControl variablesDHTMLMenuControl defines several new variables.

MenuName, MenuScript, OptionText, and OptionValue have a Visibility of Property. For this reason, these variables appear on the Properties page.

Working with DHTMLMenuControl methodsDHTMLMenuControl overrides the methods shown in the following illustration.

C h a p t e r 1 1 , W r i t i n g c u s t o m b r o w s e r c o d e 219

Using BuildFromRow( )

Override the BuildFromRow( ) method as shown in the following example:

Function BuildFromRow( row As AcDataRow ) as AcBuildStatusBuildFromRow = Super::BuildFromRow( row )'Insert your code hereBuildFromRow = ContinueBuilding

EndFunction

Using OnRow( )

OnRow( ) defines an Option element for each menu option and assigns the code to MenuCode. OnRow( ) is called repeatedly because BuildFromRow( ) returns ContinueBuilding. Override OnRow( ) as shown in the following example:

Sub OnRow ( row as AcDataRow )'Insert your code here

Dim NL as StringDim TAB as StringDim i as Integer

Dim text as StringDim value as String

NL = Chr$(10)TAB = Chr$(9)i = 0

text = row.GetValue(OptionText)value = row.GetValue(OptionValue)

220 P r o g r a m m i n g e . R e p o r t s

MenuCode = MenuCode + NL + " <option value= ' " + value + " '>" + text + "</option>"

End Sub

Using Finish( )

Finish( ) generates a Select element and assigns the code to FinalMenuCode. Override the Finish( ) method as shown in the following example:

Sub Finish( )Super::Finish( )'Insert your code hereFinalMenuCode = "<SELECT NAME=' " + MenuName + " '>"FinalMenuCode = FinalMenuCode + MenuCode + Chr$(10)FinalMenuCode = FinalMenuCode + "</SELECT>" + Chr$(10)FinalMenuCode = FinalMenuCode + MenuScript

EndSub

Using BrowserCode( )

The BrowserCode( ) method assigns FinalMenuCode to the BrowserCode variable. The BrowserCode variable passes to the DHTML converter. Override the BrowserCode( ) method as shown in the following example:

Function BrowserCode( ) As String'Insert your code hereBrowserCode = FinalMenuCode

End Function

Subclassing DHTMLMenuControlBy subclassing DHTMLMenuControl from the library, you can create a browser scripting control that generates a drop-down menu when a report appears in a web browser. For example, you can create a control called CustomerMenu that generates a drop-down menu listing all customers in the sfdata database.

Set the MenuName, OptionText, and OptionValue properties as shown in the following illustration. The OnRow( ) method uses values of OptionText and OptionValue to generate an Option element for each menu option. Because OptionText is set to customers.customName, the customer name displays in the menu. The value of MenuName is used by the Finish( ) method to generate a Select element.

C h a p t e r 1 1 , W r i t i n g c u s t o m b r o w s e r c o d e 221

Displaying custom browser code in the ViewerYou can display the custom browser code generated by the CustomerMenu control in the Viewer. Right-click the control and choose View Browser Code. The code appears in Code Editor, as shown in the following illustration:

222 P r o g r a m m i n g e . R e p o r t s

Displaying custom browser code output in a web browserThe output of the custom browser code generated by the CustomerMenu control is a drop-down menu that lists all customers in a database.

Creating a report for viewing in NetscapeTo design a report for viewing with a Netscape browser, take note of the following special considerations:

■ To create an HTML form, use a single browser scripting control and ensure that BrowserCode includes the FORM element. Do not use a frame component’s CustomDHTMLHeader and CustomDHTMLFooter properties to create a form.

■ If the BrowserClipping property is set to NoClipping, the contents of the browser scripting control can extend outside the control’s rectangle. If you apply a border or background attribute, the attribute applies only to the area within the rectangle. You must resize the rectangle to enclose the contents of the control.

■ The font attribute that the CSS style applies overrides any font formatting in custom browser code. The browser scripting control’s Font properties indicate the font attribute that the CSS style applies.

■ Because Actuate software adds multiple LAYER and DIV blocks, JavaScript pointers fail to the path

window.document.<object name>...

JavaScript functions should include only

document.<object name>...

where document refers to the LAYER and DIV block that contains the custom browser code

C h a p t e r 1 1 , W r i t i n g c u s t o m b r o w s e r c o d e 223

■ Do not use the BLINK tag. Code specified with the browser scripting control is placed within the LAYER and DIV elements. The BLINK tag does not function within the LAYER and DIV elements.

■ Do not include a STYLE element in code specified with the GlobalDHTMLCode property. Code specified with this property is appended to the HEAD element. Netscape cannot apply a STYLE element included in a HEAD element.

224 P r o g r a m m i n g e . R e p o r t s

C h a p t e r 1 2 , D e s i g n i n g a r e p o r t f o r X M L d a t a 225

C h a p t e r

Chapter 12Designing a report forXML data

This chapter contains the following topics:

■ About the XML data format

■ About the View process

■ Publishing an Actuate report as XML

226 P r o g r a m m i n g e . R e p o r t s

About the XML data formatExtensible Markup Language (XML) is a meta-language that provides a software- and platform-independent format for representing data. You can view data extracted to an XML format using any software that supports XML, including a web browser.

XML is a subset of the Standard Generalized Markup Language (SGML), which adds descriptive and structural information to data. XML uses mark-up tags to specify the content, structure, and display of data. For example, XML tags specify whether the text is a parts catalog title or an order total amount and support processing the data in another application.

Using Actuate e.Report Designer Professional, you design a report to conform to a specific XML data format. The XML data format extracts data for an entire Actuate report. A report converted to XML retains its original design and graphics. The XML data format ignores page components such as pages, flows, page headers, and page footers.

XML data supports page-level security. A user’s privileges determine what data he or she views. Page-level security is available only for a report published on iServer that the user views in a web browser using the DHTML viewer. For more information about page-level security, see Chapter 8, “Designing a report with page-level security.”

About Document Type DefinitionsAn application that processes XML conforms to a Document Type Definitions (DTD) specification. A DTD specification is one or more files that contain the formal definition of a document. A DTD file defines specific data formats.

Some XML documents have an associated DTD and adhere to that DTD. These documents are called valid XML documents. A valid XML document must also be well-formed. A well-formed XML document adheres to XML rules as defined in the XML standard. Other XML documents do not have an associated DTD. Such documents must include a declaration that they are stand-alone documents. These stand-alone documents must be well-formed according to XML rules.

There is no default DTD file. You determine the XML data that a report produces by setting properties or overriding methods in a report design.

C h a p t e r 1 2 , D e s i g n i n g a r e p o r t f o r X M L d a t a 227

Examining a simple XML documentThe following example is a simple XML document.

<?xml version="1.0" standalone="yes"?> <conversation> <greeting>Hello, sales staff!</greeting> <response>Thank you for the customer information!</response> </conversation>

This document consists of:

■ A prolog. The prolog identifies which version of XML the document supports and whether the document has an associated DTD. In this example, the prolog is the following line:

<?xml version="1.0" standalone="yes"?>

This prolog specifies that the document uses XML version 1.0. The standalone="yes" element indicates that this document does not have an associated DTD.

Actuate software generates the prolog for an XML report. You can generate a custom prolog by overriding the Actuate Basic method XMLDataProlog( ).

■ A conversation element. The conversation element contains a greeting element and a response element. The tag <conversation> begins the conversation element. The tag </conversation> ends the conversation element.

The following fragment shows a more complicated XML document:

<?xml version="1.0" standalone="no" encoding="UTF-8"?> <!DOCTYPE titlepage QTRLYRPT "http://www.MyCorp.com/RptDTDs/qtrly.dtd" [<!ENTITY % active.links "INCLUDE">]> <titlepage> <white-space type="vertical" amount="36"/> <title font="Palatino" size="30" alignment="centered">MyCorp Quarterly Report</title> <white-space type="vertical" amount="12"/><image location="http://www.MyCorp.com/RptDTDs/imgs/logo.img" type="URL" alignment="centered"/> <white-space type="vertical" amount="24"/> <author font="Palatino" size="18/22" style="italic">MyCorp Financials Group</author> </titlepage>

This document uses XML version 1.0 and UTF-8 encoding. The document adheres to the quarterly report DTD, qtrly.dtd, located at http://www.MyCorp.com/RptDTDs. The title is 30-point Palatino font with the text MyCorp Quarterly Report, followed by the company logo. The MyCorp Financials Group authors the document.

228 P r o g r a m m i n g e . R e p o r t s

About the View processThe View process supports viewing an Actuate report in a variety of formats. The View process converts Actuate report pages and other report data from XML into DHTML. This conversion supports viewing and searching an Actuate report using a web browser. When a user runs a report designed to produce XML, the View process takes the following steps:

■ Renders the report into XML.

■ Converts the XML report to another format, such as DHTML for viewing or PDF for printing.

■ Supports searching report data on the web.

■ Supports creating a dynamic table of contents for navigating through a report on the web.

The View process renders a report into the XML format the report design defines. The View process can extract search results in a variety of formats, including Excel and comma- or tab-separated formats.

The View process also provides page-level security. Page-level security restricts access to data that the user does not have permission to see. For more information about page-level security, see Chapter 8, “Designing a report with page-level security.”

The following diagram shows the View process architecture.

C h a p t e r 1 2 , D e s i g n i n g a r e p o r t f o r X M L d a t a 229

The View process translates a report to XML format then either converts it to another format or sends the XML data directly to other applications for processing.

Publishing an Actuate report as XMLThis section describes how to design an Actuate report to produce XML data output. You design a report to produce XML by setting XML properties for components and overriding methods to achieve custom XML data extraction. You can extract the data for an entire report to produce XML output or extract only the data for a specific component. The XML properties for a component determine whether Actuate software produces XML data for that component.

Actuate does not provide a Document Type Definition (DTD) for XML data. The format depends upon the report requirements. The XML output can conform to an existing DTD for specific applications or you can create a DTD to specify the XML to produce.

To produce the XML output, in Actuate e.Report Designer Professional build and run the report. InReport Viewer, choose File➛Save As➛XML Data.

ROX cache

Chart & image cache

XML

Page viewing

Search

TOC

XML data

Report documents

IE browser

Netscape browser

Custom applications

View process

Acrobat Reader

PDF

NetscapeDHTML

MS IEDHTML

Converterframeworks

Basicengine

Pagesecurity

230 P r o g r a m m i n g e . R e p o r t s

Mapping XML to Actuate report sectionsThe Actuate Foundation Classes (AFC) include XML-specific properties. These properties, which you set when you design the report, specify how to generate XML data.

When designing a report for XML, consider the following guidelines:

■ Know your DTD. The DTD determines how to represent your report’s information.

■ Determine the report’s consumer. If another application, such as a catalog or an Excel spreadsheet, processes the report’s XML output, the XML design can differ from that of a report designed for an end user to view.

Use the following guidelines to convert an Actuate report to XML. Check your DTD for specific requirements for your XML documents.

■ The AcReport component is the top-level component of the report. In AcReport, set the properties that control the XML data that the report produces. These properties are the XML prolog information.

■ A section or frame typically maps to an XML element. Set the component’s XMLTag property to the element name. Set the XMLType property to XMLElement.

■ To use a control to represent an attribute, set the control’s XMLType property to XMLAttribute.

■ If your DTD’s requirements do not readily map to an Actuate report’s XML, set the XMLType property to XMLCustom and override the GenerateXML( ) method of the component to generate the required XML.

About XML propertiesAll AFC report component classes include XML properties and methods to control the generation of XML data. This section describes the classes that provide properties and methods and the AFC functions that support generating XML data.

The property group XML Data in Component Editor lists the XML properties that e.Report Designer Professional supports for a component. If XML properties do not apply to a specific component, the XML Data property group does not appear in the Properties page for that component. The following illustration shows the XML Data property group for a report component.

C h a p t e r 1 2 , D e s i g n i n g a r e p o r t f o r X M L d a t a 231

XML properties are available for AcReportComponent and its subclasses, except for subclasses of AcBasePage.

XML properties apply to the following components:

■ AcReport

■ AcSection and its subclasses

■ AcFrame

■ AcControl and its subclasses

About AcReport XML propertiesThe following table describes the XML properties for AcReport. These properties control the overall structure and appearance of the XML output file.

Property Description

XMLCharSet The encoding declaration to insert in the XML prolog. If not specified, Actuate software does not include an encoding declaration in the XML prolog.

XMLDocType The document type string to display in the document’s DOCTYPE declaration.

XMLFileDescription The description of the XML file to build. The default value is XML Files.

XMLFileExtension The file extension of the XML file to build. The default value is xml.

232 P r o g r a m m i n g e . R e p o r t s

About AcReportComponent XML propertiesThe following table describes the XML properties for AcReportComponent.

About AFC XML functionsThe following table describes the AFC functions that control generation of XML from an Actuate report.

XMLIndent The number of spaces to indent each level in the XML file. Set the value to 0 to improve the performance of XML generation and reduce the XML file size.The default value is 4. Use the default value when viewing and debugging the XML report.

XMLMimeType The MIME type for the XML document. The default value is text/xml.

Property Description

Property Description

XMLAddContents Determines whether to search through a component’s contents recursively to find other components for which to generate XML. The default value is true. Set this value to false to skip over sections or frames for which you do not want to generate XML data.

XMLAttributes A set of additional attribute values to add to the current XML element. Use XMLAttributes to add fixed attributes. Use controls to add attributes that vary depending on the data in the data row.

XMLTag The XML element or attribute name for this component.

XMLType The type of XML object the component represents. The values are:■ XMLAttribute. The component is an XML attribute.■ XMLCustom. A custom XML element. AFC calls the

GenerateXML( ) method to generate the custom element.

■ XMLElement. The component is an XML element.■ XMLEmptyAttribute. The component is an empty

XML element. ■ XMLIgnore. Do not generate XML for the

component. XMLIgnore is the default value for XMLType.

C h a p t e r 1 2 , D e s i g n i n g a r e p o r t f o r X M L d a t a 233

AFC Class Function Description

AcReportComponent

Function GetXMLText( ) As String

Returns the value for an element or attribute. The default value for a data control is the value of GetText( ) formatted for XML. The default value for all other components is an empty string. Override this method to provide custom formatting.

AcReportComponent

Sub Generate XML(visitor AsAcXMLDataVisitor)

Generates the XML for a custom component. Actuate calls this method if the component’s XMLType is XMLCustom. Override this method to produce custom XML. By default, this function does nothing.

AcReport Function GenerateXMLDataFile(fileName As String) As Boolean

Generates an XML file for the report.

AcReport Sub XMLDataProlog (channel As Integer)

Generates the prolog portion of the XML report then writes the prolog to a channel. Override XMLDataProlog( ) to create a custom prolog. This function generates a standard prolog by default.Actuate software generates the XML version and encoding attributes in the prolog. The XML version number is the version of XML that Actuate software supports. The encoding is the type of encoding used to build the report. The default encoding is UTF-8.

AcReportView Sub GenerateXMLData(filename As String)

Generates XML data for a report.

234 P r o g r a m m i n g e . R e p o r t s

The following report, the Design Emporium product catalog, illustrates how to map a report component to an XML element.

Each component in the report corresponds to an XML element.

■ The Catalog element contains the entire catalog.

■ The Address element contains addresses. Its attribute, Type, specifies the address type, such as Mailing.

■ The Product element contains information about the items in the catalog. Its attribute, Category, specifies the item type, such as Accessories. Product contains sub-elements that describe each catalog item in detail.

■ The Part element is a sub-element of Product. Part contains the item’s catalog number as an attribute.

■ The Description element is a sub-element of Part. Description contains a text description of the item.

■ The Price element is a sub-element of Part. Price contains the item’s list price.

<CATALOG> contains the entire report

<ADDRESS TYPE=MAILING> contains the company address

<PRODUCT CATEGORY=value> specifies the general product group

<PART> specifies the part number

<DESCRIPTION> contains the item’s description

<PRICE> contains the item’s list price

C h a p t e r 1 2 , D e s i g n i n g a r e p o r t f o r X M L d a t a 235

The report design defines the Category attribute using the following properties:

The report design defines the Address element using the following properties:

The report design defines the List Price element using the following properties:

236 P r o g r a m m i n g e . R e p o r t s

The XML output for this report is similar to the following:

<?xml version="1.0" encoding="UTF-8"?><CATALOG> <ADDRESS TYPE=MAILING>Design Emporium, Inc.&lf;101 Main Street&lf;San Francisco, CA 94435</ADDRESS> <PRODUCT CATEGORY="Accessories"> <PART PARTNO="MR0410"> <DESCRIPTION>Pencil Cup</DESCRIPTION> <PRICE>$4.00</PRICE> </PART> <PART PARTNO="MR0440">...</CATALOG>

C h a p t e r 1 3 , U n d e r s t a n d i n g r e p o r t b u r s t i n g t e c h n i q u e s 237

C h a p t e r

Chapter 13Understanding reportbursting techniques

This chapter contains the following topics:

■ About report bursting

■ Understanding report bursting techniques

■ Understanding report bursting tasks

■ Examining report bursting examples

238 P r o g r a m m i n g e . R e p o r t s

About report burstingReport bursting is the process of creating a single report object executable (.rox) file that generates multiple report object instance (.roi) files. Generating many small reports has several advantages:

■ You can set privileges for each report by placing the report in a folder with the appropriate privileges.

■ A report user can download and view several small files offline more easily than one large file. The size of a report can affect the overall performance of iServer. A large report that contains more than 10,000 pages requires a longer report generation time.

■ It is often easier for a report user to find data by locating a report in an Encyclopedia volume than by navigating through a single large report.

■ If all reports in a folder use the same query, the query executes only once.

On iServer, report bursting is available only for asynchronous reports. A report that uses bursting generates other reports and iServer cannot determine which report to display if you run it synchronously.

Understanding report bursting techniquesThe report bursting techniques described in the following topics use a master report and several identical detail reports.

Your report design must include a master report. The master report controls the report generation process. The name of the master report appears in the notification when report generation finishes. To delete the master report after generation, override the RoiIsTemporary( ) method.

Use one of the following techniques to create the detail reports. Each detail report is placed in a different report object instance (.roi) file:

■ Place a sequential section in the master report. Then place the detail reports in the sequential section.

■ Use a report and subreport structure.

■ Burst the report on group boundaries.

For information about subreport bursting and group bursting, see “Examining report bursting examples,” later in this chapter. For information about using sequential sections, see Chapter 11, “Working with sections,” in Developing Advanced e.Reports.

C h a p t e r 1 3 , U n d e r s t a n d i n g r e p o r t b u r s t i n g t e c h n i q u e s 239

Understanding report bursting tasksTo create a report with bursting, you must perform the following tasks:

■ Create the detail report by adding a second subclass of AcReport to your report design. The detail report appears in a separate report object instance (.roi) file.

■ Add a page list and a page style to the detail report.

■ Provide a name for the detail report by overriding the detail report’s SuggestRoiName( ) method.

The following additional tasks are optional:

■ Create a hyperlink from the master report to the detail report.

■ Pass data from the master report to the detail report.

■ Place the detail report in a different folder.

How to add a second subclass of AcReport

To add a second subclass of AcReport to your report design, drag the report component from the Structure palette and drop it in the appropriate slot in the structure pane.

240 P r o g r a m m i n g e . R e p o r t s

Examining report bursting examplesThe Examples folder installed with e.Report Designer Professional contains two report designs that use report bursting, Burst1.rod and Burst2.rod. Both designs use the Sfdata database and both generate the same master report and detail reports.

The master report lists the states in which MultiChip Technologies’ customers are located. Each state is a hyperlink to a separate detail report that lists the customers in that state. The master report serves as an index to the detail reports. The report user can navigate from the master report to the detail reports using the hyperlinks.

Burst1.rod uses subreport bursting, and Burst2.rod uses group bursting.

Examining a subreport bursting exampleBurst1.rod uses subreport bursting. With subreport bursting, you place each subreport in a different report object instance (.roi) file.

C h a p t e r 1 3 , U n d e r s t a n d i n g r e p o r t b u r s t i n g t e c h n i q u e s 241

Examining the report structure for a subreport bursting exampleBurst1.rod uses a report and subreport structure. The subreport, or detail report, is in a sequential section.

Examining the detail report’s PageList component for a subreport bursting exampleThe detail report’s PageList component is a reference to the master report’s PageList component.

Detail query

Summary entry

Reference to master report’s PageList component

Detail report

Master report

242 P r o g r a m m i n g e . R e p o r t s

Examining the detail query for a subreport bursting exampleThe detail report’s query, CustomerQuery, has a parameter using the value of the summary entry, state.

For CustomerQuery, the Conditions tab of Query Editor appears as shown in the following illustration.

The SQL tab of Query Editor appears as shown in the following illustration.

Examining the BuildFromRow( ) method for a subreport bursting exampleThe BuildFromRow( ) method of the detail report’s section, NestedReport, is overridden to set the detail query’s parameter, StateParam, to the value of the summary entry, state.

Function BuildFromRow( row As AcDataRow ) As AcBuildStatusIf Not row Is Nothing Then

CustomerQuery::StateParam = row.GetValue( “state” )End IfBuildFromRow = Super::BuildFromRow( row )

EndFunction

C h a p t e r 1 3 , U n d e r s t a n d i n g r e p o r t b u r s t i n g t e c h n i q u e s 243

Examining the SuggestRoiName( ) method for a subreport bursting exampleThe detail report’s SuggestRoiName( ) method is overridden to give each detail report a unique name. The value of the summary entry, state, is used to create the name.

Note that there are two versions of the SuggestRoiName( ) method. One version does not take any arguments, the other version takes a data row. The following example uses the version that takes a data row.

Function SuggestRoiName( row As AcDataRow ) As StringSuggestRoiName = “State_” & row.GetValue( “state” ) & “ .roi”

EndFunction

If the report design generates a large number of reports, place the reports in different folders. To place the reports in different folders, include a folder in the name returned from SuggestRoiName( ). For example, if the report design generates reports for counties in different states and you want to place the reports for each state in a different folder, override SuggestRoiName( ) as follows:

Function SuggestRoiName( row As AcDataRow ) As StringSuggestRoiName = row.GetValue( "state" ) & "/" &

row.GetValue( "county" ) & ".roi"End Function

Examining the summary entry’s LinkExp property for a subreport bursting exampleThe summary entry’s Linking➛LinkExp property is set to create hyperlinks from the master report to the detail reports. For information about implementing hyperlinks, see Chapter 12, “Working with frames and controls,” in Developing Advanced e.Reports.

244 P r o g r a m m i n g e . R e p o r t s

Examining a group bursting exampleBurst2.rod uses group bursting. With group bursting, you burst the report on group boundaries and place each group in a different ROI file.

Examining the report structure for a group bursting exampleBurst2.rod contains two group sections. The first group section, OuterStateGroup, is in the master report, and its Before slot contains the summary entry for the group, state. The second group section, InnerGroupSection, is in the detail report. Both group sections have the same key, [customers.state].

Master report

Detail report

Reference to master report’s PageList component

Group section

Summary entry

Group section

C h a p t e r 1 3 , U n d e r s t a n d i n g r e p o r t b u r s t i n g t e c h n i q u e s 245

Examining the detail report’s PageList component for a group bursting exampleThe detail report’s PageList component is a reference to the master report’s PageList component.

Examining the SuggestRoiName( ) method for a group bursting exampleThe detail report’s SuggestRoiName( ) method is overridden to give each detail report a unique name. The value of the summary entry, state, is used to create the name.

Note that there are two versions of the SuggestRoiName( ) method. One version does not take any arguments, and the other takes a data row. This example uses the version that takes a data row.

Function SuggestRoiName( row As AcDataRow ) As StringSuggestRoiName = “State_” & row.GetValue( “state” ) & “.roi”

End Function

If your report design generates a large number of reports, place the reports in different folders. To place the reports in different folders, include a folder in the name returned from SuggestRoiName( ). For example, if your design generates reports for counties in different states and you want to place the reports for each state in a different folder, override SuggestRoiName( ) as follows:

Function SuggestRoiName( row As AcDataRow ) As StringSuggestRoiName = row.GetValue( "state" ) & "/" &

row.GetValue( "county" ) & ".roi"End Function

Examining the summary entry’s LinkExp property for a group bursting exampleThe summary entry’s Linking➛LinkExp property is set to create hyperlinks from the master report to the detail reports. For information about implementing hyperlinks, see Chapter 12, “Working with frames and controls,” in Developing Advanced e.Reports.

246 P r o g r a m m i n g e . R e p o r t s

P a r t 3 , P r o g r a m m i n g w i t h A c t u a t e B a s i c 247

P a r t

Part 3Programmingwith Actuate Basic

248 P r o g r a m m i n g e . R e p o r t s

C h a p t e r 1 4 , I n t r o d u c i n g A c t u a t e B a s i c 249

C h a p t e r

Chapter 14Introducing ActuateBasic

This chapter contains the following topics:

■ About Actuate Basic

■ Programming with Actuate Basic

■ Understanding code elements

■ Adhering to coding conventions

■ Using the code examples

250 P r o g r a m m i n g e . R e p o r t s

About Actuate Basic Actuate Basic is an object-oriented programming language designed for creating sophisticated e.reports and distributing them over the web. It consists of standard Actuate Basic functions and statements, and object-oriented language extensions. Developers use Actuate Basic to augment and extend the functionality of e.Report Designer Professional.

Actuate Basic is similar to other structured programming languages. It provides built-in functions and control structures such as If...Then...Else constructs, and For and While loops. It also supports using variables and creating your own methods and procedures. Actuate Basic is modeled after Microsoft Visual Basic, Version 5. If you program in Visual Basic, you already know a lot about Actuate Basic programming. The difference between the two languages is that Actuate Basic is designed for programming reports and has none of Visual Basic’s form-related syntax.

This chapter introduces Actuate Basic, the elements of the language, syntax, coding conventions, and how to work with various types of data and data structures. The following table lists key features of Actuate Basic.

Feature Supports ... For information, see

Strong data typing Detecting mismatched type errors at compile time instead of at run time.

Chapter 15, “Understanding variables and data types”

User-defined data types Combining variables of different types into a single type.

Chapter 15, “Understanding variables and data types”

OLE automation support

Exchanging information with other applications that support OLE automation.

Chapter 18, “Programming an object from another application”

C h a p t e r 1 4 , I n t r o d u c i n g A c t u a t e B a s i c 251

Programming with Actuate BasicActuate e.Report Designer Professional provides design tools that support dynamic content delivery. Using Design Editor, you create a report by placing components in a report design and setting properties to customize their appearance. e.Report Designer Professional translates the report design into corresponding Actuate Basic code.

You can also write code in Actuate Basic to control the report-generation process, add application-specific logic, or design a report that responds to user-triggered events. To accomplish these tasks, you typically override predefined methods in the Actuate Foundation Classes or create new methods. A method is a procedure declared within a class declaration. It performs actions on the objects of a class. The following example shows a method that adds an item and a separator to a menu:

Sub AddMenuCommands( menu As AcPopupMenu )Super::AddMenuCommands( menu )menu.AddSeparator

menu.AddItem( "Evaluate Discount", me, "OnEvaluateDiscount" )End Sub

For information about classes and methods, see Chapter 2, “Working with a class.” For information about overriding and creating methods, see Chapter 4, “Using Component Editor.”

Programming in Actuate Basic involves writing procedures. The procedures you write can be methods or general procedures available to the entire report. You store a general procedure in an Actuate Basic source (.bas) file. When you include a source file with your report design, you can use the general procedures in it the same way you use Actuate Basic’s built-in statements and functions. For more information about procedures, see Chapter 16, “Writing and using a procedure.”

Calls to external functions

Using functions stored in external libraries. For example, you can create and access a Java object, call a C function, and convert an Actuate Basic string to a Java String.

Chapter 19, “Calling an external function”

Portability Running a report on an NT, Windows, or UNIX server.

Actuate Basic Language Reference

Feature Supports ... For information, see

252 P r o g r a m m i n g e . R e p o r t s

Understanding code elementsTo program in Actuate Basic, you must familiarize yourself with its syntax, naming conventions, control structures, and so on. This section provides an overview of the following standard Actuate Basic code elements:

■ About statements

■ About expressions

■ About operators

About statementsA statement is a complete set of instructions directing Actuate Basic to execute a specific task within a method. A procedure typically contains a series of Actuate Basic statements that perform an operation or calculate a value.

The simplest and most common statement in a procedure is the assignment statement. It consists of a variable name followed by the equal sign and an expression:

<variable> = <expression>

The expression can be as simple or complex as necessary but it must evaluate to a valid data type. For more information about data types, see Chapter 15, “Understanding variables and data types.”

All the following assignment statements are valid:

Area = PI * Radius ^ 2StartTime = StopTime - NowNet_Worth = Assets - LiabilitiesLabel.Text = "Page " & Str$(curPageNum) & " of" & Str$(NumPages)

In these examples, the assignment statement stores information. The value of an expression, which appears to the right of the assignment operator (=) is computed and the result is stored in the variable to the left. The data type of the variable must be the same as that returned by the computed expression.

Statements

Sub SetLabelBackgroundColor( anyControl As AcLabelControl )Dim Label As MyLabelIf GetClassName(anyControl) = "MyLabel" Then

Set Label = anyControlLabel.BackgroundColor = Red

End IfEnd Sub

Procedure

C h a p t e r 1 4 , I n t r o d u c i n g A c t u a t e B a s i c 253

For instance, assigning a double value to an integer variable rounds the double to the nearest integer. If necessary, you can use a function to convert elements of different data types to one common type. For example, the last statement in the previous example uses the Str$ function to convert numbers to character values.

Actuate Basic class statements can be recursive. This means that they can call themselves repeatedly to perform a task. Actuate Basic sets a runtime stack limit of 200. A report that exceeds this limit causes a fatal error in e.Report Designer Professional and e.Report Designer. For example, a report using recursion with a large number of iterations might exceed this limit.

About expressionsAn expression consists of values and operators combined in such a way that the expression evaluates to one of the Actuate Basic data types. The type of the operands in an expression determine the expression type.

In an expression that contains an operation, Actuate Basic considers the types of all operands to determine the type of the result. For example, if you add two integers, the result of the expression is an integer. But if you mix data types in an expression, Actuate Basic makes the result the type of the widest range. For example, the expression 3 * 4.55 results in a double.

To avoid mixing types in an expression, you can use type-declaration characters with numeric constants. These characters force a constant to take on a specific type. For example, 10 is an integer, but 10@ is a currency value. Thus, 10@ + 20@ yields a currency value of thirty dollars or thirty francs, depending on the locale. For more information about type-declaration characters, see “Using a type-declaration character,” in Chapter 15, “Understanding variables and data types.”

About operatorsAn operator is a symbol or keyword that performs an operation, such as adding or comparing, on an expression. Actuate Basic provides the following types of operators:

■ Arithmetic

■ Comparison

■ Logical

■ Concatenation

254 P r o g r a m m i n g e . R e p o r t s

Using an arithmetic operatorUse an arithmetic operator with a numeric expression. You can also use an arithmetic operator with a date expression to subtract one date from another and to add or subtract a number from a date. The following table lists arithmetic operators Actuate Basic supports.

Using exponentiation

The exponentiation operator support computing powers and roots. A power is computed using a positive exponent and a root is computed using a negative exponent. For example 10 ^ 3 evaluates to 1000, 10 cubed. Conversely, 1000 ^ -3 evaluates to 10, the cube root of 10.

Contrasting floating-point with integer division

The floating-point division operator (/) performs standard division and returns a floating-point number. For example, 3/2 returns 1.5 as a floating point, even though both operands are integers. The integer division operator (\) returns only the integer portion of the division. For example, 10\2 evaluates to 5 and 3\2 evaluates to 1.

Using a comparison operatorUse a comparison operator to compare two expressions of the same type and return true or false. Although the equal to (=) operator is the same as the assignment operator (=), Actuate Basic can determine by its context which one to use. The assignment operator is valid only when it immediately follows a variable in an assignment statement. For all other contexts, the = operator is a comparison operator. The following table lists comparison operators Actuate Basic supports.

Operator Description Syntax

^ Exponentiation number ^ exponent

* Multiplication expression1 * expression2

/ Floating-point division expression1 / expression2

\ Integer division expression1 \ expression2

Mod Modulus (remainder) expression1 Mod expression2

BAnd Bitwise And expression1 BAnd expression2

BOr Bitwise Or expression1 BOr expression2

+ Addition expression1 + expression2

- Subtraction expression1 - expression2

C h a p t e r 1 4 , I n t r o d u c i n g A c t u a t e B a s i c 255

Working with logical operatorsUse logical operators to compare two logical expressions and return true or false. The following table lists logical operators Actuate Basic supports.

Operator Description Syntax

> Greater than expression1 > expression2

< Less than expression1 < expression2

>= Greater than or equal to expression1>= expression2

<= Less than or equal to expression1<= expression2

= Equal to expression1 = expression2

<> Not equal to expression1 <> experssion2

Like String comparison expression Like pattern

Is Object reference variable comparison

objectref1 Is objectRef2

Operator Description Syntax

Not Performs a logical negation on an expression. Returns false if expression is true.

Not expression

And Performs a logical conjunction on two expressions. Returns true if both expressions are true. Returns false if either expression is false.

expression1 And expression2

Or Performs a logical disjunction on two expressions. Returns true if one or both expressions are true.

expression1 Or expression2

Xor Performs a logical exclusion on two expressions. Returns true if one but not both of the expressions is true.

expression1 Xor expression2

Eqv Performs a logical equivalence on two expressions. Returns true if both expressions evaluate to the same logical value.

expression1 Eqv expression2

Imp Performs a logical implication on two expressions.

expression1 Imp expression2

256 P r o g r a m m i n g e . R e p o r t s

Using the concatenation operatorThe string concatenation operator (&) combines two strings to produce a new string that contains both original strings. The original strings themselves do not change. The operands must be strings. To concatenate a number with a string, you must convert the number to a string first. For example:

"The cube root of 27 is " & Str$(27 ^ (1/3))

About operator precedenceWhen several operations occur in an expression, Actuate Basic evaluates and resolves each part in a predetermined order. This order is called operator precedence. You can use parentheses to override the order of precedence and force parts of an expression to evaluate before others. Operations within parentheses are always performed before those outside parentheses.

When an expression contains operators from more than one category, Actuate Basic evaluates arithmetic operators first, comparison operators next, and logical operators last. Within an individual category, an operator is evaluated in the order in which it is presented in the tables in the previous sections. All comparison operators have equal precedence. They are evaluated in the left-to-right order in which they appear.

Adhering to coding conventionsYou can write code that is easy to read and understand by using style conventions. For example, you can comment your code to explain its purpose, use a consistent style to name language elements, indent lines of code for nested statements, and break up long statements at logical places. The following sections describe in greater depth common conventions to follow.

Commenting codeCode comments make a procedure easy to understand and maintain, especially if other programmers work with your code. Actuate Basic recognizes two comment markers:

■ The apostrophe (')

■ Rem

Actuate Basic treats characters to the right of a ' character or Rem as comments and does not execute those lines. A comment can follow a statement or occupy an entire line. A comment cannot follow a line continuation character. The following code example shows a comment.

C h a p t e r 1 4 , I n t r o d u c i n g A c t u a t e B a s i c 257

Rem This is a comment that takes up an entire line.'This is a comment that takes up an entire line.Text1.BackGroundColor = Red ' print negative numbers in red.

Breaking up a long statementMost code is written with one Actuate Basic statement to a line and no terminator at the end of the line. Sometimes, however, you must break a long statement over several lines. To do so, use a + continuation character at the beginning of any lines after the first one. For example:

Data1.RecordSource = "SELECT * FROM Titles, Publishers" + & "WHERE Publishers.PubId = Titles.PubID AND + Publishers.State = 'CA'"

Placing short, related statements on a single lineSometimes the code is more readable when you place several related, short statements on the same line. You can place two or more statements on a single line by using the colon separator. For example:

Text1.Text = "Loss" : Red = 255: Text1.BackgroundColor = Red

Indenting codeIndenting lines of code gives a visual clue to the hierarchy of statements, especially if the procedure contains nested procedures and statements. Indentation also makes it easy to see a construct that has unbalanced beginning and ending statements.

Using a consistent naming and style conventionA good naming scheme can help describe and differentiate named elements. For example, you can develop notation to identify the element as a variable, method, or class, or identify its scope or data type. Hungarian notation is one popular naming scheme. In Hungarian notation, a currency (cur) variable of global scope (g) can be named gcurPrimeRate.

You can also use capitalization to improve the legibility of variable, method, and class names. For example, Actuate Basic uses mixed capitalization, which makes it easy to read a descriptive name such as GetFirstContent( ). Actuate Basic is not case sensitive, however, so ThisMethod( ) works exactly the same as thismethod( ).

258 P r o g r a m m i n g e . R e p o r t s

About naming rulesWhen naming an element such as a variable, constant, or procedure, adhere to the following rules:

■ The name can contain up to 40 characters.

■ The first character of the variable name must be a letter. A letter is any upper- or lower-case character in the US ASCII (A-Z and a-z) character set and does not include non-English characters such as å or ô.

■ Subsequent characters in a name can be letters, digits, or the underscore (_) character.

■ You cannot use reserved keywords, such as Function, Type, Sub, If, and End. For a list of reserved keywords, see Appendix B, “Keywords,” in Actuate Basic Language Reference.

■ You cannot use an operator such as *, ^, and %.

■ The name cannot contain spaces.

Using the code examplesActuate products include example code to help you program specific functionality into a report. For more information about using example code, see Chapter 2, “Statements and functions,” in Actuate Basic Language Reference.

C h a p t e r 1 5 , U n d e r s t a n d i n g v a r i a b l e s a n d d a t a t y p e s 259

C h a p t e r

Chapter 15Understanding variablesand data types

This chapter contains the following topics:

■ About variables

■ Declaring an array

■ About data types

■ Working with variant data

■ Working with string data

■ Working with numeric data

■ Working with date data

■ Working with a user-defined data type

■ Working with a CPointer data type

■ Converting a data type

260 P r o g r a m m i n g e . R e p o r t s

About variablesWhen writing Actuate Basic code, you often store values to perform calculations. You can compare values, perform a calculation and store the result, or store values such as global configuration settings. Actuate Basic, like most other programming languages, uses variables to store values. A variable is a named location in memory for temporarily storing data.

Declaring a variableDeclare a variable using the Dim, Global, or Static statements, as shown in the following examples:

Dim Total As IntegerGlobal FileName As StringStatic Counter As Integer

Some implementations of Basic support implicit declaration of variables. Actuate Basic does not. Implicit declaration of a variable means that you can use a variable name in your code without having previously declared it. Because good programming practice discourages implicit variable declarations, Actuate Basic requires that you explicitly declare a variable before using it.

The scope of a variable determines which procedures access the variable. Depending on how and where you declare it, a variable has one of three scopes.

When you add a variable to a class, e.Report Designer Professional generates an appropriate Dim or Static declaration. For more information about the Global, Dim, and Static statements, see Chapter 1, “Language summary,” in Actuate Basic Language Reference.

About global variablesA global variable is accessible from any part of a report. It is useful for storing values that apply to the entire application. Examples of global variables include file names and default paths to data.

Declared with Declared in Scope

Global Declarations section of an Actuate Basic source (.bas) file included with a report design

Global

Dim or Static A procedure or method Local

Dim or Static A class Class

C h a p t e r 1 5 , U n d e r s t a n d i n g v a r i a b l e s a n d d a t a t y p e s 261

The following figure shows an example of an Actuate Basic source (.bas) file with global variables defined in a declaration section.

Although global variables are useful in certain situations, avoid using them. They can contribute to the creation of complex state machines and can make the logic of an application hard to understand. Use a local variable whenever possible.

Creating a global variable using a new source file

To create a global variable using a new BAS file:

1 In e.Report Designer Professional, create the BAS file:

1 Choose Tools➛Library Organizer➛New.

2 In New Library, name the file and select Source File (*.bas). Choose Save.

3 In Library Organizer, choose OK.

A page for creating the source file appears.

2 In the source file, create a declarations section with Declare...End Declare.

3 In the body of the declarations section, declare the global variable.

4 Save the source file.

The report includes the source file as a library.

Creating a global variable using an existing source file

To create a global variable using an existing BAS file:

1 Choose the Actuate Basic source file:

1 Choose Tools➛Library Organizer.

Library Organizer appears.

If the file to include is in Available Libraries, select it and choose Up. If the file to include is not in the list, choose More to search for it.

2 In Library Organizer, choose OK.

A page for creating the source file appears.

Declare

Global XVar As IntegerGlobal YVar As String

End Declare

Basic source (.bas) file

262 P r o g r a m m i n g e . R e p o r t s

2 In the source file, create a declarations section with Declare...End Declare.

3 In the body of the declarations section, declare the global variable.

4 Save the source file.

The report includes the source file as a library.

Initializing a global variable

To initialize a global variable after you declare it:

1 Write a Sub procedure in your source file that assigns an initial value to a global variable.

2 Override the Start( ) method of the report so that it calls the Sub procedure.

When the report runs, an Actuate client product or Actuate iServer initializes the global variable when report generation starts.

Using a local variableA local variable is accessible only within the procedure or method in which you declare it. A local variable is useful for a temporary calculation, such as counting in a For or Do loop. Limiting the scope of a variable supports reusing variable names. For example, if you declare a variable called Total in a procedure and you later write another procedure for a similar task, you can use the variable name Total in the new procedure.

Declare a local variable using Dim or Static:

Dim intTemp As IntegerStatic intPermanent As Integer

Declaring a local variable with Dim

A variable you declare with Dim exists only as long as the procedure or method is executing. When a procedure finishes executing, an Actuate client product or Actuate iServer discards the values of its local variables and reclaims the memory. The next time the procedure executes, its local variables reinitialize.

Declaring a local variable using Static

A variable you declare using Static retains the same data throughout the report generation process. Use Static to retain the value of a local variable to perform tasks such as calculating a cumulative total. In the following example, a function calculates a cumulative total by adding a new value to the total of previous values stored in the static variable Accumulate:

C h a p t e r 1 5 , U n d e r s t a n d i n g v a r i a b l e s a n d d a t a t y p e s 263

Function CumulativeTotal(ByVal Num As Double) As DoubleStatic Accumulate As DoubleAccumulate = Accumulate + NumCumulativeTotal = Accumulate

End Function

If you declare Accumulate using Dim instead of Static, the function does not retain previously accumulated values. The function returns the same value with which you call it.

About class variablesA class variable typically stores values that define the state and attributes of an object of the class. You can declare a class variable using Dim or Static. For more information about class variables, see “About class variables,” in Chapter 2, “Working with a class.”

Declaring an arrayAn array is a series of objects of the same size and data type. Each object in an array is called an array element. Elements in an array are contiguous. You use an index number to differentiate elements.

For example, you can declare an array of integers or an array of doubles, as shown in the following example:

Dim Counters(14) As Integer ' Integers, indexed 0-14 or 1-14, ' depending on the Option Base statement

Dim Sums(50) As Double ' Doubles, indexed 0-50 or 1-50Dim Sums(10 To 20) As Double ' Doubles, indexed 10-20

You can also create a Variant array and populate it with elements of different data types. For example, you can create an array that contains both integers and strings. For more information about working with data types, see “About data types,” later in this chapter.

Using an array, you can set up loops that efficiently manage a number of cases by using the index number. An array has both upper and lower bounds, such as 1-50 or 10-100. Because Actuate Basic allocates space for each index number, avoid declaring an array larger than necessary.

264 P r o g r a m m i n g e . R e p o r t s

About multi-dimensional arraysYou can declare an array with multiple dimensions. For example, a two-dimensional array, called a matrix, has rows and columns. The following statement declares a fixed-size, two-dimensional 10 x 20 Matrix array with bounds:

Dim Matrix(1 To 10, 1 To 20) As Double

Be aware when adding dimensions to an array that the total storage the array requires increases dramatically, especially with a Variant array.

About dynamic arraysSometimes, you do not know in advance exactly how large to make an array. Actuate Basic supports changing the size of an array as the report runs. Such a dynamic array helps you manage memory efficiently. For example, you can use a large array for a short time and reallocate memory to the system when the report completes. The alternative is to declare a fixed-size array of the largest possible size. This approach can cause your process to run low on memory.

To declare a dynamic array, use a statement similar to the following declaration, with nothing between the parentheses, then size the array later using ReDim:

Dim AccordionArray( ) As Double

Changing the size of an arrayTo change the size of an array without losing the data in it, use ReDim with the Preserve keyword. For example, you can enlarge an array by five elements without losing the values of the existing elements:

ReDim Preserve MyArray(UBound(MyArray) + 5)

You can also use ReDim to decrease the size of an array.

About data typesActuate Basic defines a set of standard data types. A data type provides a way to classify data stored in a variable by defining rules that govern how you work with data and what the variable can contain. The Actuate Basic data types include the standard Basic data types as well as data types defined for the Actuate Foundation Classes.

C h a p t e r 1 5 , U n d e r s t a n d i n g v a r i a b l e s a n d d a t a t y p e s 265

Using standard data typesActuate Basic defines standard Visual Basic data types. The following table lists the names and characteristics of these standard data types.

Using an AFC data typeAn AFC data type is either a typedef or a structure:

■ A typedef is an alias for a Basic data type, typically an Integer. Actuate Foundation Classes use typedefs to create a type that has additional rules beyond those a simple Integer provides. These rules govern limitations on range, direct special display formatting, and specify related constants. For example, typedef rules about the numbers that represent colors restrict them to the range between 0 and hexadecimal FFFFFF.

Some types are intended to be enumerations, or enums. An enum is a type in which the value can only be one of its associated constants. For example, a Boolean can only be true or false. Other types can also have constants. In such cases, the constant provides convenient shorthand for a value.

Data type Storage size Range

Integer 4 bytes32 bits

-2,147,483,648 to 2,147,483,647

Long 4 bytes32 bits

-2,147,483,648 to 2,147,483,647

Single 8 bytes64 bits

±2.2250738585072014E-308 to±1.7976931348623158E+308

Double 8 bytes64 bits

±2.2250738585072014E-308 to±1.7976931348623158E+308

Currency 12 bytes96 bits

-39,614,081,257,132,168,796.771975168 to39,614,081,257,132,168,796.771975167

Date 8 bytes64 bits

Dates 1 January 100 to 31 December 9999Times 0:00:00 to 23:59:59

CPointer 4 bytes32 bits

Same as for Unsigned Long

String 1 byte per character

0 to approximately 2,147,483,647 characters or memory limit

Variant As needed Depends on value stored, up to the range of a Double

User-defined (defined with Type)

Defined by elements

Range of each element depends on its fundamental type

266 P r o g r a m m i n g e . R e p o r t s

■ A structure is a group of variables that describe a single item. The structure members can be Basic data types, such as an integer or other AFC-defined structures. In some cases, structures are nested, as in the following example:

AcFontAcSize

For a list of the AFC data types, see Chapter 2, “AFC data types,” in Actuate Foundation Class Reference.

Assigning a data typeA variable has an associated data type. The data type determines what kind of data the variable can store. When you declare a variable, you can explicitly assign a data type to it. If you do not assign a data type to a variable, Actuate Basic assigns it the Variant data type.

There are two ways to assign a data type to a variable:

■ Using the As keyword

■ Using a type-declaration character

Using the As keywordTo declare a variable and assign it a data type using the As keyword, use the following syntax:

Dim <variable> [As <type>]

The following examples show valid variable declarations:

Dim MyAccount As CurrencyDim YourAccount

These examples declare both variables and initialize them to the default value of the data type. For these examples, MyAccount is a Currency variable initialized to 0.00 and YourAccount is a Variant initialized to Empty.

Using a type-declaration characterYou can identify the data type of a variable by appending a type-declaration character to the end of the variable name.

The following table lists the type-declaration characters for Actuate Basic.

Data type Type declaration character

Integer %

Long &

C h a p t e r 1 5 , U n d e r s t a n d i n g v a r i a b l e s a n d d a t a t y p e s 267

The following examples show valid variable declarations:

Dim OurAccount@ ' declare Currency variableDim CustomerName$ ' declare String variableDim QuantitySold% ' declare Integer variable

About constantsFor a value that does not change during the life of a report, Actuate Basic supports declaring a constant. A constant is a reserved memory location of which the content does not change. The following examples set constant values:

Const Pi = 3.14159265358979Const FirstName = "James"Const MyAccount = 25.43

These examples do not contain type declarations. In such cases, Actuate Basic assigns the most appropriate data type. Pi is a Double and FirstName is a String. MyAccount, however, can be a Single, Double, or Currency. In such a case, Actuate Basic assigns the data type that uses the least amount of space, in this case a Single, which is probably not what the programmer intends. To specify that MyAccount is Currency, use the following syntax:

Const MyAccount@ = 25.43@

Constants improve the readability of your code and reduce the chance for typing errors. Although a constant resembles a variable, you cannot change its value. If you attempt to do so, Actuate Basic sends an error message.

Working with variant dataA Variant data type can store all Actuate Basic system-defined data types. When you work with a Variant, you typically do not have to be concerned with the type of data it contains. Actuate Basic performs any necessary conversions.

A Variant variable is a variable that can change its type depending on the program logic. The Variant maintains an internal representation of the data

Single (real) !

Double (real) #

Currency @

String $

Data type Type declaration character

268 P r o g r a m m i n g e . R e p o r t s

type it stores. This internal representation determines how Actuate Basic manages the value when you perform an operation on the variable.

Actuate Basic uses the most compact representation possible to represent the variable. Later operations on the variable can result in its data type changing. You can use the VarType function to determine the data type of a Variant.

A Variant variable contains the special value Empty until you assign another value to it. Use the IsEmpty function to test whether a Variant variable contains a value.

For a small report or frequently used variable, the Variant data type offers a convenient way to declare a variable. A Variant reduces the performance of the program, on the other hand, and can result in unintended conversion of data types. For example, the result of the + operator can be ambiguous when you use it with two Variants. If both Variants are numbers, Actuate Basic adds them. If both Variants are strings, Actuate Basic concatenates them. If one Variant is a string and the other is a number, Actuate Basic first attempts to convert the string to a number. If the conversion fails, a Type mismatch error occurs. To avoid such issues, use fewer Variants and more explicitly typed variables in your code.

Working with string dataA string variable contains text. Although a string can contain digits, you cannot perform mathematical operations on the digits in a string. Within a string, digits are treated as characters. You typically store zip codes and telephone numbers as string data in tables because you do not perform calculations with them.

Declaring a stringYou can declare a variable as a string if it will always contain text and you never expect to treat it as a number in a calculation:

Dim myString As String

You can assign strings to this variable and modify the variable using string functions. Use double quotation marks to delimit a literal string in an expression:

myString = "Actuate Basic"newString = Left(myString,7)

A string variable or argument is a variable-length string. The string grows or shrinks as you assign new data to it.

C h a p t e r 1 5 , U n d e r s t a n d i n g v a r i a b l e s a n d d a t a t y p e s 269

Using binary string dataTraditionally in Basic programs, binary data was stored in a string variable. This technique worked because American National Standards Institute (ANSI) strings were single-byte arrays of characters. Actuate Basic code can read and write binary data on a byte-by-byte basis, using strings and manipulating the standard string functions, regardless of whether the data has a meaningful ANSI equivalent.

Manipulating a stringYou can manipulate a string, including a binary string, using Actuate Basic string functions. There are two types of string manipulation functions, one for ANSI strings and another for binary strings. You can use the ANSI versions without any preparatory steps. To use the binary versions, follow these steps:

1 Place the binary data in a byte array using Get or another function.

2 Assign the byte array to a string. This assignment does not translate the binary data. It simply copies the data into a string variable.

3 Use the binary version of the functions in the following table to manipulate the binary data in the string.

4 Assign the contents of the manipulated binary string back to a byte array.

Function Description

Asc Returns the ANSI character code for the first character.

InStr Returns the first occurrence of one string within another.

InStrB Binary flavor of InStr. Returns the first occurrence of a byte in a binary string.

Mid Returns a specified number of characters from a string.

MidB Binary flavor of Mid. Returns a specified number of bytes from a binary string.

Left, Right Returns a specified number of characters from the right or left sides of a string.

LeftB, RightB Binary flavors of Left and Right. Returns a specified number of bytes from the left or right side of a binary string.

Chr Returns a string containing the ANSI character specified.

270 P r o g r a m m i n g e . R e p o r t s

For information about working with a multibyte character string, see Working with Multiple Locales.

Formatting stringsThe simplest way to format a string is to use the Str function. The syntax is:

Str(<expression>)

When you convert a number to a string using Str, you place either a leading space or a minus sign in front of the string. If the number is positive, the leading space implies the plus sign. If the number is negative, the minus sign goes in front of the string.

For more complicated string formatting, use the more powerful Format function. The syntax is:

Format(<expression>[,<format>])

where:

■ <expression> is any valid expression

■ <format> is a valid named or user-defined format expression

If you try to format a number without providing a value for the parameter format, Format provides the same functionality as the Str function.

For more information about the Format function, see Chapter 2, “Statements and functions,” in Actuate Basic Language Reference.

Comparing stringsThe StrComp function returns a value indicating the result of a string comparison. The syntax for StrComp is:

StrComp(<string1>, <string2>[, <compare>])

where:

■ <string1> is any valid string expression

■ <string2> is any valid string expression

■ <compare> specifies the type of string comparison. The compare argument can be omitted, or it can be 0 or 1. Specify 0, the default, to perform a binary comparison. Specify 1 to perform a textual comparison. If compare is Null, an error occurs. If you omit compare, the Option Compare setting determines the type of comparison by default.

C h a p t e r 1 5 , U n d e r s t a n d i n g v a r i a b l e s a n d d a t a t y p e s 271

The following table shows the return values of a string comparison.

Changing capitalizationThe following table lists four functions to change the capitalization of a string.

Removing spacesThe following table lists the functions to remove leading or trailing spaces from a string.

If StrComp returns

string1 is less than string2 -1

string1 is equal to string2 0

string1 is greater than string2 1

string1 or string2 is Null Null

Function Description

LCase(<string expression>) Returns a variant in which all letters are lower case

LCase$(<string expression>) Returns a string in which all letters are lower case

UCase(<string expression>) Returns a variant in which all letters are upper case

UCase$(<string expression>) Returns a string in which all letters are upper case

Function Description

LTrim(<string expression>) Returns a copy of a string without leading spaces

RTrim(<string expression>) Returns a copy of a string without trailing spaces

Trim(<string expression>) Returns a copy of a string with neither leading nor trailing spaces

272 P r o g r a m m i n g e . R e p o r t s

Embedding a quote in a stringActuate Basic supports embedding a literal quote within a string, as shown in the following example:

The CEO said, "Sales are fantastic!"

To make this sentence into a valid string expression, you must insert an additional set of quotation marks to display each set in the string. Actuate Basic interprets two quotation marks in a row as an embedded quotation mark. To assign the previous string to a variable, use the following code:

Text.Aside = "The CEO said, ""Sales are fantastic!"""

Working with numeric dataActuate Basic offers several data types that can contain numeric data. The type you choose depends on how you use the numbers. The following sections describe the different types of numeric data and when to use each.

About numbersThe Integer and Long data types represent numbers that have no fractional component.

The Single and Double data types can express floating-point numbers. A floating-point number, also called a real number, represents a value that has a fractional component. The term floating point comes from the fact that the decimal point can occur any place within the number, as shown in the following examples:

0.0003 205.333 30000.0

In contrast, the decimal point in the Currency data type is fixed at four places of precision.

If you know that a variable always contains a whole number, such as 45 or 30,000,000,000, rather than a number with a fractional amount, such as 3.14159, declare it as an Integer or Long type. An operations is faster with integers, which consume less memory than Variants. Integers are especially useful as counter variables in For...Next programming constructs.

About currencyThe Currency data type represents monetary values with a precision of four decimal places. Currency variables are stored as 96-bit (12-byte) numbers in an Integer format, scaled by 1,000,000,000 (109) to give a fixed-point number with 20 digits to the left of the decimal point and 9 digits to the right. The Currency

C h a p t e r 1 5 , U n d e r s t a n d i n g v a r i a b l e s a n d d a t a t y p e s 273

data type is useful for calculations involving money and for fixed-point calculations in which accuracy is particularly important. Floating-point numbers have much larger ranges than Currency but they are subject to small rounding errors. Because Currency is a scalar data type, it is not subject to rounding errors within its range.

To ensure that a currency value maintains its precision, append the currency type declaration symbol, @, to the value after you define it. For example:

Dim DollarAmt As CurrencyDollarAmt= 922337203685476.5807@

The above code ensures that DollarAmt is not subject to rounding errors. In this example, if you do not specify the currency type declaration symbol, DollarAmt evaluates to 922337203685477.

Using numeric data typesIf a variable contains a fraction, declare it as a Single, Double, or Currency variable, whichever is appropriate. The Currency data type supports up to 9 digits to the right of the decimal and 20 digits to the left. Currency is a scalable fixed-point data type, especially suitable for monetary calculations because it is not subject to rounding errors. The Single and Double data types are floating-point numbers with much larger ranges than fixed point data types, but are subject to small rounding errors.

You can express a floating-point value as:

mmmmEeee

where

■ mmmm is the mantissa

■ eee is the exponent, a power of 10

You can assign all numeric variables to each other and to variables of type Variant. Actuate Basic rounds off the fractional part of a floating-point number before assigning it to an Integer.

Working with date dataDate variables are stored as IEEE 64-bit floating-point numbers. These numbers represent dates ranging from 1 January 100 to 31 December 9999 and times from 0:00:00 to 23:59:59. You can assign any recognizable literal date value to a date variable. You must enclose a literal date within number sign characters (#) in the following format:

#1/1/2002# or #11/12/2003#

274 P r o g r a m m i n g e . R e p o r t s

Using Date display formatsA date variable uses the short date format your computer recognizes. Times appear in either 12- or 24-hour format, according to the time format recognized by your computer.

When you convert other numeric data types to Date, values to the left of the decimal represent date information and values to the right of the decimal represent time. Midnight is 0 and midday is .5. A negative number represents a date before December 30, 1899.

Formatting date and timeYou can perform mathematical operations on a date or time value. Adding or subtracting an integer operates on the date. Adding or subtracting a fraction operates on the time. The following table lists the Actuate Basic date functions.

You can use date and time literals by enclosing them within number signs (#). For example:

If Today > #2/25/2003# Then ...

Function Description

DateSerial(yyyy,mm,dd) Returns a date or date serial number from the year, month, and day numbers entered. Always specify four-digit years. The supported date range for report scheduling is January 1, 1980 through December 31, 2036, inclusive. The supported date range for all other data processing and display, including database access, is January 1, 100 through December 31, 9999.

Day(x) Extracts the day from a date and returns a number.

Weekday(x) Determines the day of the week for this date and returns it as a number (1 to 7), where Sunday is 1.

Month(x) Extracts the month component of a date and converts it to a number.

Date(x) Returns the current date.

Year(x) Extracts the year from a date and returns a number.

C h a p t e r 1 5 , U n d e r s t a n d i n g v a r i a b l e s a n d d a t a t y p e s 275

You can also include a time:

If Now > #2/25/2003 10:00pm# Then ...

If you do not include a time, Actuate Basic uses midnight as the start of the day. If you do not include a date, Actuate Basic uses December 30, 1899.

You can use the IsDate function to determine whether a Variant or other value can convert to a Date data type. You can then use the CDate function to convert the value to a Date data type.

The user’s locale determines the interpretation of Date literals. To distribute a report to multiple locales, DateSerial is a better choice.

Working with a user-defined data typeActuate Basic’s data types are useful for most of the fundamental report information that is easily represented by strings, numeric data, and dates. Many programs require data that should be logically grouped together. These programs are less prone to error when you create custom, or user-defined, data types. There are three user-defined data types:

■ Aliases

■ Structures

■ Classes

Using an aliasAn alias is the simplest type of user-defined data. When you use an alias, you declare a data type that has the properties of an already existing data type. The syntax is:

Typedef <new data type> As <existing data type>

Typically, the new data type is one of the Actuate Basic data types. The following is an example of an AFC type:

Typedef AcColor As Integer

You can also declare an alias to a structure, as the following example shows:

Typedef MyPoint As AcPoint

Using a structureYou create a user-defined data type as a structure in which the elements contain previously defined data types. These data types can be either Actuate Basic data types or user-defined data types.

276 P r o g r a m m i n g e . R e p o r t s

For example, if you write a program to catalog computers, you can define a structure that represents related information about the computer systems, as the following example shows:

Type SysInfoComputerName As StringCPU As StringMemory As LongDiskDriveType As StringDiskDriveSize As SinglePrice As CurrencyPurchaseDate As Date

End Type

After you declare a structure, you declare a variable of this data type the same way you declare a variable of a fundamental type:

Dim SystemOne As SysInfo, SystemTwo As SysInfo

When you declare a variable, you can assign and retrieve values from the elements of the variable using the dot notation shown in the following example:

SystemOne.Price = 1999.95SystemOne.PurchaseDate = #2/25/03#

You can also assign one user-defined variable to another, provided that both variables are of the same user-defined type. The following example assigns all elements of the first variable to the same elements of the second variable:

SystemTwo = SystemOne

You can nest user-defined types. After you define a data type, you can include it in another user-defined type. Nesting can be as complex as your application requires. To keep your code readable and easy to debug, however, keep all nested user-defined types in one module.

Using a classA class is a user-defined data type that defines the attributes of an object in a report. To create an object, you declare a variable that contains a reference to the object and assign a class as its type. Actuate provides a collection of classes, called the Actuate Foundation Class Library, that you can use. For more information about classes, see Chapter 2, “Working with a class.” For more information about objects, see Chapter 3, “Working with an object.”

Working with a CPointer data typeA CPointer data type variable holds a pointer to data allocated in a C function you create.

C h a p t e r 1 5 , U n d e r s t a n d i n g v a r i a b l e s a n d d a t a t y p e s 277

Converting a data typeActuate Basic provides eight functions to convert a value into a specific data type. For example, to convert a value to Currency, use the CCur function:

WeeklyPay = CCur(hours * rate)

The following table lists the functions for converting a data type.

Function Converts an expression to

CCur Currency

CDate Date

CDbl Double

CInt Integer

CLng Long

CSng Single

CStr String

CVar Variant

278 P r o g r a m m i n g e . R e p o r t s

C h a p t e r 1 6 , W r i t i n g a n d u s i n g a p r o c e d u r e 279

C h a p t e r

Chapter 16Writing and using aprocedure

This chapter contains the following topics:

■ About procedures

■ Declaring a procedure

■ Declaring an argument

■ Calling a procedure

■ Overloading a procedure

■ Using a control structure

280 P r o g r a m m i n g e . R e p o r t s

About proceduresA procedure can simplify programming by breaking a program into smaller logical components. These components can become building blocks that you use to enhance and extend Actuate Basic.

A procedure is useful for condensing a repeated or shared task, such as calculation, text and control formatting, and database operations.

Using procedures has two major benefits:

■ When you break a program into discrete logical units, you can debug these units more easily than an entire program without procedures.

■ You can reuse a procedure in multiple reports, typically without modification.

Actuate Basic supports two types of procedures:

■ Sub procedures do not return a value.

■ Function procedures return a value.

About scope in proceduresIn a report, the procedures you create can have either class or global scope. A procedure you declare in a class is a method. A procedure you declare in an Actuate Basic source (.bas) file is a global procedure. The following sections describe methods and global procedures in more detail.

About methodsA method is a procedure declared within a class. A method performs an action on an object. Because methods have class scope, they are accessible only to objects of that class. For information about creating a method, see “Overriding an inherited method,” in Chapter 4, “Using Component Editor.”

A report typically includes multiple objects of a class. Usually, your code does not need to specify which object is currently executing. Sometimes, however, a method or property refers explicitly to a particular object. The Me keyword supports referring to the object in which the code is running. Use Me as if it were the Name property of the object:

Sub PrintTotal( )Me.Print

End Sub

For more information about programming with objects, see Chapter 3, “Working with an object.”

C h a p t e r 1 6 , W r i t i n g a n d u s i n g a p r o c e d u r e 281

Creating a global procedureA global procedure is accessible from any part of the report. You can create a global procedure by creating a new BAS file or by using an existing BAS file.

The following code example shows an outline of a BAS file that uses global procedure declarations:

SubProcA( )...End SubFunction FuncAr( )...FuncA = <expression>End Function

After you include a module containing procedure declarations, you can call the procedures you defined the same way you call Actuate’s built-in functions and statements.

How to create a global procedure using a new source file

To create a global procedure using a new source file, take the following steps:

1 Create an Actuate Basic source file.

1 Choose Tools➛Library Organizer➛New.

2 In New Library, name the file. Choose Source File (*.bas) in Save as type.

3 Navigate to the directory in which to save the file and choose Save.

4 In Library Organizer, choose OK.

A page for creating the source file appears.

2 In the source file, write the procedures with the Sub or Function statement. Be sure to include parentheses after the procedure name, even if the parentheses are empty.

3 Save the source file.

The source file is included in the report.

How to create a global procedure using an existing source file

To create a procedure that includes an existing Actuate Basic source (.bas) file:

1 Choose the source file:

1 Choose Tools➛Library Organizer.

If the file you want to use is listed in the Library Organizer, select it and choose the Up arrow. If the file you want is not listed, choose More to locate it.

282 P r o g r a m m i n g e . R e p o r t s

2 In Library Organizer, choose OK.

A page for editing the source file appears.

2 In the source file, write procedures using the Sub or Function statement. Be sure to include parentheses after the procedure name, even if the parentheses are empty.

3 Save the source file.

The source file is included in the report.

Declaring a procedureActuate Basic supports two types of procedures, Sub and Function. Sub procedures do not return a value. Function procedures return a value. The following sections describe how to declare Sub and Function procedures.

Declaring a Sub procedureThe syntax for a Sub procedure is:

Sub <procedure name>( [<arguments>] ) <statements>

End Sub

where:

■ <arguments> is an optional list of argument names separated by commas. Each argument looks like a variable declaration and acts like a variable in the procedure. For more information about arguments, see “Declaring an argument,” later in this chapter.

■ <statements> are executed each time the procedure is called. You can place a sub procedure in a global module, where it is accessible throughout the report, or in a class, where it becomes a method that operates on or is accessible only to an instance of that class.

Declaring a Function procedureActuate Basic includes built-in functions such as Chr, Now, and Cos. Each function returns a value with an appropriate data type. For example, Now returns a date value containing the current date and time.

You can write your own procedures using the Function statement. The following example shows the syntax:

C h a p t e r 1 6 , W r i t i n g a n d u s i n g a p r o c e d u r e 283

Function <procedure name>( <arguments> ) [As <type>]<statements><procedure name> = <expression>

End Function

A Function procedure is similar to a Sub procedure in that it can take arguments, execute a series of statements, and change the value of its arguments. The arguments for a function procedure work the same way as arguments for a Sub procedure, with the following differences:

■ Typically, you call a function by including the function procedure name and arguments on the right side of a larger statement or expression. The value the function returns is assigned to the variable on the left of the equal sign.

■ A Function procedure has a data type, just as a variable does, that determines the type of the return value. If you omit the As clause, the function type is Variant.

■ You return a value by assigning it to the procedure name itself within the procedure. When the function returns, this value can become part of the larger expression from which you called the function.

The following example shows how to write a function that calculates and returns the area of a rectangle, given the length and width:

Function RectArea (Width As Single, Length As Single) As SingleRectArea = Width * Length

End Function

Declaring an argumentAn argument is a variable you declare in a procedure declaration. An argument passes a value to the procedure. For example, a procedure that performs a calculation usually requires a value for processing, as shown in the following examples. You pass this value to the procedure when you call it. The arguments are the names the procedure uses for the values you supply. The first value you supply gets the first parameter name in the list, the second value gets the second parameter name, and so on:

Function Sum (Num1 As Integer, Num2 As Integer) As IntegerSum = Num1 + Num2

End Function

Function ExtendedCost (Cost As Currency, Quantity As Integer) As CurrencyExtendedCost = Cost * Quantity

End Function

284 P r o g r a m m i n g e . R e p o r t s

About argument data typesA procedure argument has the Variant data type by default. You can declare another data type for a variable of a procedure argument, however. For example, the following function accepts a string and an integer:

Function ExtractLeftString( S As String, n As Integer)<statements>

End Function

Passing an argument by referenceActuate Basic passes a variable to a procedure by reference. Passing an argument to a procedure by reference gives the procedure access to the variable’s location in memory. Using this information, the procedure can change the value of the variable.

If you declare a data type for an argument passed by reference, you must pass a value of that data type when you call the procedure. You can convert the data type if necessary.

Passing an argument by valueThe ByVal keyword passes a variable by value. When calling an internal procedure, Actuate Basic passes a copy of the value to the procedure. In this case, if the procedure changes the value, only the copy changes, not the original.

When calling an external procedure, Actuate Basic passes the address of the string data. In this case, if the procedure changes the value, the original value also changes. When the procedure finishes, the copy of the variable goes out of scope.

Calling a procedureThe techniques for calling a procedure depend on the type of procedure, where it is, and how your report uses it. The following sections describe how to call Sub and Function procedures.

Calling a Sub procedureA call to a Sub procedure is a stand-alone statement. Because a Sub procedure does not return a value, you cannot call it by using its name within an expression. A Sub procedure, like a Function procedure, can modify values of any variables passed as arguments.

C h a p t e r 1 6 , W r i t i n g a n d u s i n g a p r o c e d u r e 285

There are two ways to call a Sub procedure. These following two examples accomplish the same result:

Call MyProc( Argument1, Argument2)MyProc (Argument1, Argument2)

Calling a Function procedureBecause a Function procedure returns a value, you typically call it by using its name as part of a larger expression. You call a custom function the same way you call a built-in function. All the following examples call a function named UpdateTotal:

Print UpdateTotalNewTotal = UpdateTotalIf UpdateTotal < 0 Then

MsgBox "Error: Total is negative."End If

Overloading a procedure Procedure overloading is an Actuate Basic feature that can make your programs more readable. For example, suppose you write a square root function that operates on integers and another square root function for doubles. In Actuate Basic, you can give both procedures the same name, square_root. By using the name square_root more than once, or overloading it, you give it more than one meaning.

Actuate Basic distinguishes between versions of the function by the type and number of arguments. The following examples show procedures with the same name used in different contexts:

Function square_root( intInput As Integer) As Integer

Function square_root( doubleInput As Double) As Double

Using a control structureA control structure allows you to control the flow of report execution. Most reports contain decision points that allow the application to change statement order with structures and loops.

286 P r o g r a m m i n g e . R e p o r t s

Using If...ThenUse an If...Then block to execute one or more statements conditionally:

If <condition> Then<statements>

End If

The condition is typically a comparison but it can be any expression that evaluates to a numeric value. Actuate Basic interprets this value as a Boolean, meaning that any value other than zero is considered true.

If myDate < Now ThenmyDate = Now Timer.Enabled = True 'Start the timer

End If

Using If...Then...ElseUse an If...Then...Else block to define several blocks of statements, only one of which executes:

If <condition1> Then[<statement block 1>]

ElseIf <condition2> Then[<statement block 2>]

Else[<statement block 3>]

End If

If...Then...Else is the general case of If...Then. You can have any number of ElseIf clauses, or none at all. You can include a single Else clause, but only one, whether or not you have ElseIf clauses.

Using Do...LoopUse a Do...Loop statement to execute a block of statements an indefinite number of times. A Do...Loop statement works well when you do not know how many times to execute the statements in the loop. There are several variations on the Do...Loop statement but each evaluates a numeric conditional as a Boolean to determine whether to continue executing.

The following example first tests the condition statement. If false, the loop code is skipped. If true, the statements execute and the loop repeats until the condition evaluates to false.

Do While <condition><statements>

Loop

C h a p t e r 1 6 , W r i t i n g a n d u s i n g a p r o c e d u r e 287

The following example is a variation of the Do...Loop that guarantees that the loop will execute at least once.

Do<statements>

Loop While <condition>

Using For...NextIf you know how many times to execute a statement, use the For...Next loop. A For...Next loop uses a counter that increments or decrements in value during each step of the loop:

For <counter> = <start> To <end> [Step <step size>]<statements>

Next <counter>

Using a nested control structureYou can place a control structure inside another control structure, such as a For...Next loop within an If...Then block. A control structure inside another control structure is said to be nested.

In Actuate Basic, a control structure can be nested to as many levels as you need. A common practice is to make nested decision structures and loop structures more readable by indenting the body of the decision structure or loop.

Exiting a control structureUsing the Exit For and Exit Do statements, you can exit the corresponding loop without performing any further iterations or statements within the loop.

Exiting a Sub or Function procedureUsing the Exit Sub and Exit Function statements, you can exit a procedure without processing any further statements in it. This approach can be useful when the procedure has performed its tasks and can immediately pass control to the line following its End statement.

288 P r o g r a m m i n g e . R e p o r t s

P a r t 4 , P r o g r a m m i n g i n t h e W i n d o w s e n v i r o n m e n t 289

P a r t

Part 4Programming in theWindows environment

290 P r o g r a m m i n g e . R e p o r t s

C h a p t e r 1 7 , U s i n g a n o b j e c t f r o m a n o t h e r a p p l i c a t i o n 291

C h a p t e r

Chapter 17Using an object fromanother application

This chapter contains the following topics:

■ Adding an object from another application

■ About object linking and embedding

■ Linking and embedding an OLE object

■ Editing an OLE object

■ Inserting an OLE custom control

■ Moving and sizing an OLE component

■ Subclassing an OLE component

292 P r o g r a m m i n g e . R e p o r t s

Adding an object from another applicationWhen designing a report, you can add an object created in another application. For example, you can add a Word document, an Excel spreadsheet, a PDF file, a PaintBrush image, a sound, or an OLE custom control (OCX). This capability is possible through a Microsoft Windows protocol called object linking and embedding (OLE). You can view an OLE object only in the Windows Viewer.

About object linking and embeddingOLE is a Windows protocol for sharing data among applications. To use OLE, one application must be an OLE server and another application must be an OLE container. An OLE server is an application that can create and edit an OLE object. An OLE container is an application that can contain an OLE object. An OLE object is the data shared by the two applications. Examples of OLE objects are documents, spreadsheets, images, and sounds. The file in which the object was created is called the object file.

Some Windows applications, such as Microsoft Word, can serve as both OLE server and container. Actuate reports usually work as OLE containers. Using OLE, an Actuate report can display and manipulate data from other Windows applications that support OLE. Another application, however, cannot display an Actuate report within it. Actuate software is an OLE server for the OCX and ActiveX controls and the Actuate Live Report Extension for Microsoft Internet Explorer.

The following illustration shows a Microsoft Excel spreadsheet as an OLE object in an Actuate report. In this example, Microsoft Excel is the OLE server.

C h a p t e r 1 7 , U s i n g a n o b j e c t f r o m a n o t h e r a p p l i c a t i o n 293

About supported OLE objectsWhen you install an application in Windows, an entry is added to the OLE registry if that application supports OLE. When you insert an OLE object, the Insert Object dialog lists all supported OLE objects. The list of supported OLE objects varies from system to system, depending on which applications are available and which support OLE.

The following illustration shows an example of the Insert Object dialog listing the types of OLE objects supported by a particular system.

About OLE custom controls (OCX)Another type of object you can insert in a report design is an OLE custom control. OLE custom controls are controls, created and distributed by third-party developers, that you can use in Windows 32-bit applications. Microsoft created the concept of the OLE custom control to address the limitations of the Visual Basic custom controls (VBXs), which were designed to work in 16-bit Visual Basic applications.

Supported OLE objects

294 P r o g r a m m i n g e . R e p o r t s

Like a Visual Basic custom control, an OLE custom control has a set of methods and properties you can use to manipulate the control once you insert it in your application. The following illustration is an example of an OLE custom control, a calendar control, in a report frame.

Understanding linking and embeddingYou can incorporate an OLE object into an Actuate report either by creating a link to the object or embedding it in the report. There is no discernible difference between how a linked object and an embedded object appear in the report.

The difference between linking and embedding is that data in a linked OLE object is stored and maintained by the application that created it. Data in an embedded OLE object is stored and maintained by the container application.

Working with a linked objectWhen you link an object, you are inserting a placeholder, not the data, for the linked object into the report. For example, when you link a Paintbrush image in the report, only a reference to the location of the data is stored in the report. The actual data is stored in a Paintbrush file. You can, however, edit the data from within the Actuate report by choosing Edit➛Object to activate the Paintbrush application for editing.

When an OLE object is linked to your report, the object’s data can also be accessed from any other application that contains links to that data. Just as you can edit the data in the OLE object from Actuate software, you or another user can edit the same data from other container applications or from the OLE server application itself.

C h a p t e r 1 7 , U s i n g a n o b j e c t f r o m a n o t h e r a p p l i c a t i o n 295

For example, the Paintbrush image linked to your report can also be linked to a Microsoft Word document. If the image is changed from the Actuate report, Word file, or Paintbrush file, the modified data appears in the Actuate report, the Word document, and the Paintbrush file.

Linking makes it easy to track identical information that appears in multiple applications. Linking supports maintaining one set of data that several applications access.

Working with an embedded objectWhen you embed an OLE object in a report, all the data in the OLE object is stored in the Actuate report. Embedding is useful if you want the report to maintain data that is created and edited in another application. Unlike a linked object, no other application has access to the embedded object. You can edit the OLE object within the Actuate report only. You do so by choosing Edit➛Object to activate the server application for editing.

Changes you make to the OLE object have no effect on the original object. For example, if you embed a PaintBrush image in the report, then edit it in the report, the original image is unchanged. Conversely, changes you make to the original image do not affect the image embedded in your report.

Actuate e.Report Designer Professional - [SalesRpt]

Linked object

Actuate report

Word document

Paintbrush image

296 P r o g r a m m i n g e . R e p o r t s

Guidelines for linking and embeddingUse the following guidelines when deciding whether to link or embed an OLE object in your report.

Linking and embedding an OLE objectThere are two ways to link or embed an OLE object. You can:

■ Select the frame into which to link or embed the OLE object, then choose Insert➛Object.

Insert Object appears.

■ Drag the OLE Container component from the Drawing and Graphics palette to a frame in the structure or layout pane.

Insert Object appears.

To link an OLE object, the object file must already exist. To embed an OLE object, however, you can either use a file that has already been created, or create a new file from within e.Report Designer Professional.

The following sections provide step-by-step procedures for linking and embedding OLE objects.

When to link When to embed

You want the capability to modify the original object file and have those changes reflected in all applications that have a link to that object.

You want the capability to modify the object and have those changes reflected only in the report application.

The original object file is likely to be modified frequently, or modified from multiple OLE container applications.

The original object file is unlikely to be modified, or modified from the report only.

The original object file will not be moved or deleted. Links break when files move to different locations.

The original object file might be moved or deleted.

You are unlikely to distribute the report application.

You want to distribute the report application without worrying about distributing the object files that your report maintains links to.

C h a p t e r 1 7 , U s i n g a n o b j e c t f r o m a n o t h e r a p p l i c a t i o n 297

How to link an OLE object

1 Choose Insert➛Object.

2 Place the object in the structure or layout pane.

Insert Object appears.

3 On Insert Object take the following steps:

1 Select Create from File.

2 Enter the name of the file or choose Browse to select the file to which you want to link.

The file to which you want to link must already exist.

3 Select Link and choose OK.

The content of the file you selected appears in the frame.

How to embed an existing OLE object

1 Place an OLE Container component into a frame.

Insert Object appears.

2 In Insert Object, take the following steps:

1 Choose Create from File.

298 P r o g r a m m i n g e . R e p o r t s

2 Enter the name of a file or choose Browse to select a file containing the object to embed.

3 Choose OK.

The content of the file you selected appears in the frame.

How to create and embed a new OLE object

1 Place an OLE Container component into a frame or select a frame and choose Insert➛Object.

Insert Object appears.

2 In Insert Object, take the following steps:

1 Choose Create New.

2 From the Object Type list, select the type of object to create.

Only objects in which the application can be an OLE server appear in this list.

C h a p t e r 1 7 , U s i n g a n o b j e c t f r o m a n o t h e r a p p l i c a t i o n 299

3 Choose OK.

The OLE server application appears.

3 Create the contents of the OLE object.

Editing an OLE objectAfter you link or embed an OLE object, you can modify it in Design Editor. If the object is linked, you can also edit it in the server application without opening Actuate e.Report Designer Professional.

If you edit a linked object in Design Editor, a separate window opens the object in its application. For example, if you edit a linked Paintbrush image in the report, the Paintbrush application opens and the image appears.

If you edit an embedded object, sometimes a separate application window opens. Sometimes the server application temporarily takes over the Actuate application, replacing the Actuate menus. When the server application takes over the container application, this process is called in-place editing. Microsoft Word, Excel, and WordPad, for example, temporarily replace Actuate’s menus with their own when you edit an embedded Excel or WordPad object. The

300 P r o g r a m m i n g e . R e p o r t s

following illustration shows the Word application taking over the Actuate application when you edit an embedded WordPad document.

How to edit an OLE object

1 Select an object and choose Edit➛Object.

Actuate opens the server application and the object appears.

2 Modify the object.

3 Save the changes and close the window.

Actuate software displays the changes in the report.

Inserting an OLE custom controlThe procedure for inserting an OLE custom control is similar to the procedure for linking and embedding an OLE object. You can:

■ Select the frame into which to insert an OLE custom control then choose Insert➛Object. The Insert Object dialog appears.

■ Drag the OLE Container component from the Drawing and Graphics palette to a frame. The Insert Object dialog appears.

Insert Object displays the list of available OLE controls installed on your system.

C h a p t e r 1 7 , U s i n g a n o b j e c t f r o m a n o t h e r a p p l i c a t i o n 301

How to insert an OLE custom control

1 Select a frame and choose Insert➛Object.

2 Place the control in the frame.

Insert Object appears.

3 Select Create Control.

4 From Object Type, select the control to insert. Choose OK.

The control appears in the frame.

Moving and sizing an OLE componentYou move and size an OLE component the same way you move and size other components in the Layout pane. For more information about OLE components, see Chapter 12, “Working with frames and controls,” in Developing Advanced e.Reports.

The default size of the OLE component is determined by the OLE server application. For example, if you link or embed a Paintbrush image that is 2 inches by 3 inches, that is the size of the image in the report. You can, however, resize the OLE component in the report’s Layout pane. If you do so, it can appear stretched or compressed. Note that only the display size changes. The size of the original image does not change.

302 P r o g r a m m i n g e . R e p o r t s

Subclassing an OLE componentLike other components in your report design, you can subclass an OLE component. For information about how to subclass a component, see Chapter 4, “Using Design Editor,” in Developing Advanced e.Reports.

When you subclass an OLE component, the subclass refers to the superclass’ OLE object, as the following illustration shows. Changes you make to the OLE object in the superclass are reflected in the subclass.

If you modify the OLE object in the subclass, Actuate software creates an independent copy of the OLE object. Changes to the OLE object in the superclass do not affect the object in the subclass, and changes in the object in the subclass do not affect the object in the superclass.

OLEComponent1 displays Paintbrush image

OLEComponent2, a subclass of OLEComponent1, references Paintbrush image in its superclass

C h a p t e r 1 8 , P r o g r a m m i n g a n o b j e c t f r o m a n o t h e r a p p l i c a t i o n 303

C h a p t e r

Chapter 18Programming an objectfrom another application

This chapter contains the following topics:

■ About programming other applications’ objects

■ About OLE Automation

■ Creating an OLE Automation object

■ Working with an OLE Automation object

■ Using an OLE Automation example

304 P r o g r a m m i n g e . R e p o r t s

About programming other applications’ objectsThe previous chapter, “Using an object from another application,” describes how to use object linking and embedding (OLE) to share data with another Windows application. This chapter describes how, using a feature called OLE Automation, you can remotely access and work with an OLE object in another application.

About OLE AutomationOLE Automation is a Windows standard that applications use to expose their OLE objects to development tools, languages, and container applications that support OLE Automation. For example, a spreadsheet application can expose a worksheet, chart, cell, or range of cells as different types of objects. A word processor can expose paragraphs, sentences, bookmarks, or spelling checkers as objects. These exposed objects are called OLE Automation objects.

When an application supports OLE Automation, Actuate software can access the objects it exposes. Use Actuate Basic to call the objects’ methods or set its properties, just as you do Actuate’s native objects.

For example, a report can display additional information stored in an Excel worksheet that users see when they double-click a text control. To create this functionality, you write Actuate Basic code that creates an Excel OLE Automation object, activates it, and displays the worksheet.

Differentiating an OLE Automation object from another OLE objectUnlike an OLE object, an OLE Automation object is accessible only by using a programming language such as Actuate Basic. An OLE Automation object is not visible to the user and typically is used to automate repetitive tasks or tasks that do not involve user interaction. Since it is created using code, an OLE Automation object is temporary and does not remain after the code executes. For this reason, you cannot link or embed an OLE Automation object.

Determining which OLE Automation objects an application supportsBecause each application provides different features, there is no common set of objects. To get a list of objects that an application supports, consult the application’s documentation.

C h a p t e r 1 8 , P r o g r a m m i n g a n o b j e c t f r o m a n o t h e r a p p l i c a t i o n 305

Creating an OLE Automation objectUse the CreateObject function to work with another application’s OLE objects remotely, without creating a linked or embedded OLE object. Before creating an object, you must define a variable that you can use to refer to the object. The following example shoes one such variable:

Dim excelHandle As Object

Then, use the CreateObject function to create the OLE object. This function requires a single string argument that indicates the application name and the type of object to create. Use the following syntax to specify the argument:

"Application.ObjectType"

For example, to specify an Excel worksheet object, supply the following argument:

"Excel.Worksheet"

Use the Set statement to assign to the object variable the object returned by the CreateObject function. For example:

Set excelHandle = CreateObject( "Excel.Worksheet" )

When this code executes, Actuate software starts Excel and creates an OLE Automation object. Unlike the image that appears when you create a linked or embedded object, the OLE Automation object’s image does not appear in Actuate software and Actuate products do not maintain the object’s data.

Working with an OLE Automation objectWork with an OLE Automation object’s properties and methods in the same way you work with any Actuate object. Use the object.property syntax to set or retrieve the object’s properties. Use the object.method syntax to perform actions on the object. To determine an OLE object’s methods and properties, refer to the application’s documentation.

The following code shows examples of working with an Excel worksheet:

' Format the first row in the worksheet as boldexcelHandle.Row(1).Font.Bold = True

' Put the value 100 in the first cellexcelHandle.Cells( 1,1 ).Value = 100

' Save the worksheet and close ExcelexcelHandle.SaveAs( "MySheet.xls" )Set excelHandle = Nothing

306 P r o g r a m m i n g e . R e p o r t s

All OLE objects support some method that closes the object and the application that created it. Since an OLE object can use a significant amount of memory in your Actuate report, it is good practice to explicitly close an object when your report no longer needs it.

There are two ways to close an OLE object and its associated application:

■ Use the object’s method for closing itself. For most objects, the method is either Close or Quit.

■ Set the variable that refers to the object to Nothing, as shown in the following example:

Set ExcelHandle to Nothing

Using an OLE Automation example A Sales Forecast Detail report shows customer orders. Each customer order has an order number and multiple order items. When a user views the report, he or she can right-click an order number and select the Evaluate Discount option from the context menu to get discount information on the order. The discount information is in an Excel worksheet. The report uses OLE Automation to access an existing Excel worksheet that contains the formula for calculating discounts and the format for displaying the results. The OLE Automation code is implemented in a user-defined method called OnEvaluateDiscount( ):

Sub OnEvaluateDiscount( )

' Define the object reference variablesDim excelHandle As ObjectDim workbookHandle As ObjectDim cellHandle As Object

Dim orderSection As AcLevelBreakSectionDim customerSection As AcLevelBreakSectionDim sectionChild As AcFrameDim theItemFrame As ::ItemFrameDim customerTitle As ::CustomerTitleFrameDim creditRating As StringDim purchasePattern As StringDim curSheetRow As Integer

' Create the OLE Automation object and open the appropriate fileSet excelHandle = CreateObject( "Excel.Application" )Set workbookHandle = excelHandle.WorkBooksworkbookHandle.Open( "\Actuate\demo\discount.xls" )excelHandle.Visible = True

C h a p t e r 1 8 , P r o g r a m m i n g a n o b j e c t f r o m a n o t h e r a p p l i c a t i o n 307

' Assign values to the variablesSet orderSection = p_Container.p_ContainterSet customerSection = orderSection.p_ContainerSet customerTitle = customerSection.GetFirstContent

creditRating = customerTitle.creditRating.DataValuepurchasePattern = customerTitle.purchasePattern.DataValue

' Specify the cells in which to display dataSet cellHandle = excelHandle.Cells( 2, 5 )cellHandle.Value = DataValueSet cellHandle = excelHandle.Cells( 2, 6 )cellHandle.Value = creditRatingSet cellHandle = excelHandle.Cells( 2, 7 )cellHandle.Value = purchasePattern

Set sectionChild = orderSection.GetFirstContentcurSheetRow = 10

' Loop through all the order items and enter the values into the cellsDo Until sectionChild is Nothing

If IsKindOf( sectionChild, "ItemFrame" ) ThenSet the ItemFrame = excelHandle.Cells(1, curSheetRow)Set cellHandle = excelHandle.Cells(1, curSheetRow)cellHandle.Value = theItemFrame.itemCode.DataValueSet cellHandle = excelHandle.Cells(2, curSheetRow)cellHandle.Value = theItemFrame.quantity.DataValueSet cellHandle = excelHandle.Cells (3, curSheetRow)cellHandle.Value = theItemFrame.priceQuote.DataValue

curSheetRow = curSheetRow + 1End If

Set sectionChild = orderSection.GetSuccessor( sectionChild )Loop

End Sub

308 P r o g r a m m i n g e . R e p o r t s

The following illustrations show how a user triggers the OnEvaluateDiscount( ) method and the Excel worksheet that appears.

1. Right-click the order number to display context menu

2. Choose Evaluate Discount to get discount information (executes the OnEvaluate-Discount( ) method)

3. Excel worksheet with discount information appears

C h a p t e r 1 9 , C a l l i n g a n e x t e r n a l f u n c t i o n 309

C h a p t e r

Chapter 19Calling an externalfunction

This chapter contains the following topics:

■ Calling an external C function

■ Using a C function with Actuate Basic

■ Declaring a C function

■ Calling a C function

■ Working with a Java object

■ Converting a Java data type

■ About Java exception and error handling

■ Debugging a Java object

310 P r o g r a m m i n g e . R e p o r t s

Calling an external C functionThis section describes how to call a C function in your Actuate Basic report. It does not describe how to program a C function or publish it in a library. Refer to C documentation for that information.

Actuate Basic provides a rich set of statements and functions you can use in your report. Sometimes, however, your program can accomplish more or execute more efficiently using C functions. Actuate Basic supports calling an external C function if the function is accessible to your report. In the Windows environment, an Actuate Basic report can call a C function stored in a dynamic link library (DLL). On a UNIX system, your report can call a C function stored in a shared library.

Many companies and third-party developers supply libraries of C functions. By tapping into the vast resources of C libraries, you can extend the power of Actuate Basic.

A variable that an external call returns must be cleaned up as part of the library unload process. Alternatively, the external library must explicitly implement a memory cleanup function AcCleanup(char *aPointer).

You must implement the AcCleanup function in the external library. Actuate software attempts to call the AcCleanup() defined in the library that manages external memory. If you do not implement AcCleanup(), Actuate software does not call cleanup functions.

Using a C function with Actuate BasicBecause C functions reside in external files, you must provide information to Actuate Basic so that it can find and execute the appropriate C function. There are two basic steps to using a C function:

■ Declare the C function in Actuate Basic using the Declare statement. This step supplies the information Actuate Basic needs to convert and execute the C function.

■ Call the C function as you would an Actuate statement or function. Actuate software loads the library then executes the C function.

You declare the C function only once but you can call it any number of times.

To make a C function accessible to all parts of your Actuate application, write the Declare statements in an Actuate Basic source (.bas) file, using a text or code editor. Then, include the BAS file in your report by choosing Tools➛Library Organizer.

C h a p t e r 1 9 , C a l l i n g a n e x t e r n a l f u n c t i o n 311

Declaring a C functionTo declare a C function, you must provide the following information in the Declare statement:

■ Name of the C function.

■ Name of the library that contains the C function. In Windows, this is the name of a DLL and in UNIX, the name of a shared library.

■ Name with which to call the C function (optional).

■ Arguments that the C function takes.

■ Return value, if any.

For complete syntax information about the Declare statement, see Chapter 2, “Statements and functions,” in Actuate Basic Language Reference.

Declaring the C function as a Sub procedureIf the C function does not return a value, declare it as a Sub procedure, using the following syntax:

Declare Sub <function name> Lib <"library name"> [Alias <"alias name">][(<argument list>)]

The following is an example of a Sub procedure declaration:

Declare Sub LogError Lib "Kernel32"(ByVal uErr As Integer, lpvInfo As Any)

Declaring the C function as a Function procedureIf the procedure returns a value, declare it as a Function procedure, using the following syntax:

Declare Function < function name> Lib <"library name">[Alias <"alias name">][(<argument list>)][As <type>]

The following is an example of a Function procedure declaration:

Declare Function GetSystemMetrics Lib "USER32" (i As Integer) As Integer

Understanding C function declaration issuesTo declare and call a C function, ensure you have documentation on those procedures. A declaration for a C function can become complex for a number of reasons:

■ C often passes arguments by value whereas Actuate Basic, by default, passes arguments by reference.

312 P r o g r a m m i n g e . R e p o r t s

■ C type declarations differ from Actuate Basic type declarations.

■ A C function can have a name that is not a valid identifier in Actuate Basic.

The following sections explain the syntax of the Declare statement in more detail so that you can create the correct declaration for the C function.

Specifying the library of a C functionOn a Windows system, you specify the name of a DLL in the Lib<"library name"> clause. On a UNIX system, you specify the name of a shared library.

<"library name"> can be a file specification that includes a path. For example:

Declare Function GetSystemMetrics Lib "C:\WINNT\SYSTEM32\USER32" (i As Integer) As Integer

If you omit the path, Actuate software searches for the library in the following order:

1 The directory in which Actuate is installed

2 The current directory

3 The Windows system directory

4 The Windows directory

5 The directories listed in the PATH environment variable

If you omit the file extension, Actuate software assumes a .dll extension.

Passing an argument by value or referenceBy default, Actuate Basic passes all arguments by reference. Many C functions, however, expect arguments to be passed by value. If you pass an argument by reference to a procedure that expects an argument to be passed by value, the procedure cannot interpret the data.

To pass an argument by value, use the ByVal keyword before the argument declaration in the Declare statement. Each time you call the procedure, the argument is passed by value. For example:

Declare Function GetFreeSystemResources Lib "User32" (ByVal fuSysResource As Integer) As Integer

The arguments that you pass by reference to C functions are strings and arrays, described later in this chapter.

About flexible argument typesSome C functions can accept more than one type of data for the same argument. To pass more than one type of data, declare the argument using As Any to remove type restrictions. For example, you can declare a procedure as follows:

C h a p t e r 1 9 , C a l l i n g a n e x t e r n a l f u n c t i o n 313

Declare Function SendMessage Lib "User32" (ByVal hWnd As Integer, ByVal msg As Integer, ByVal wp As Integer, ByVal lp As Any) As Long

When you call the function, you can pass either a string or a long integer as its last argument:

FindItem = SendMessage(aList.hWnd, LB_FINDSTRING, -1, target)

Aliasing a non-standard C function nameOccasionally, a C function has a name that is an invalid Actuate Basic identifier. It might start with an underscore, contain a hyphen, or have the same name as an Actuate Basic reserved word. When the C function name is an invalid Basic identifier, use the Alias keyword, as shown in the following example:

Declare Function LOpen Lib "Kernel32" Alias "_lopen" (ByVal fn As String, ByVal f As Integer) As Integer

In this example, you call LOpen in your Basic code. _lopen is the name of the C function in the DLL or shared library.

Use Alias whenever you want to use a different function name from the actual C function name. You can, for example, substitute a shorter name for a long C function name.

Determining an Actuate Basic argument typeTo call a C function from Actuate Basic, you must translate it into a valid Declare statement. The following table lists the Actuate Basic argument types to declare in the Declare statement based on the C argument types of the function you call.

C type Actuate Basic type

int *x, int &x x As Integer

int x ByVal x As Integer

long *x, long &x x As Long

long x ByVal x As Long

double *x, double &x x As Double, x As Single, x As Date

double x ByVal As Single, ByVal As Double, ByVal As Date

1AcCurrency *x x As Currency

AcCurrency x ByVal x As Currency2RWCString *x, RWCString &x x As String

char *x, LPCSTR x (null terminated string)

ByVal x As String

314 P r o g r a m m i n g e . R e p o r t s

Calling a C functionCall a C function as you would an Actuate Basic statement or function, ensuring that you pass the correct arguments. Actuate Basic cannot verify the arguments you pass.

union { int, long, double, AcCurrency, RWCString } *x

x As Variant, x As Any

actual data (int, long, double, AcCurrency, char*)

ByVal x As Variant, ByVal As Any

void**x (pointer to any C/C++ pointer)

x As CPointer

void* x ByVal x As CPointer

int *x, int x[ ] x( ) As Integer, ByVal x( ) As Integer

long *x, long x[ ] x( ) As Long, ByVal x( ) As Long

double *x, double x[ ] x( ) As Single, ByVal x( ) As Single, x( ) As Double, ByVal( ) As Double, x( ) As Date, ByVal x( ) As Date

AcCurrency *x, AcCurrency x[ ] x( ) As Currency, ByVal x( ) As Currency

RWCString **x, RWCString &x[ ] x( ) As String

char **x, char *x[ ] ByVal x( ) As String

void **x, void *x[ ] x( ) As CPointer, ByVal x( ) As CPointer

1. AcCurrency is a C structure with a size of 12 bytes:

struct AcCurrency{

unsigned long low;unsigned long mid;long high;

};

The currency value is stored in fixed point format:

<96-bit integer value in AcCurrency structure> = <currency value> * 109

2. RWCString is a class for string data types provided by Rogue Wave Software, Inc.

C type Actuate Basic type

C h a p t e r 1 9 , C a l l i n g a n e x t e r n a l f u n c t i o n 315

Calling a C function with a specific data typeActuate Basic provides a range of data types, including some, such as variable-length strings, AnyClass, and Object, that C functions do not support. The following sections discuss some of the data-type issues to consider when passing an argument in a function call.

Passing a string to a C functionProcedures in most DLLs expect standard C strings, which end in a null character (binary zero). If a C function expects a null-terminated string as an argument, declare the argument as a string with the ByVal keyword. In a string declaration, the ByVal keyword is misleading because ByVal tells Actuate Basic to convert the string to a null-terminated string, not that the string is passed by value. In fact, strings are always passed to C functions by reference.

Passing an array to a C functionYou pass individual elements of an array in the same way you pass any variable of the same type as the base type of the array. You can also pass an entire array of any type except user-defined types. Actuate copies data in the Actuate Basic array into a C array before passing it to the C function.

If you pass a multidimensional array, the C function reverses the dimensions. For example, if you declared an Actuate Basic array with Dim x (3, 4, 5) As Integer, it is converted to Int x [5][4][3] in C.

Passing an array by value is faster than passing it by reference. Use the ByVal keyword to pass an array whenever possible.

Passing a null pointer to C functionIn Actuate Basic, any of the fundamental data types can be null. Therefore, to pass a null pointer to a C function, use the Null keyword, as the following examples show:

Declare Sub Func1 Lib "LIBABC" (ByVal p As CPointer)Dim ptr As CPointerFunc1(ptr) ' pass CPointer ptr to the C functionFunc1(Null) ' pass null pointer to the C function

Declare Sub Func2 Lib "LIBXYZ" (ByVal s As String)Dim s As Strings = "text"Func2(s) ' pass null-termintated string to the C functionFunc2(Null) ' pass null pointer to the C function

316 P r o g r a m m i n g e . R e p o r t s

Passing a user-defined data type to a C functionYou cannot pass a user-defined data type to a C function.

Passing an object reference variable to a C functionYou cannot pass an object reference variable to a C function. An object reference variable is a complex data structure that C functions cannot manage.

About return values from C functionsThe following table shows how return values convert to Actuate Basic data types.

Working with a Java objectActuate software supports access to Java objects using the Java Native Interface (JNI). Access a Java object from Actuate Basic to perform the following tasks:

■ Create a Java object

■ Invoke an instance method on the instances

■ Invoke a static method on the class of the object

■ Access an instance variable on the instances

■ Access a static variable on the class of the object

About Java requirementsYou must use Java Runtime Environment (JRE) or Java Development Kit (JDK) version 1.2 or 1.3 to access a Java object from Actuate Basic. You must verify the installation of the JRE or JDK. For example, if a required DLL is missing, JRE can close an Actuate report when creating a Java Virtual Machine.

C type Actuate Basic type

int Integer

long Long

double Single, Double, Date

char* (null terminated) String

(char*) NULL String (empty)

any pointer (void*, etc.) CPointer

C h a p t e r 1 9 , C a l l i n g a n e x t e r n a l f u n c t i o n 317

Add the class definitions of the Java classes to the CLASSPATH variable.

How to modify the CLASSPATH variable

1 Choose Start➛Settings➛Control Panel.

2 Choose System.

System Properties appears.

3 Choose Environment.

4 In the list of User Variables, select CLASSPATH.

5 In Value, add the necessary folders, Java Archive (.jar) files, and the current directory to the CLASSPATH.

Separate these items using semicolons. Java is case-sensitive.

6 Choose Set.

7 Choose OK.

Creating a Java objectBefore creating a Java object, you must declare a variable to refer to the object. For example:

Dim theObject As Object

You then use the CreateJavaObject function to create the Java object using the following syntax:

Set theObject = CreateJavaObject("<class identifier>")

Invoking a method and accessing a field on a Java objectYou can invoke the methods of a Java object using the object.method syntax to perform actions on the object. If the method does not exist for the object, Actuate software displays a user error message.

To access a field on the object, name the field following the handle to the object. For example:

someint=theObject.internalValue

To set a field to a specific value, use the following syntax:

theObject.internalValue=10

Use the same syntax to access static fields and methods.

318 P r o g r a m m i n g e . R e p o r t s

Actuate software makes no distinction between code that accesses a field and code that invokes a method without parameters. For example, the following lines of code are considered the same:

someint = theObject.InternalValue() someint = theObject.InternalValue

Similarly, if an instance method and a static method have the same name and the same or similar signatures, Actuate software makes no distinction between them. Specifically, Actuate software makes no distinction between integral data types such as long, short, and int, and float data types such as single and double. For example, there is no distinction between the following methods:

Myfunction(short,short,long)Myfunction(int,int,int)

Invoking a static method and accessing a static fieldYou can invoke a static method and access a static field without instantiating an object of the class. For example:

Dim theClassObject As ObjectSet theClassObject = CreateJavaClassHandle( <classname> )theClassObject.TheStaticMethod( <parameters> ) theClassName.theStaticField = 10

In this example, TheStaticMethod is the name of the method to call and theStaticField is the name of the field to access.

Converting a Java data typeThe following table describes the conversion between Actuate Basic data types and Java data types.

Java data type Actuate Basic type

boolean Boolean

byte Integer

char Integer

double Double

float Single

int Integer

long Integer

C h a p t e r 1 9 , C a l l i n g a n e x t e r n a l f u n c t i o n 319

Converting a Java StringActuate e.Report Designer Professional supports conversions between a Java String and an Actuate Basic string. Actuate software converts only the entire string. Other Actuate string operations do not work on a Java String. e.Report Designer Professional supports the following operations:

■ Converting an Actuate Basic string to a Java String object.

■ Passing an Actuate Basic string to a method expecting a Java String object.

■ Converting a Java String object to an Actuate Basic string.Java String objects do not convert automatically. Use methods on the Java object to copy a string from a Java String object.

Converting a Java nullActuate does not support assigning a Java null to an Actuate data type. In C and C++, Null is a constant defined in a header file, with a value similar to 0, 0L, or ((void*)0), depending on the compiler and memory model options.

In Java, null is a keyword denoting a special value for a reference. Null does not necessarily have a value of 0. You cannot convert it to a primitive data type such as Integer or Boolean.

The workaround is to return an appropriate value instead of null from a method in the Java class file.

Converting an arrayActuate software supports automatic conversion of single-dimension arrays of primitive types to and from Actuate Basic. The assignment operator (=) copies a Java array where each element is a primitive type, such as an int, into an Actuate Basic array. In an assignment operation, you can copy an entire Actuate Basic array of primitive types into a Java array. The operation copies each element in the source array to the destination array until the end of either the source or the destination array. The following example shows how to copy an array of 10 elements:

Object Object

short Integer

void No type

Java data type Actuate Basic type

320 P r o g r a m m i n g e . R e p o r t s

Dim basicIntArr( 10 ) As IntegerDim javaIntArr As ObjectSet javaIntArr = <something returning a Java array>basicIntArr = javaIntArr

‘converting a Java integer array to a Basic array

Access elements in an array using the methods on the array object.

About Java exception and error handlingIn Actuate Basic, the Err function returns an integer value corresponding to each user error. You can use either the number or the constant for error handling. The following table lists the error names, the integer values, and error meanings.

Actuate software captures and keeps the last exception object. You can test for the E_JAVAEXCEPTIONOCCURRED user error and access the exception object using the GetJavaException() function. For example:

Dim javaObj As ObjectOn Error Goto HandleError

Set javaObj = CreateJavaObject( "JavaClassName" )javaObj.TryToDoSomething( ) ' assume this causes a Java Exception

Error name Integer Value Meaning

E_JVMCLASSPATHNOTFOUND

97 Could not get environment variable CLASSPATH

E_JVMCREATEJVMFAILED 98 Failed to create Java Virtual Machine

E_JVMCLASSNOTFOUND 99 Could not find the Java class

E_JVMCREATEOBJECTFAILED

100 Failed to create Java object

E_JVMINVALIDJAVAHANDLE

101 Invalid Java object or class handle

E_JVMMETHODFIELDACCESSFAILED

102 Failed to access a method or a field

E_JVMTYPECONVERSIONFAILED

103 Type conversion failed

E_JAVAEXCEPTIONOCCURRED

104 Java exception occurred

C h a p t e r 1 9 , C a l l i n g a n e x t e r n a l f u n c t i o n 321

' Put code here to handle normal behavior without exception then exit the method

HandleError:

Dim errorCode As IntegererrorCode = Err

If errorCode = E_JAVAEXCEPTIONOCCURRED Then ' Next statement has the same result as above statement ' If errorCode = 104 Then

Dim exceptionObj As ObjectSet exceptionObj = GetJavaException( )If exceptionObj.toString( ) = "SomeJavaExceptionType" Then

' Do something or resume executionEnd If

End If

Debugging a Java objectThe Actuate debugger recognizes all external objects. When the object is declared, the debugger indicates that the type of object is unknown. When the object is created, the debugger shows the object type. A numeric identifier indicates the object. Handles to the same object show the same indicator.

For Java Strings, the debugger indicates that the object is a Java Object and shows the beginning of the string value.

For Java arrays, the debugger indicates that the object is a Java array object and shows the type of the object.

322 P r o g r a m m i n g e . R e p o r t s

P a r t 5 , P r o g r a m m i n g w i t h A c t u a t e ’ s C + + A P I s 323

P a r t

Part 5Programming withActuate’s C++ APIs

324 P r o g r a m m i n g e . R e p o r t s

C h a p t e r 2 0 , U s i n g A c t u a t e ’ s a p p l i c a t i o n p r o g r a m m i n g i n t e r f a c e s 325

C h a p t e r

Chapter 20Using Actuate’sapplication programming

interfacesThis chapter contains the following topics:

■ About the programming interfaces

■ A comparison of API features

■ Choosing the appropriate API

326 P r o g r a m m i n g e . R e p o r t s

About the programming interfacesThis chapter provides an overview of Actuate’s C++ application programming interfaces (APIs) to the Actuate iServer. These APIs include:

■ Report server API

■ Requester API

■ Search extension API

■ ActiveX controls

The following sections provide an overview of each API. The remaining chapters of this Part explain how to work with the Requester and Search extension APIs and the ActiveX controls. For more information on how to choose an API that meets the needs of your organization, see “Choosing the appropriate API,” later in this chapter.

About the Report Server APIThe Report Server API is a set of C++ function calls that govern the administration and configuration of a single Encyclopedia volume and the server. The volume stores report files and related data, such as access privileges and request queues. The server is a set of services that manage the data in the volume and process the requests.

You use the Report Server API to:

■ Integrate Actuate features into existing corporate applications

■ Automate routine or time-consuming tasks

■ Implement new feature groupings for custom business processes

■ Execute Actuate and non-Actuate reports and integrate them into the Encyclopedia volume

For a description of Report Server API classes, see Actuate Report Server API Reference. For an in-depth understanding of Actuate iServer System, see Administering Actuate iServer System.

About the Requester APIThe Requester API is a multiplatform interface for generating, displaying, customizing, and printing reports. This API supports modifying report parameters before generating a new report. Applications built with the Requester API run on both Windows and UNIX platforms.

Use the Requester API to write applications that:

C h a p t e r 2 0 , U s i n g A c t u a t e ’ s a p p l i c a t i o n p r o g r a m m i n g i n t e r f a c e s 327

■ Access attributes and values of report parameters

■ Inspect and change the values of report parameters

■ Generate reports

■ Display reports and print them using an Actuate iServer

■ Configure the printer setup

To display reports, the Requester API works with the Actuate Viewer or End User Desktop. To generate a report locally, the Requester API requires Actuate e.Report Designer, Actuate e.Report Designer Professional, Actuate Active Portal, or End User Desktop.

On a local machine or iServer, you can use the Requester API to run reports in batch mode, create your own requester interface in Visual Basic or C++, or generate a new report when the user activates an external hyperlink.

About the search extension APIThe search extension API is a set of C++ function calls that govern tasks such as setting search parameters, processing search results, and writing startup and cleanup code.

This API extends the search feature of Actuate e.Report Designer, Actuate e.Report Designer Professional, End User Desktop, and ActiveX controls. A search extension application customizes searches initiated from an Actuate user interface, you cannot initiate a search from the API.

Actuate offers prebuilt search extensions for third party applications such as Microsoft Excel, CorVu Graphical Analysis Module, and Brio Technology BrioQuery. Using the search extension API, you can add custom extensions for additional third party applications or build custom analysis tools.

Use the search extension API to support the following use scenarios:

■ Extract the result of a search and display it in another tool

■ Record a set of searches and extractions to run on a regular basis

■ Run a saved search and extract the data to an external application

About the Actuate ActiveX controlsActiveX controls are Microsoft Windows components you use for embedding prebuilt functionality into custom applications. Actuate provides two powerful ActiveX controls, the Actuate Viewer ActiveX control and the Actuate Desktop ActiveX control, that developers can use in custom reporting applications. You use these controls only with Actuate e.Report Designer Professional.

328 P r o g r a m m i n g e . R e p o r t s

A window for viewing reports is the primary component of the Actuate ActiveX controls. Developers place this window in the host application along with other tools to implement the required functionality.

Using the Viewer ActiveX control, developers build applications that display and print reports and navigate through open documents. The Desktop ActiveX control adds the ability to generate new reports locally. The relatively small number of access points and ActiveX control standardization shorten the development cycle for new applications.

Use the Actuate ActiveX controls, to add the following functionality to custom Windows applications:

■ Open and view a report (Desktop and Viewer ActiveX controls)

■ Navigate a report (Desktop and Viewer ActiveX controls)

■ Run a report executable (Desktop ActiveX control only)

■ Print a report (Desktop and Viewer ActiveX controls)

A comparison of API featuresThe following table lists the functional capabilities each Actuate interface provides.

TaskReport server Requester

Search extension ActiveX

Generate reports Yes Yes 1 Yes 2

Print reports Yes Yes Yes

Configure printer Yes Yes Yes 3

View reports Yes 4 Yes

Build a GUI application

Yes

Modify parameters

Yes

Schedule execution and printing reports

Yes

Distribute results Yes Yes

Security features Yes

C h a p t e r 2 0 , U s i n g A c t u a t e ’ s a p p l i c a t i o n p r o g r a m m i n g i n t e r f a c e s 329

Choosing the appropriate APIThis section provides information about factors to consider when choosing an API and offers suggestions about when to use each one.

When choosing an Actuate API, consider the following factors:

■ Operating environmentThe Requester and Report Server APIs operate on Windows and UNIX systems. ActiveX and search extension are Windows-specific interfaces.

■ Feature setAll the APIs support basic reporting. The Report Server API accesses the broadest range of Actuate reporting features, including security, scheduling, and so on. For an overview of the features each API supports, see “A comparison of API features,” earlier in this chapter.

■ Level of abstraction and length of development cycleHigh-level APIs are easier to use and require shorter development cycles. The Actuate ActiveX controls are the simplest to use, followed by the Requester and the search extension, then the Report Server API.

■ User interfaceActuate ActiveX controls are the easiest tools to use to create Windows-based GUI applications to view and generate Actuate reports.

■ Client/server or local modelThe ActiveX, Requester, and Report Server APIs provide access to the Encyclopedia volume. Actuate ActiveX controls and the Requester API can also work locally. The search extension API works only with client applications.

Encyclopedia management

Yes

Custom features Yes

1. Requires local instance of the End User Desktop.2. Requires Desktop ActiveX Control for local report generation.3. Requires user input.4. Requires a local instance of the Actuate Viewer or End User Desktop.

TaskReport server Requester

Search extension ActiveX

330 P r o g r a m m i n g e . R e p o r t s

When to use the Report Server APIUse the Report Server API as an interface for accessing Actuate iServer functionality. Using the Report Server API, you can integrate Actuate reporting features into your existing applications and automate high-volume or routine reporting tasks.

Use the Report Server API when:

■ Your environment consists of varied platforms and operating systems

■ You need full server management and report generation functionality, including the ability to add custom features

■ You have s long design cycle that allows a learning curve

When to use the Requester APIUse the Requester API for client applications running on different platforms and operating systems, where you do not require server management functionality. The Requester API supports modifying the attributes and values of report parameters. Developers use both the Requester and Report Server APIs in applications that require parameter modifications. Client applications often use the Actuate Viewer in conjunction with the Requester API for viewing and navigating reports.

Use the Requester API when:

■ Your environment consists of varied platforms and operating systems

■ You want to view, execute, and print reports, and modify report parameters programmatically

■ You have a moderate-length design cycle

When to use the search extension APIUse the search extension API for customizing the search feature of Actuate e.Report Designer, Actuate e.Report Designer Professional, Administrator Desktop, End User Desktop, and ActiveX controls. Typically, developers use the search extension API to transfer the results of a user-specified search to a third-party application such as Microsoft Excel.

When to use Actuate ActiveX controlsUse the Actuate ActiveX controls to embed Actuate reporting into a Windows application. The Actuate ActiveX controls are the easiest to implement.

C h a p t e r 2 0 , U s i n g A c t u a t e ’ s a p p l i c a t i o n p r o g r a m m i n g i n t e r f a c e s 331

Use the Actuate ActiveX when:

■ You are developing a Windows-based application

■ You want to view, execute, and print reports with the Desktop ActiveX control or view and print reports with the Viewer ActiveX control

■ You have a short design cycle and minimum resources

Using Actuate ActiveX controls, you can quickly build an application that has many of the features of the Actuate Viewer or End User Desktop.

332 P r o g r a m m i n g e . R e p o r t s

C h a p t e r 2 1 , R e q u e s t e r A P I u s e r g u i d e 333

C h a p t e r

Chapter 21Requester API user guideThis chapter contains the following topics:

■ About the Requester API

■ Understanding the Requester API

■ Using the Requester API

■ Understanding API functions by programming tasks

■ Writing a Requester API application

■ Processing a report request

■ Using the Requester API in Actuate Basic

■ Using the Requester API in Visual Basic

■ Using the Requester in a C++ application

334 P r o g r a m m i n g e . R e p o r t s

About the Requester APIThe Requester API controls how and when a report is generated. With this API, you can modify report parameters, then generate, display, and print new reports.

Using the Requester API, you write applications that perform the following tasks:

■ Access attributes and values of report parameters

■ Change the values of report parameters

■ Generate reports

■ Display and print reports

■ Configure the print setup

The Requester API works in conjunction with the Actuate Viewer or End User Desktop to display reports. This interface requires e.Report Designer, e.Report Designer Professional, or End User Desktop to generate reports locally.

For an alphabetic reference of all the functions in the Requester API, see Chapter 22, “Requester API reference.”

Understanding the Requester APIThe way you use the Requester API depends upon how you publish reports within your organization. You can use this API for either:

■ Client-server reporting

In this setting, you use the Requester API on a client machine that interacts with iServer. iServer and Encyclopedia volumes manage your reporting tasks.

■ Local reporting

If you perform your reporting tasks locally using e.Report Designer, e.Report Designer Professional, or End User Desktop, you must use the local reporting features of the Requester API.

You write your application differently for client-server reporting than you do for local reporting. For example, an API application must connect to iServer for client-server reporting but not for local reporting.

C h a p t e r 2 1 , R e q u e s t e r A P I u s e r g u i d e 335

In a UNIX environment, use Requester API only for reports that reside on the server. If reports reside on the client or on both the client and server, you cannot use Requester APIs.

The following sections describe both client-server and local reporting methods, show the required Actuate products for each environment, and explain how the products interconnect.

Working in the client-server environmentThe Requester API, working in conjunction with iServer, uses a client-server architecture to execute, view, and print reports.

The client typically runs the following software components:

■ Requester API

■ Custom API application

■ Actuate Viewer (Windows OS only)

The Actuate Viewer is optional. Use it only if you want your application to display reports on screen. As an alternative, you can use e.Report Designer, e.Report Designer Professional, or End User Desktop. In the UNIX environment, you cannot display reports on a client machine.

The server runs Actuate iServer System.

The following diagram shows a typical client-server configuration for the Requester API.

Working with iServer, your application:

■ In the Encyclopedia volume, references report executable, parameter, and output files using rotp file system syntax:

rotp://<server>/<path>/<filename>[;<version>]

RequesterAPI

Customapplication

Viewer

Actuate iServer

Encyclopediavolume

Client LAN Server

336 P r o g r a m m i n g e . R e p o r t s

■ Observes iServer security by programmatically logging in as a valid user with Read and Execute privileges on the desired reports.

■ Prints reports by specifying a printer the server recognizes.

■ On Windows platforms, views reports locally by launching a local copy of the Viewer, e.Report Designer, e.Report Designer Professional, or End User Desktop. Viewing reports is optional for Windows-based applications. If you are simply generating reports, you do not need the Viewer, e.Report Designer, e.Report Designer Professional, or End User Desktop. In the UNIX environment, you cannot display reports on the client machine.

Working locallyLocal reporting uses e.Report Designer, e.Report Designer Professional, or End User Desktop rather than iServer for report generation. In the local configuration, the client machine contains the applications required to generate, view, and print reports. You cannot work locally in the UNIX environment. A typical local configuration consists of Requester API and e.Report Designer, e.Report Designer Professional, or End User Desktop.

Working locally, your Requester application:

■ References report executable, parameter, and output files on a local hard drive, using standard operating system syntax:

<drive>:\<path>\<filename>

■ Generates and displays reports locally. You specify the location of the application that compiles and displays the report. You choose report executable, parameter, and output files using standard file system conventions.

■ Prints reports locally by specifying a printer the local operating system recognizes.

Using the Requester APIYou can use the Requester API to run reports in batch mode, create your own requester interface in Visual Basic or C++, or generate a new report when an external hyperlink is activated. These tasks can be accomplished on a local machine or on iServer.

Using this API, you can inspect and change parameter values before generating a report. If you want to change, add, or delete the definitions of report parameters, you must do so in the report design itself.

C h a p t e r 2 1 , R e q u e s t e r A P I u s e r g u i d e 337

The following subsections provide details about the development and operating environments for the Requester API.

Actuate Client Integration Technology includes examples for the Requester API in \Program Files\Actuate7\ClntIntTech\RequesterAPI\Examples.

About the Requester API development environmentRequester API applications run on Windows or UNIX platforms. You access the Requester API through a library of methods defined by header or declare statements and an API library file.

Identifying the APIs to your applicationYou identify an API to your application according to the programming language you plan to use:

■ Actuate BasicCall the Requester API functions as you would any other Actuate Basic function.

■ Visual BasicDeclare the Requester methods in a code module using the Declare statement. The reqapivb.txt file contains declarations for all Requester API methods.

■ C or C++Include the reqbasic.h header file.When programming in C or C++, you declare strings as BSTRs. For more information, see “Working with a BSTR in the Windows environment,” later in this chapter.

Selecting a compiler and other toolsThe following table lists the supported development platforms for Release 7 of the Requester API, along with the required tools for each. Actuate distributes Rogue Wave headers and libraries as part of the Actuate Server Integration

338 P r o g r a m m i n g e . R e p o r t s

Technology. You can obtain other supported development tools, including Solaris, HP-UX, and AIX C++ compilers, from their manufacturers.

Windows 98, XP Professional, and ME are supported as deployment environments. UNIX C is not supported. On HP-UX, the HP ANSI C++ compiler is required.

Choosing API filesThe Requester API uses dynamic link libraries (.dll) and compiled libraries (.lib) during execution. Actuate periodically updates the DLLs to enhance features, correct problems, and support different development environments. This section explains how to choose the correct DLL version for your application.

Platform Supported tools

Windows NT and 2000 Actuate BasicVisual Basic 6.0Visual C++ 6.0Rogue Wave SourcePro Core 8.0

Solaris Actuate BasicSun C++ 5.0Sun Forte 6 (C++ 5.1)Sun Forte 6 Update 1 (C++ 5.2)Sun Forte 6 Update 2 (C++ 5.3)

HP-UX Actuate BasicHP aC++ A.03.27 on HP-UX 11.x

IBM AIX Actuate BasicIBM VisualAge C++ 5.0

C h a p t e r 2 1 , R e q u e s t e r A P I u s e r g u i d e 339

Understanding API file name conventions

The following table summarizes the naming conventions for files the Requester API uses.

Choosing a Requester API file

When choosing an API file for your application, use the library files that correspond to the DLLs for the release you are using. For example, if you are using acrs7060.dll, the corresponding library file is acrs7060.lib.

Choosing a DLL file for the Windows environmentFor the Requester API, refer to the following table for the correct DLL. All file names in the table have the .dll file extension.

DLL File Name

Report server API DLL acrsxxyy.dll■ xx = Report server API version

yy = Visual C++ version (6.0)Example: acrs7060.dll

RogueWave DLL acrxxyy.dll■ xx = RogueWave version

yy = Visual C++ version (6.0)Example: acr7060.dll

Requester API DLL acrqxxyy.dll■ xx = Report server API version

yy = Visual C++ version (6.0)Example: acrq7060.dll

Actuate release VC++ 6.0

7.0 acrq7060

6.0, 6.0 Service Pack 1 acrq6060

5.0, 5.0 Service Pack 1, 5.0 Service Pack 1 Patch 1

acrq5060

4.0 to 4.1 acrq4060

340 P r o g r a m m i n g e . R e p o r t s

The Requester API requires the Report Server API DLL when you run your application. Refer to the following table to determine the correct DLL. All file names in the table have the .dll file extension.

You generally specify the path to the library files in your development environment or copy the DLLs to your system directory. If you use e.Report Designer Professional, the library files are in the \Program Files\Actuate7\ErdPro\Lib directory and the DLL files are in the \Program Files\Actuate7\ErdPro\Bin directory.

Working with UNIX libraries and path variablesWhen linking your UNIX application, set the library path to the shared library for your specific UNIX system.

Make sure the environment variable AC_SERVER_HOME is set to the Server Integration Technology installation directory.

About the Requester API operating environmentA client machine running an application using the Requester API requires up to three components:

■ Actuate Viewer, e.Report Designer, or e.Report Designer Professional

To view reports you need the Actuate Viewer. To run reports locally, you need e.Report Designer. Applications that generate reports on iServer do not require any of these components.

■ Custom application using the Requester API

■ Requester API DLL for your system

Actuate release VC++ 6.0

7.0 acrs7060

6.0, 6.0 Service Pack 1 acrs6060

5.0, 5.0 Service Pack 1, 5.0 Service Pack 1Patch 1

acrs5060

4.0 to 4.1 acrs4060

Operating system Shared library Path variable

SunOS libreqstapi.so LD_LIBRARY_PATH

HP-UX libreqstapi.sl SHLIB_PATH

AIX libreqstapi_share.a LIBPATH

C h a p t e r 2 1 , R e q u e s t e r A P I u s e r g u i d e 341

When using the Requester API with the Actuate Viewer, you must copy the viewer executable file to the client system and set up the operating environment.

Using the Requester API with the Actuate ViewerYou can use the Actuate Viewer to display reports for your application if you set up the client machine as follows:

1 Install the Viewer.

2 Copy Acrq7060.dll to your Windows system directory or set the PATH environment variable to the location of the DLL. If you copy the DLL, copy it to the correct directory for your platform:

3 Install your API application.

4 Verify that the Temp directory is accessible on the server that runs the Requester API.

Understanding API functions by programming tasksThis section categorizes and lists the Requester API functions by the following general programming tasks:

■ Writing startup and cleanup code

■ Working with report files

■ Getting the parameter and parameter group names

■ Getting the parameter attributes

■ Getting the default parameter values

■ Getting the current parameter values

■ Setting parameter values

■ Configuring a printer

■ Running, viewing, and printing reports

■ Checking for errors

Platform Copy DLL to:

Windows NT and Windows 2000

System32 directory

Windows 95/98 System directory

342 P r o g r a m m i n g e . R e p o r t s

For a complete description of each function, see Chapter 22, “Requester API reference.”

Writing startup and cleanup codeThe following table lists the functions for starting and ending usage of the Requester API.

Applications must call AcReqSelectClient or AcReqSetEUDTPath to select the client product. AcReqSelectClient supersedes AcReqSetEUDTPath and is the recommended method for new applications.

Working with report filesWhen using the Requester API functions, you typically work with the following files:

■ Report parameter values (.rov)

The report parameter values file contains a report request’s parameter definitions and values. Actuate creates the parameter values file automatically when users issue a request. You open a parameter values file to access and manipulate parameter values. As an alternative, open a report executable (.rox) file. After setting parameter values, you write the information to a report parameter values file. You then use the report parameter file to generate a report based on the specified parameter values.

Programming task API function

Select the client product to use for client-side viewing, printing, and running reports.

AcReqSelectClient

Specify the End User Desktop application to use to generate a report (.roi).

AcReqSetEUDTPathAcWReqSetEUDTPath

Initialize the API. This step is required before the program can call any of the other API functions.

AcReqInitialize

Connect to the server if the program accesses files on a server.

AcReqConnectAcWReqConnect

Disconnect from the server after the program has finished executing tasks on the server.

AcReqDisconnect

Close the library and free resources used by the API.

AcReqUnInitialize

C h a p t e r 2 1 , R e q u e s t e r A P I u s e r g u i d e 343

■ Report executable (.rox)

The executable file contains the report request’s parameter definitions as well as other information. Actuate creates the executable file when you build and run a report design. You open either a parameter values or executable file to access and manipulate parameter values.

■ Report document (.roi)

From the API, you can display or print a report document on a local system or iServer at any time.

Specifying a local file name—Requester APIWhen specifying file names as arguments to the Requester API functions, you must specify the full path if the file you want to access is not in the current directory. For example, if code in a report opens an .rov file in a different directory, specify the full path name of the .rov file as an argument to AcReqReadFile.

Specifying an iServer file name—Requester APIThe following is the syntax for specifying server file names as arguments to API functions:

rotp://[<user>:<password>@]<server>/<path>/<filename>[;<version>]

Include the user name and password when multiple users are issuing requests to generate the same report or read or write the same parameter values or report executable file.

<user>Optional. The name of the user submitting the request.

<password>Optional. The password for the user submitting the request.

<server>Optional. The name of the server. If you omit this argument, uses the server to which the program is currently connected.

<path>The full path to the directory in which the file resides.

<filename>The name of the file to access.

344 P r o g r a m m i n g e . R e p o r t s

<version>Optional. The version of the file to use. If you omit this argument, uses the latest version of the file. The following table lists the values you can specify.

The following examples are valid arguments for AcReqViewReport, one of the Requester API functions that requires the filename argument:

AcReqViewReport( "rotp://Paradise/MyDir/MyReport.roi", AC_REQ_VIEW )AcReqViewReport( "rotp://Paradise/MyDir/MyReport.rov;Latest", AC_REQ_VIEW )AcReqViewReport( "rotp://Paradise/Accounting/July2002/AcctRpt.roi", AC_REQ_VIEW )AcReqViewReport( "rotp://Paradise/Accounting/July2002/AcctRpt.roi;15", AC_REQ_VIEW )

The following table lists the functions for working with report files.

Getting the parameter and parameter group namesAt design time, you can organize parameters into logical groups. For example, a parameter group Customer can contain the parameters Name, Credit_rank, and Purchase_volume. A parameter group Office can contain the parameters City and State.

Value Description

Latest The most recent version of the file

Oldest The oldest version of the file

LatestDev The most recent development version of the file

LatestRel The most recent released version of the file

<#> The version number of the file

<version name> The version name of the file

Programming task API function

Open an .rov or .rox file to access information about the parameters.

AcReqReadFileAcWReqReadFile

Get the version number of a generated report.

AcReqGetReportVersion

Create a new .rov file to store parameter values you set.

AcReqWriteFileAcWReqWriteFile

Close an open .rov or .rox file. AcReqCloseFile

C h a p t e r 2 1 , R e q u e s t e r A P I u s e r g u i d e 345

The Requester API provides functions for getting the names of parameter groups and parameters in the order in which they appear in the Requester dialog in e.Report Designer and e.Report Designer Professional. You can use this information, for example, to create a custom Requester dialog with a Visual Basic form. You also use the parameter names as arguments to other functions that set or retrieve parameter values.

Getting the parameter attributesAt design time, each parameter is assigned a variety of attributes, such as its data type, whether it is required or optional, or whether or not it is ad hoc. The Requester API provides functions for getting information on each parameter’s attributes. You cannot change these attributes with the API.

Programming task API function

Get the name of the first parameter group.

AcReqGetFirstGroupAcWReqGetFirstGroup

Get the name of the next parameter group.

AcReqGetNextGroupAcWReqGetNextGroup

Get the name of the first parameter. AcReqGetFirstParameterAcWReqGetFirstParameter

Get the name of the next parameter. AcReqGetNextParameterAcWReqGetNextParameter

Specify how parameter names are retrieved.

AcReqSetScopedParameterName

Programming task API function

Get a parameter’s alias name. The alias name appears as a prompt in the Requester dialog.

AcReqGetAliasAcWReqGetAlias

Determine if a parameter is required or optional.

AcReqGetRequiredAcWReqGetRequired

Determine if a parameter can only be set programmatically.

AcReqGetHiddenAcWReqGetHidden

Determine whether a parameter was defined to display asterisks or actual text as users type the value in the Requester.

AcReqGetHideTextAcWReqGetHideText

Determine if a parameter is an ad hoc parameter.

AcReqGetAdhocAcWReqGetAdhoc

346 P r o g r a m m i n g e . R e p o r t s

Getting the default parameter valuesAt design time, you must assign a default value to required parameters. The default value is used if a value is not supplied when the report runs. The following table lists the functions for getting default parameter values.

Getting the current parameter valuesThe current value of a parameter is the value last entered in the parameter values (.rov) file. If you access a parameter values file and need to find the values of parameters, use the functions the following table describes. If you are accessing an executable file, the parameter values are the default values defined at design time.

Get the data type of a parameter as a string.

AcReqGetParmTypeAcWReqGetParmType

Get the data type of a parameter as an enumeration.

AcReqGetTypeAcWReqGetType

Programming task API function

Programming task API function

Get the default value of a parameter of any type as a string.

AcReqGetDefaultValueStrAcWReqGetDefaultValueStr

Get the default value of a parameter of type currency as a currency.

AcReqGetDefaultValueCurrencyAcWReqGetDefaultValueCurrency

Get the default value of a parameter of type date as a date.

AcReqGetDefaultValueDateAcWReqGetDefaultValueDate

Get the default value of a parameter of type double as a double.

AcReqGetDefaultValueDoubleAcWReqGetDefaultValueDouble

Get the default value of a parameter of type integer as an integer.

AcReqGetDefaultValueInteger

Get the default value of a parameter of type string as a string.

AcReqGetDefaultValueStringAcWReqGetDefaultValueString

Determine if a parameter has a default value assigned.

AcReqHasDefaultValueAcWReqHasDefaultValue

C h a p t e r 2 1 , R e q u e s t e r A P I u s e r g u i d e 347

Setting parameter valuesThe following table lists the functions you use to set parameter values. Assign a value whose type matches the parameter type. Before assigning a value to a parameter, you can check the parameter’s type by calling AcReqGetParmType. The following table lists functions for each data type.

Programming task API function

Get the current value of a parameter of type currency as a currency.

AcReqGetValueCurrencyAcWReqGetValueCurrency

Get the current value of a parameter of type date as a date.

AcReqGetValueDateAcWReqGetValueDate

Get the current value of a parameter of type double as a double.

AcReqGetValueDoubleAcWReqGetValueDouble

Get the current value of a parameter of type integer as an integer.

AcReqGetValueIntegerAcWReqGetValueInteger

Get the current value of a parameter of type string as a string.

AcReqGetValueStrAcWReqGetValueStr

Get the current value of a parameter of type string as a string. Use AcReqGetValueString instead of AcReqGetValueStr if you need to pass an argument.

AcReqGetValueStringAcWReqGetValueString

Programming task API function

Set the value of a parameter of type currency.

AcReqSetValueCurrencyAcWReqSetValueCurrency

Set the value of a parameter of type date.

AcReqSetValueDate AcWReqSetValueDate

Set the value of a parameter of type double.

AcReqSetValueDoubleAcWReqSetValueDouble

Set the value of a parameter of type integer.

AcReqSetValueIntegerAcWReqSetValueInteger

Set the value of a parameter of type string.

AcReqSetValueStringAcWReqSetValueString

348 P r o g r a m m i n g e . R e p o r t s

Configuring a printerIf you do not want to use your system’s default printer or its default settings, you can change the printer and the printer settings before printing a report. The following table lists the functions related to printers.

Running, viewing, and printing reportsThe following table list the methods you use to run, view, and print reports.

Programming task API function

Specify a printer to use. AcReqSetPrinterName AcWReqSetPrinterName

Specify the number of copies to print. AcReqSetPrinterNumberCopies

Specify the page orientation as Portrait or Landscape.

AcReqSetPrinterOrientation

Specify the size of the image to print. AcReqSetPrinterScale

Turn color printing on or off. AcReqSetPrinterColor

Turn duplexing on or off.1 AcReqSetPrinterDuplex

Turn collating on or off. AcReqSetPrinterCollate

Specify the paper size by its type (Letter, Legal, and so on) or physical size.2

AcReqSetPrinterFormName AcWReqSetPrinterFormName

Specify the paper size with specific dimensions.

AcReqSetPrinterPaperSize

Revert to the system’s default printer. AcReqSetDefaultPrinter

Specify the paper tray. AcReqSetPrinterTray

1. UNIX servers do not support this feature.2. UNIX servers support logical size but not physical size.

Programming task API function

Specify the priority for reports generated on iServer.

AcReqSetRequestPriority

Generate a report (.roi) based on an existing .rov file or an .rov file you created with new parameter values.

AcReqGenerateReportAcWReqGenerateReport

Print a report. AcReqPrintReportAcWReqPrintReport

Display a report. AcReqViewReport AcWReqViewReport

C h a p t e r 2 1 , R e q u e s t e r A P I u s e r g u i d e 349

You must call AcReqSelectClient or AcReqSetEUDTPath before printing, viewing, or running a report locally.

Running a report locallyWhen you call AcReqGenerateReport to generate a report, Actuate automatically runs the report executable file (.rox) associated with the report object value (.rov) file you specify. It looks for the .rox in the same directory in which the parameter values file resides. If the .rox is not located in the same directory as the .rov, Actuate displays an error message and provides a dialog for you to find the .rox.

To run a report in batch mode, specify the executable file programmatically. To do so, set the .rox file name parameter, represented by the constant AC_REQ_ROX, to the name of the executable file to use before you write the parameter values to a new parameter values file. The .rox file name parameter is hidden and can only be set programmatically. It does not appear in the Requester dialog.

To set the .rox file name parameter, use AcReqSetValueString as the following code snippet shows:

' Specify the .rox file to use to generate the reportAcReqSetValueString( fileNum, AC_REQ_ROX, "C:\Test\Myreport.rox" )

'Write the parameter values you set to a new .rov file. This file is in a'different directory from the .rox fileAcReqWriteFile( fileNum, "Myreport.rov" )

'Generate a report based on the .rov file you createdAcReqGenerateReport( "myreport.rov", AC_REQ_GENERATE, 0)

If the executable file to run is in the same directory as the parameter values file, you do not have to set the .rox file name parameter.

Checking for errorsThe way you check for errors an API function encounters depends upon the types of tasks the function performs. Some functions do not have sufficient information to return error codes. For a list of these functions, see “Functions that do not support error checking,” later in this chapter. For a list of functions that provide error checking, see “Functions with direct error checking,” later in this chapter.

For functions that support error checking, you check for errors the functions encounter in one of the following ways:

■ Examine the return value from the API function

■ Call the API functions designed to return error conditions

350 P r o g r a m m i n g e . R e p o r t s

To check the last error that occurred and return an error number, call AcReqGetError. To check the last error that occurred and return the error description, call AcReqGetErrorString or AcWReqGetErrorString. To check the generation status of a report on a server, call AcReqReportStatus.

Functions with direct error checkingYou use the return value directly to check on any errors the following functions encounter:

AcReqConnectAcReqDisconnectAcReqInitializeAcReqReportStatusAcReqUninitializeAcWReqConnect

Functions that do not support error checkingYou cannot check on any errors the following functions encounter:

AcReqSetDefaultPrinter AcReqSetEUDTPath AcReqSetPrinterCollate AcReqSetPrinterColorAcReqSetPrinterDuplexAcReqSetPrinterFormNameAcReqSetPrinterNameAcReqSetPrinterNumberCopies AcReqSetPrinterOrientationAcReqSetPrinterPaperSizeAcReqSetPrinterScaleAcReqSetPrinterTrayAcReqSetRequestPriorityAcWReqSetEUDTPath AcWReqSetPrinterFormNameAcWReqSetPrinterName

Writing a Requester API applicationAll Requester API applications support a common set of core operations. This section explains how to build two simple applications which set parameters and generate a new report. These applications demonstrate two types of reporting:

C h a p t e r 2 1 , R e q u e s t e r A P I u s e r g u i d e 351

■ Client-server reporting using iServer. Written in C++.

■ Local reporting using the End User Desktop. Written in Visual Basic.

Before trying out the following examples, set up your development environment as described in “Using the Requester API,” earlier in this chapter.

Writing an application that uses iServerYou build a Requester API application that generates, displays, and prints reports using iServer in six steps:

1 Initialize an API session.

2 Connect to iServer.

3 Specify parameters.

4 Run the report, specifying options such as viewing.

5 Print the report.

6 Close the API session.

The C++ example code is divided into small member functions for clarity. An actual implementation would likely combine these segments into a larger procedure. The server name and file names are hard-coded to a specific environment. For a practical example, see “Using the Requester in a C++ application,” later in this chapter.

Initializing an API sessionThe following example initializes the Requester library, prepares the API for a new session by calling AcReqInitialize, and declares the application’s variables:

#include <reqbasic.h>static long fileNum;static long sessionHandle;static long connectionHandle;

void CReqReportDlg::OnSession() {

// Initialize sessionsessionHandle = AcReqInitialize();

}

Connecting to iServerThe gateway to the Encyclopedia volume is the iServer connection. iServer enforces security by requiring a user name and password before validating a connection and allowing server requests. Once established, the server

352 P r o g r a m m i n g e . R e p o r t s

connection generally remains active for an entire session. Other methods use the server connection handle to invoke server functionality. The following C++ code example establishes a server connection:

void CReqReportDlg::OnConnect() {

// Connect to the Report ServerconnectionHandle = AcReqConnect("Kilauea", "Administrator", "");

}

In this case, the application uses a fixed login account on Kilauea called Administrator. The user name and password must represent a valid account on the server and the user must have permission to access and run the desired reports. The Administrator account is a special account for system administrators. The client application usually uses other accounts the server system administrator sets up.

Specifying parametersYou must set two parameters prior to report execution:

■ RoiFileName —the name of the output report file

■ RoxFileName —the name of the report executable file

You can also set additional parameters as part of the report design. You set both the required and optional parameters before running the report. This example has an optional parameter called customers_creditrank.

You first get parameters from either an .rox or .rov file, then set the parameter values. Prior to executing the report, you must store the parameters either in a temporary file that AcReqGenerateReport creates or in an .rov file that you create. This example uses the .rox file as the report generation argument, eliminating the need to save the parameters in an .rov file. For a different method of setting parameters and running a report using an .rov file, see “Generating a report,” later in this chapter.

The following example shows how to specify parameters in C++. It assumes you have a report Detail.rox in a folder Western on the server and you have established a connection:

void CReqReportDlg::OnParameters() {

// Read the .rox from the server.fileNum = AcReqReadFile( "rotp://Kilauea/Western/Detail.rox");// Set the parameter specifying the output .roi nameAcReqSetValueString( fileNum, "RoiFileName", "/Western/Detail.roi"); // Set the parameter specifying the .rox file to be used for report AcReqSetValueString( fileNum, "RoxFileName", "/Western/Detail.rox");// Set a report-specific paramaterAcReqSetValueString( fileNum, "customers_creditrank", "C");

}

C h a p t e r 2 1 , R e q u e s t e r A P I u s e r g u i d e 353

You specify the report locations using the rotp format. This format tells the Requester API to look for the file in the Encyclopedia volume. You do not need to use the rotp format for the parameters RoiFileName and RoxFileName because the server location is implied.

Running and viewing the reportYou submit a request for report generation with AcReqGenerateReport. This example generates a report from the .rox using the parameters you set in the previous example. Since this example does not use an explicit .rov parameter file, the server creates a temporary one in the Encyclopedia volume before running the report.

The following code segment shows how to request report generation in C++. The rotp format in the file specifier tells the API to look for the report in the Encyclopedia volume and execute it on the server:

void CReqReportDlg::OnExecute() {

// Generate Reportlong requestHandle = AcReqGenerateReport (

"rotp://Kilauea/Western/Detail.rox",AC_REQ_GENERATE + AC_REQ_VIEW,fileNum);

}

When requesting report generation, you specify one or more options in the second argument of AcReqGenerateReport. With the options specified in this example, the server generates the report (AC_REQ_GENERATE) and a local viewer displays the report (AC_REQ_VIEW).

Printing the reportTo print a report using server resources, set the printer name and invoke the AcReqPrintReport method. Specify a printer the server recognizes. If you do not specify a printer, the server uses the default printer for the report:

void CReqReportDlg::OnPrint() {

// Specify printer and print reportAcReqSetPrinterName( "HP LaserJet IIP”);requestHandle = AcReqPrintReport( "rotp://Kilauea/Western/Detail.roi",0);

}

Closing the API sessionThe final step in building a Requester API application is cleanup code. In this step, you need to close the file, disconnect from the server, and close the API session as the following example shows:

354 P r o g r a m m i n g e . R e p o r t s

void CReqReportDlg::OnClose() {

AcReqCloseFile( fileNum );AcReqDisconnect(connectionHandle);AcReqUnInitialize(sessionHandle);

}

Writing an application for local reportsYou build a Requester API application that generates and prints reports locally on the client machine in six steps:

1 Declare Visual Basic Methods.

2 Initialize an API session.

3 Specify parameters.

4 Run the report, specifying options such as viewing and printing.

5 Print the report.

6 Close the API session.

When working with reports locally, you do not need a connection to the server.

The Visual Basic code segments in this section are broken into small segments for clarity. An actual implementation would likely combine these small segments into a larger procedure. For a more practical example, see “Using the Requester API in Visual Basic,” later in this chapter.

Declaring a Visual Basic methodActuate e.Report Designer Professional provides a file, reqapivb.txt, that contains all the function declarations. If you installed e.Report Designer Professional in the default location, the file is located in \Program Files\Actuate7\ErdPro. To declare Visual Basic methods:

1 Open reqapibvb.txt in a text editor or word processor.

2 Copy the function declarations you want.

3 Paste the function declarations into a general code module.

4 Declare other global variables.

Basic function declarations appear as follows:

Declare Function AcReqInitialize Lib "Acrq7060.dll" ( ) As LongDeclare Function AcReqUnInitialize Lib "Acrq7060.dll" _ (ByVal sessionHandle As Long ) As Boolean' Other declarations ...Dim sessionNum As Integer

C h a p t e r 2 1 , R e q u e s t e r A P I u s e r g u i d e 355

Initializing an API sessionInitialize the Requester DLL and prepare the API for a new session by calling AcReqInitialize. When working locally, specify the location of the e.Report Designer or e.Report Designer Professional you want to generate and display the report by calling AcReqSetEUDTPath:

Private Sub Form_LoadsessionNum = AcReqInitialize

AcReqSetEUDTPath (RunViewExe)End Sub

Specifying parametersYou must set two parameters prior to report execution:

■ RoiFileName —the name of the output report file

■ RoxFileName —the name of the report executable file

You can also set additional parameters as part of the report design. You set both the required and optional parameters before running the report.

You first get parameters from either an .rox or .rov file, then set the parameter values. Prior to executing the report, you must store the parameters either in a temporary file that AcReqGenerateReport creates or in an .rov file that you create. This example uses an explicit .rov file so it saves the parameters in a .rov file before running the report. For a different method of setting parameters and running a report from a .rox file, see “Specifying parameters,” earlier in this chapter.

The following example shows how to specify parameters in Visual Basic. It assumes you have a report Detail.rox in a folder Example on your C: drive:

Private Sub SetParameters()Dim fileNum As Long

' Open detail.rox to access the parameter definitionsfileNum = AcReqReadFile("C:/Example/Detail.rox")' Set parameter valuesAcReqSetValueString fileNum, "RoiFileName", "C:/Example/Mydetail.roi"AcReqSetValueString fileNum, "RoxFileName", "C:/Example/Detail.rox"AcReqSetValueString fileNum, "customers_creditrank", "C"' Write the parameter values to Mydetail.rovAcReqWriteFile fileNum, "C:/Example/Mydetail.rov"' Close the fileAcReqClosefile(fileNum)

End Sub

356 P r o g r a m m i n g e . R e p o r t s

Generating a reportYou submit a request for report generation with AcReqGenerateReport, using either an .rox or .rov file. When specifying the .rov, as this example does, you need to pass the fileNum variable from the preceding example as an argument to the method.

The following code segment shows how to request report generation in Visual Basic. The standard Windows file specification in the file specifier tells the API to look for the report in the local file system and execute it on the specified End User Desktop. The End User Desktop generates the report (AC_REQ_GENERATE).

Private Sub GenerateReport( )Dim ret As Long' Specify the End User Desktop application to generate the reportAcReqSetEUDTPath ("C:/Program Files/Actuate7/ErdPro/Bin/Runview.exe")' Generate the reportret = AcReqGenerateReport _

("C:/Example/Mydetail.rov", AC_REQ_GENERATE, 0)End Sub

Viewing a reportTo view the report the previous example report generated, add the following line to the procedure:

AcReqViewReport "C:/Example/Mydetail.rov", AC_REQ_VIEW

Printing a reportTo print a report using server resources, set the printer and invoke the AcReqPrintReport method. Specify a printer the local operating system recognizes:

Private Sub PrintReport( ) Dim ret As Long AcReqSetDefaultPrinter ret = AcReqPrintReport( "C:/Example/Mydetail.roi", AC_REQ_PRINT )End Sub

As an alternative, you can print the report by specifying the AC_REQ_PRINT option in the AcReqGenerateReport command.

Closing a sessionTerminate the API session by calling AcReqUnInitialize:

Private Sub Form_UnLoad( Cancel As Integer )AcReqUnInitialize( sessionNum )

End Sub

C h a p t e r 2 1 , R e q u e s t e r A P I u s e r g u i d e 357

For more information about writing the code to implement these steps, see “Using the Requester API in Visual Basic,” later in this chapter.

Processing a report request Building an application using the Requester API functions supports submitting and checking requests that must be processed in a specific sequence. To minimize the administrative overhead on iServer, make multiple requests using the same connection rather than connecting and disconnecting for each request.

The following code example illustrates one way of submitting and checking server requests using the Requester API:

g_pendingRequestList <- empty listwhile (some_condition_is_true) {

# --- Submit new requests herewhile (we_want_to_submit_new_request) {

declare l_requestID variable

# Set up a report and then set# l_requestID <- AcReqGenerateReport(... asynchronous submission ...)# Record requestID as a pending request and one we are waiting# to hear back fromadd l_requestID to g_pendingRequestList

}# --- Make sure we are not busy-waiting, i.e., continually cycling through# this loop without pause: sleep for an arbitrary time, or sleep for enough# time to make sure the statements after the pause are hit only once # every N seconds.sleep(5);# --- Check for completion of pending requests here# Requester API version:for (each l_requestID in g_pendingRequestList) {

if (AcReqReportStatus(requestID) <> AC_REQ_ACTIVE) {# Report has completed or failed, or maybe there's an API failure

... do what is necessary after report is done, or after API failure ...

# We are no longer waiting for this requestIDremove requestID from g_pendingRequestList

}

When you submit a request and the report fails, a temporary .rov file remains on iServer so you can resubmit the request. If you resubmit the request using

358 P r o g r a m m i n g e . R e p o r t s

the Requester API, use the .rox file name rather than the .rov file name as the following example shows:

Function AcReqGenerateReport( filename As String, options As Long, fileNumber As Long ) As Long

Using the Requester API in Actuate BasicOne typical use of the Requester API is generating a new report before activating a hyperlink that connects one report to another. This feature, called dynamic hyperlinks, has two advantages over a hyperlink between two existing reports:

■ The information in the destination report is current because it is generated just before the hyperlink is activated.

■ The dynamic hyperlink does not rely on an existing destination report.

For information about hyperlinks, see Chapter 12, “Working with frames and controls,” in Developing Advanced e.Reports.

Generating a report in Actuate Basic This example shows how to generate a new report before activating a hyperlink. You override the OnLButtonDown function of a control in the source report. To generate the report, you click the left mouse button on the control:

Function OnLButtonDown( view As AcReportView, Shift As AcShiftKeyState,+ x As Integer, y As Integer ) As Boolean

Dim fileNum As Long Dim theErrorStr As String Dim theError As Integer Dim ret As Long Dim value as String' Options for AcReqGenerateReport

Dim generateReport As IntegerDim viewRpt As Integer ' Views reportDim printRpt As Integer ' Prints Report

Dim stayopen As Integer ' Keeps the EUDT openDim async As Integer ' Runs asynchronouslyDim always As Integer ' Launches EUDTDim hide As Integer ' Hides EUDT

Dim opts As LongDim DetailRox as StringDim SmallDetailRoi As StringDim SmallDetailRov As String

C h a p t e r 2 1 , R e q u e s t e r A P I u s e r g u i d e 359

DetailRox = "C:\Program Files\Actuate7\ErdPro\Examples\Detail\detail.rox"SmallDetailRoi = "C:\Program Files\Actuate7\ErdPro\Examples\Request\ab\

Smdetail.roi"SmallDetailRov = "C:\Program Files\Actuate7\ErdPro\Examples\Request\Ab\

Smdetail.rov"

AcReqSetEUDTPath("C:\Program Files\Actuate7\ErdPro\Bin\Runview.exe") fileNum = AcReqReadFile( DetailRox ) If (AcReqGetError(fileNum)) Then MsgBox (AcReqGetErrorString(fileNum))

Exit Function End If value = GetValue()

AcReqSetValueString( fileNum, "RoiFileName", SmallDetailRoi ) AcReqSetValueString( fileNum, "RoxFileName", DetailRox ) AcReqSetValueString( fileNum, "orders_orderID", value ) AcReqWriteFile( fileNum, SmallDetailRov ) If (AcReqGetError(fileNum)) Then MsgBox (AcReqGetErrorString(fileNum))

OnLButtonDown = FalseExit Function

End If AcReqCloseFile( fileNum) ' Set the options to view the small report

generateReport= TrueviewRpt = TrueprintRpt)= Falsestayopen= Trueasync = Falsealways = Truehide = Falseopts = 0If ( generateReport = True ) Then

opts = AC_REQ_GENERATEEnd IfIf ( viewRpt = True ) Then

opts = opts + AC_REQ_VIEWEnd IfIf ( printRpt = True ) Then

opts = opts + AC_REQ_PRINTEnd IfIf ( stayopen = True ) Then

opts = opts + AC_REQ_STAY_OPENEnd IfIf ( async = True ) Then

opts = opts + AC_REQ_ASYNCEnd If

360 P r o g r a m m i n g e . R e p o r t s

If ( always = True ) Thenopts = opts + AC_REQ_LAUNCH_ALWAYS

End IfIf ( hide = True ) Then

opts = opts + AC_REQ_HIDEEnd If

ret = AcReqGenerateReport(SmallDetailRov, opts, 0)If ret > 0 Then theErrorStr = AcReqGetErrorString(ret)

MsgBox theErrorStrOnLButtonDown = FalseExit Function

End If

OnLButtonDown = TrueEnd Function

Using the Requester API in Visual BasicThis section describes how to access the Requester API from Visual Basic. Two programming examples show how to use the API.

Accessing the Requester API from Visual BasicTo access the Requester API, you must declare the functions in a general code module. Actuate e.Report Designer Professional provides a file, reqapivb.txt, that contains all the declarations. If you installed e.Report Designer Professional in the default location, the file is located in \Program Files\Actuate7\ErdPro. Open reqapibvb.txt in a text editor or word processor, copy the function declarations you want, and paste them into a code module.

Specifying the DLL in the Declare statementIf you type the declarations yourself, you must use a relative path name to the DLL. You must also ensure that the directory in which the DLL resides is in the search path, for example, the current directory or a directory defined in the PATH environment variable. Hard-coding a full path name to the DLL in the Declare statement causes problems. The following examples show of a valid and an invalid Declare statement:

' Valid statementDeclare Function AcReqReadFile Lib "Acrq7060.dll" (ByVal fileName As

String) As Long' Invalid statement

Declare Function AcReqReadFile Lib "C:\Libraries\Acrq7060.dll" (ByValfileName As String) As Long

C h a p t e r 2 1 , R e q u e s t e r A P I u s e r g u i d e 361

Manipulating parameter values, generating and printing a reportThis example shows how to generate a report, print a report, get and set parameter values, and get parameter names from a Visual Basic form.

The following illustration shows the sample Visual Basic form and identifies the procedure with each button. The code for each procedure follows the illustration.

Declaring the Requester API functions

Open reqapivb.txt in a text editor or word processor, copy all the function declarations, and paste them into a general code module. In the same code area, declare the variables the test application uses. Edit these definitions to suit your environment as the following example shows:

Private Const DetailRox As String = "C:/Examples/Detail/Detail.rox"Private Const MyDetailRoi As String = "C:/Examples/Detail/Mydetail.roi"Private Const RunViewExe As String = "C:/Bin/Runview.exe"Private Const SourceRox As String = "C:/Examples/Request/Vb/Source.rox"Private Const MyTypesRov As String = "C:/Examples/Request/Vb/Mytypes.rov"Private Const SourceRoi As String = "C:/Examples/Request/Vb/Source.roi"Private Const RotpHost As String = "kilauea"Private Const RotpUser As String = "Administrator"Private Const RotpPassword As String = ""Private Const RotpFolder As String = "/Western"Private Const RotpObjectName As String = "detail"Private Const RoiParmName As String = "RoiFileName"Private Const RoxParmName As String = "RoxFileName"

GenerateReport_Click( )

PrintReport_Click( )

AllTypes_Click( )

FindParms_Click( )

ViewServerReport_Click( )

GenerateServerReport_Click( )

When a user clicks one of these buttons, the procedure executes:

362 P r o g r a m m i n g e . R e p o r t s

Dim genReport As BooleanDim viewRpt As BooleanDim printRpt As BooleanDim stayopen As BooleanDim async As BooleanDim always As BooleanDim hideEUDT As BooleanDim sessionHandle As Long

Initializing the Requester API

Private Sub Form_Load() sessionHandle = AcReqInitialize AcReqSetEUDTPath (RunViewExe)End Sub

Generating and viewing a report locallyPrivate Sub GenerateReport_Click() Dim fileNumber As Long Dim ret As Long fileNum = AcReqReadFile(DetailRox) If (AcReqGetError(fileNum)) Then MsgBox (AcReqGetErrorString(fileNum)) End If ' Set report parameters AcReqSetValueString fileNum, "RoiFileName", MyDetailRoi AcReqSetValueString fileNum, "RoxFileName", DetailRox AcReqSetValueString fileNum, "customers_creditrank", "C" ' Set the options to view the report genReport = True viewRpt = True printRpt = False stayopen = True async = False always = True hideEUDT = False opts = 0 If (genReport = True) Then opts = AC_REQ_GENERATE End If If (viewRpt = True) Then opts = opts + AC_REQ_VIEW End If If (printRpt = True) Then opts = opts + AC_REQ_PRINT

C h a p t e r 2 1 , R e q u e s t e r A P I u s e r g u i d e 363

End If If (stayopen = True) Then opts = opts + AC_REQ_STAY_OPEN End If If (async = True) Then opts = opts + AC_REQ_ASYNC End If If (always = True) Then opts = opts + AC_REQ_LAUNCH_ALWAYS End If If (hideEUDT = True) Then opts = opts + AC_REQ_HIDE End If ret = AcReqGenerateReport(DetailRox, opts, fileNum) AcReqCloseFile fileNumEnd Sub

Printing the report locallyPrivate Sub PrintReport_Click() Dim ret As Long AcReqSetDefaultPrinter ret = AcReqPrintReport(SourceRoi, AC_REQ_PRINT)End Sub

Getting and setting parameter values

The following code assumes that the parameters aCurrency, aDate, aDouble, aInteger, and aString are defined for the report design:

Private Sub AllTypes_Click() Dim fileNumber As Long Dim inDouble, outDouble As Double Dim inInteger, outInteger As Integer Dim inLong, outLong As Long Dim inString, outString As String Dim inDate, outDate As Date Dim inCurrency, outCurrency As Currency inDouble = 0.0345 inInteger = 321 inLong = 987654 inString = "Hello In" inDate = CDate(#12/6/1967#) inCurrency = 123324.567 fileNumber = AcReqReadFile(SourceRox) If (AcReqGetError(fileNumber)) Then

364 P r o g r a m m i n g e . R e p o r t s

MsgBox (AcReqGetErrorString(fileNumber)) End If outCurrency = AcReqGetDefaultValueCurrency(fileNumber, "aCurrency") outDate = AcReqGetDefaultValueDate(fileNumber, "aDate") outDouble = AcReqGetDefaultValueDouble(fileNumber, "aDouble") outInteger = AcReqGetDefaultValueInteger(fileNumber, "aInteger") outString = AcReqGetDefaultValueString(fileNumber, "aString") AcReqSetValueCurrency fileNumber, "aCurrency", inCurrency AcReqSetValueDate fileNumber, "aDate", inDate AcReqSetValueDouble fileNumber, "aDouble", inDouble AcReqSetValueInteger fileNumber, "aInteger", inInteger AcReqSetValueString fileNumber, "aString", inString AcReqWriteFile fileNumber, MyTypesRov AcReqCloseFile fileNumber fileNumber = AcReqReadFile(MyTypesRov) If (AcReqGetError(fileNumber)) Then MsgBox (AcReqGetErrorString(fileNumber)) End If outCurrency = AcReqGetValueCurrency(fileNumber, "aCurrency") outDate = AcReqGetValueDate(fileNumber, "aDate") outDouble = AcReqGetValueDouble(fileNumber, "aDouble") outInteger = AcReqGetValueInteger(fileNumber, "aInteger") outString = AcReqGetValueString(fileNumber, "aString") AcReqCloseFile fileNumberEnd Sub

Getting the parameter name

Private Sub FindParms_Click() Dim CurrentGroup As String Dim CurrentParameter As String Dim Alias As String Dim Required As Boolean Dim Hidden As Boolean Dim HideText As Boolean Dim Adhoc As Boolean Dim ParmType As String fileNumber = AcReqReadFile(DetailRox) CurrentGroup = AcReqGetFirstGroup(fileNumber) Do While (CurrentGroup <> "") CurrentParameter = AcReqGetFirstParameter(fileNumber, CurrentGroup) Do While (CurrentParameter <> "")

C h a p t e r 2 1 , R e q u e s t e r A P I u s e r g u i d e 365

Alias = AcReqGetAlias(fileNumber, CurrentParameter) Required = AcReqGetRequired(fileNumber, CurrentParameter) Hidden = AcReqGetHidden(fileNumber, CurrentParameter) HideText = AcReqGetHideText(fileNumber, CurrentParameter) Adhoc = AcReqGetAdhoc(fileNumber, CurrentParameter) ParmType = AcReqGetParmType(fileNumber, CurrentParameter) CurrentParameter = AcReqGetNextParameter _

(fileNumber, CurrentGroup) Loop CurrentGroup = AcReqGetNextGroup(fileNumber) Loop AcReqCloseFile (fileNumber)End Sub

Generating a report on iServer

Private Sub GenerateServerReport_Click() Dim connectionHandle As Long Dim requestHandle As Long Dim rov As String Dim rox As String Dim rsRoi As String Dim rsRox As String Dim fileNumber As Long ' Connect to the report server connectionHandle = AcReqConnect(RotpHost, RotpUser, RotpPassword) ' Build the file names based on the set properties 'rov = "rotp://" + RotpHost + RotpFolder + "/" + RotpObjectName + ".rov" rox = "rotp://" + RotpHost + RotpFolder + "/" + RotpObjectName + ".rox" rsRoi = RotpFolder + "/" + RotpObjectName + ".roi" rsRox = RotpFolder + "/" + RotpObjectName + ".rox" ' Read the .rov from the server fileNumber = AcReqReadFile(rox) ' Specify where the report server should generate the .roi AcReqSetValueString fileNumber, RoiParmName, rsRoi AcReqSetValueString fileNumber, RoxParmName, rsRox ' Set the report parameters AcReqSetValueString fileNumber, "customers_creditrank", "C" ' Generate the report requestHandle = AcReqGenerateReport _

(rox, AC_REQ_GENERATE, fileNumber) AcReqCloseFile fileNumber AcReqDisconnect (connectionHandle)End Sub

366 P r o g r a m m i n g e . R e p o r t s

Viewing a report on iServer

Private Sub ViewServerReport_Click() Dim connectionHandle As Long Dim roi As String ' Connect to the server connectionHandle = AcReqConnect(RotpHost, RotpUser, RotpPassword) ' Build the file names based of the set properties roi = "rotp://" + RotpHost + RotpFolder + "/" + RotpObjectName + ".roi" ' View the report AcReqViewReport roi, AC_REQ_VIEW AcReqDisconnect (connectionHandle)End Sub

Closing the Requester API library

Private Sub Form_Unload(Cancel As Integer) AcReqUnInitialize (sessionHandle)End Sub

Creating a custom dialog for requesting parameter valuesThis example shows how to replace Actuate’s requester interface with a custom interface that prompts users to supply values for report parameters when users run an executable file. The following are general guidelines for implementing a custom Requester interface:

1 The Requester program must read in the parameter values (.rov) file specified at the command line.

2 After reading in the values from the parameter values file and manipulating them, the Requester program must write out the new parameter values to the same parameter values file.

3 You assign the name of the Requester program executable file to the CustomRequesterName property of the topmost report object in your report design. The topmost report object is a subclass of AcReport.

The following illustration shows the Visual Basic form, the custom requester interface. The code to implement the custom requester follows the illustration. In this example, the custom requester retrieves only one parameter.

C h a p t e r 2 1 , R e q u e s t e r A P I u s e r g u i d e 367

Declaring Requester API functions and global variables

In a general code module, declare the Requester API functions to call:

Private Declare Function AcReqInitialize Lib "Acrq7060.dll" () As LongPrivate Declare Function AcReqUnInitialize Lib "Acrq7060.dll" _

(ByVal sessionHandle As Long) As LongPrivate Declare Function AcReqReadFile Lib "Acrq7060.dll" _

(ByVal fileName As String) As LongPrivate Declare Sub AcReqWriteFile Lib "Acrq7060.dll" _

(ByVal fileNumber As Long, ByVal fileName As String)Private Declare Sub AcReqCloseFile Lib "Acrq7060.dll" _

(ByVal fileNumber As Long)Private Declare Function AcReqGetValueString Lib "Acrq7060.dll" _

(ByVal fileNumber As Long, ByVal aParmName As String) As StringPrivate Declare Sub AcReqSetValueString Lib "Acrq7060.dll" _

(ByVal fileNumber As Long, ByVal aParmName As String, _ByVal aValue As String)

Private Declare Function AcReqGetErrorStr Lib "Acrq7060.dll" _(ByVal fileNumber As Long) As String

' Declare global variablesDim fileName As StringDim fileNum As Long

Loading the custom requester and initializing the Requester API

Private Sub Form_Load() Dim groupName As String Dim parmName As String

' Read in the parameter values file specified at the command line. fileName = Command

' Initialize the API AcReqInitialize

' Open the parameter values file to access the parameter definitionsfileNum = AcReqReadFile( fileName )

' Specify the parameter whose value to get valueField.Text = AcReqGetValueString(fileNum, "orders_orderID")End Sub

Object name: valueField

Object name: btnClose

Object name: form

368 P r o g r a m m i n g e . R e p o r t s

Setting the parameter value the user entered

Private Sub btnClose_Click(Index As Integer)' When the user clicks the Close button, set the value to the parameter

AcReqSetValueString fileNum, "orders_orderID", valueField.Text hey = AcReqGetErrorStr(fileNum) Unload Me EndEnd Sub

Closing the Requester API

Private Sub Form_Unload(Cancel As Integer) AcReqWriteFile fileNum, fileName AcReqCloseFile fileNum AcReqUnInitializeEnd Sub

Using the Requester in a C++ applicationThis section explains how to work with BSTRs and dates in the C++ environment. A BSTR is also known as a Basic string or binary string. It is the C++ representation of a Visual Basic string. It points to a narrow character buffer in non-Unicode applications and a wide character buffer in Unicode applications. This section includes an example that shows how to specify report parameters, generate a report, and display the results in a C++ application.

Working with a BSTR in the Windows environmentUnlike C++ strings that are freed by their creator, BSTRs (OLE strings) are freed by their requester. Failure to free a BSTR causes memory leaks. The following example shows how to use SysFreeString to free a BSTR:

// NT platform. BSTR Alias; fileNumber = AcReqReadFile( szDetailRox ); Alias = AcReqGetAlias( fileNumber, "RoiFileName" ); SysFreeString(Alias); // UNIX -> 'delete Alias;' AcReqCloseFile (fileNumber);

The following example shows how dates are set from C++ as doubles using C++ Runtime library classes:

C h a p t e r 2 1 , R e q u e s t e r A P I u s e r g u i d e 369

int fileNumber; double inDate, outDate; COleDateTime oleDate( 1967, 12, 6, 0, 0, 0 ); // y m d h m s inDate = oleDate; fileNumber = AcReqReadFile( szSourceRox ); outDate = AcReqGetDefaultValueDate(fileNumber, "aDate"); oleDate = outDate;AcReqSetValueDate( fileNumber, "aDate", inDate ); AcReqCloseFile( fileNumber );

Working with BSTRs in C++ This example shows how to generate a report, print a report, get and set parameter values, and get parameter names from a Visual C++ form.

The following illustration shows the sample Visual C++ form and identifies the procedure with each button. The code for each procedure follows the illustration.

This example demonstrates using the following Requester methods.

OnGenerate( )

OnPrint( )

OnView( )

OnTypes( )

When a user clicks one of these buttons, the procedure executes:

Task Key classes & functions

Submit a request after setting three parameters.

AcReqSetValueStringAcReqGenerateReportAcReqSetEUDTPath

Print a report locally. AcReqSetPrinterNameAcReqPrintReport

370 P r o g r a m m i n g e . R e p o r t s

Declaring a variable

This section defines the reports the example uses. Edit these definitions to suit your environment:

#include <reqbasic.h>static char *szMyDetailRoi ="C:/Program Files/Actuate7/ErdPro/Examples/Detail/Mydetail.roi";// pointer to example .roi file (contains report instance)static char *szDetailRox = "C:/Program Files/Actuate7/ErdPro/Examples/Detail/Detail.rox";// pointer to example .rox file (contains report executable file)static char *szEUDT = "C:/Program Files/Actuate7/ErdPro/Bin/Runview.exe";// pointer to End User Desktopstatic char *szRoxFile = "RoxFileName";// .rox file to be used to generate the report (required by .rov)static char *szRoiFile ="RoiFileName";// .roi file to be generated (output parameter)

Setting parameters and generating a report

This code segment shows how to set the two required parameters and one optional report parameter and submit the report for local execution:

void CActReqDlg::OnGenerate() {

int fileNumber;// Open the report executable file and read its parameter definitions// Check the error flag to ensure the operation was successfulfileNumber = AcReqReadFile( szDetailRox );if ( AcReqGetError(fileNumber) )

AfxMessageBox ( (char*)AcReqGetErrorStr(fileNumber) );// Set the output .roi name to myDetail.roiAcReqSetValueString( fileNumber, szRoiFile, szMyDetailRoi ); // Set the parameter specifying the .rox file for report generation to// detail.roxAcReqSetValueString( fileNumber, szRoxFile, szDetailRox );// Set the customers_creditrank input parameter to CAcReqSetValueString( fileNumber, "customers_creditrank", "C" );// Set a pointer to the End User DesktopAcReqSetEUDTPath ( szEUDT );// Generate the report Mydetail.roi using the parameters just created and// display it using the End User Desktop (print option here is set to False)// Check for errors.// Set the options to generate the reportBOOL viewRpt = TRUE; // Views reportBOOL print = FALSE; // Prints ReportBOOL stayopen = TRUE; // Keep the EUDT open

C h a p t e r 2 1 , R e q u e s t e r A P I u s e r g u i d e 371

BOOL async = FALSE; // Runs asynchronouslyBOOL always = TRUE; // Launches EUDTBOOL hide = FALSE; // Hide EUDTlong opts = AC_REQ_GENERATE|

(viewRpt? AC_REQ_VIEW : 0 )|(print? AC_REQ_PRINT : 0 )|(stayopen? AC_REQ_STAY_OPEN : 0 )|(async? AC_REQ_ASYNC : 0 )|(always? AC_REQ_LAUNCH_ALWAYS : 0 )|(hide ? AC_REQ_HIDE : 0 );

// Generate the reportlong requestHandle = AcReqGenerateReport(szDetailRox, opts,

fileNumber);// Close the fileAcReqCloseFile( fileNumber );

}

Printing a report

This code segment shows how to print the report the previous example generated:

void CActReqDlg::OnPrint() {

int ret;// Set a pointer to the End User DesktopAcReqSetEUDTPath ( szEUDT );// Set a pointer to the default printerAcReqSetDefaultPrinter( );// Uncomment this line if you want to set the number of copies printed//AcReqSetPrinterNumberCopies( 1 );// Print the myDetail.roi (this code assumes the report has already been// generated)ret = AcReqPrintReport(szMyDetailRoi, AC_REQ_PRINT);

}

Viewing parameters for a report

This code facilitates viewing of parameters in a report:

void CActReqDlg::OnView() { // Byte sized BStrings are used rather than short strings to allow identical code to work with Visual Basic

BSTR CurrentParameter;BSTR CurrentGroup;BSTR Alias;

BOOL Required; BOOL Hidden;

372 P r o g r a m m i n g e . R e p o r t s

BOOL HideText; BOOL Adhoc; BSTR ParmType;

int fileNumber; // Open the parameter definition file from the report executable file

fileNumber = AcReqReadFile( szDetailRox );// Get the first parameter group defined for that reportCurrentGroup = AcReqGetFirstGroup(fileNumber);while (*(((char*)CurrentGroup)+1)){

// Get the first parameter the parameter group containsCurrentParameter = AcReqGetFirstParameter(fileNumber, (char*)

CurrentGroup); while (*(((char*)CurrentParameter)+1)) {

// Find the alias the devleoper set for that parameterAlias = ReqGetAlias(fileNumber, (char*) CurrentParameter);

// Find if the parameter is requiredRequired = AcReqGetRequired(fileNumber, (char*) CurrentParameter);

// Find if the parameter is marked as hiddenHidden = AcReqGetHidden(fileNumber, (char*) CurrentParameter);

// Find if the parameter has been marked with HideTextHideText = AcReqGetHideText(fileNumber, (char*) CurrentParameter);

// Find if the parameter is ad hocAdhoc = AcReqGetAdhoc(fileNumber, (char*) CurrentParameter);

// Get the parameter typeParmType = AcReqGetParmType(fileNumber, (char*) CurrentParameter);

// Free the BSTRsSysFreeString(Alias);SysFreeString(ParmType);SysFreeString(CurrentParameter);// Get the next parameter in the group.CurrentParameter = AcReqGetNextParameter(fileNumber, (char*)

CurrentGroup);

}// Free the BSTRsSysFreeString(CurrentGroup);// Get the next parameter group for the reportCurrentGroup = AcReqGetNextGroup(fileNumber);

} // Close the file

AcReqCloseFile (fileNumber);}

C h a p t e r 2 1 , R e q u e s t e r A P I u s e r g u i d e 373

Getting and setting report parameters

This code demonstrates how to get and set report parameters:

void CActReqDlg::OnTypes() { int fileNumber; double inDouble, outDouble; int inInteger, outInteger;

BSTR outString; double inDate, outDate; CURRENCY inCurrency, outCurrency;

COleDateTime oleDate( 67, 12, 6, 0, 0, 0 );COleCurrency oleCurrency( 123324, 567 );

char inString[]="Hello In"; inDouble = 0.0345; inInteger = 321; inDate = oleDate; inCurrency = oleCurrency;

// Open the parameter definition file from the report executable file// Check for errors

fileNumber = AcReqReadFile( szSourceRox ); if ( AcReqGetError( fileNumber ) ) AfxMessageBox( (char*)AcReqGetErrorStr( fileNumber ) );

// .rox file contained above contains parameters named aCurrency, // aDate, aDouble, aInteger and aString of type currency, date, double,

// integer, and string respectively// Find the default values set by the developer for the currency parameter// named aCurrency

outCurrency.int64 = AcReqGetDefaultValueCurrency(fileNumber, "aCurrency");

// Find the default values set by the developer for the date parameter named aDate outDate =AcReqGetDefaultValueDate(fileNumber, "aDate");

// Find the default values the developer set for the double parameter// named aDouble

outDouble = AcReqGetDefaultValueDouble(fileNumber, "aDouble");// Find the default values the developerset for the integer parameter// named aInteger

outInteger = AcReqGetDefaultValueInteger(fileNumber, "aInteger");// Find the default values the developer set for the string parameter// named aString

outString = AcReqGetDefaultValueString(fileNumber, "aString");// outCurrency is currently of type int64. Set it to type Currency

oleCurrency = outCurrency;// outDate is currently of type Double. Set it to type date

374 P r o g r a m m i n g e . R e p o r t s

oleDate = outDate;

// Set the currency parameter to the value of the inCurrency VariableAcReqSetValueCurrency( fileNumber, "aCurrency", inCurrency.int64 );

// Set the date parameter to the value of the inDate variableAcReqSetValueDate( fileNumber, "aDate", inDate );

// Set the double parameter to the value of the inDouble variableAcReqSetValueDouble( fileNumber, "aDouble", inDouble );

// Set the integer parameter to the value of the inInteger variableAcReqSetValueInteger( fileNumber, "aInteger", inInteger );

// Set the string parameter to the value of the inString variableAcReqSetValueString( fileNumber, "aString", inString );

// Write out the new parameter value file

AcReqWriteFile( fileNumber, szMyTypesRov );// Close the file

AcReqCloseFile( fileNumber );

// Open the parameter file you created and check for errorsfileNumber = AcReqReadFile( szMyTypesRov );

if (AcReqGetError(fileNumber)) AfxMessageBox( (char*) AcReqGetErrorStr(fileNumber) ); // Find all the parameter values. These should match the ones set above

outCurrency.int64 = AcReqGetValueCurrency(fileNumber, "aCurrency"); outDate = AcReqGetValueDate(fileNumber, "aDate"); outDouble = AcReqGetValueDouble(fileNumber, "aDouble"); outInteger = AcReqGetValueInteger(fileNumber, "aInteger"); outString = AcReqGetValueString(fileNumber, "aString");

// convert the outCurrency value to Currency and the outDate value to DateoleCurrency = outCurrency;oleDate = outDate;

// Close the fileAcReqCloseFile( fileNumber );

}

C h a p t e r 2 2 , R e q u e s t e r A P I r e f e r e n c e 375

C h a p t e r

Chapter 22Requester API referenceThis reference alphabetically lists the functions in the Requester API. For a conceptual discussion of the Requester API, see Chapter 21, “Requester API user guide.”

376 P r o g r a m m i n g e . R e p o r t s

A c R e q C l o s e F i l e

AcReqCloseFileCloses an open parameter values (.rov) or a report executable (.rox) file.

Syntax Basic: Sub AcReqCloseFile( fileNumber As Long )

C/C++: void AcReqCloseFile( long fileNumber )

Parameter fileNumberThe file number of the .rov or .rox file you opened with AcReqReadFile.

Description Use AcReqCloseFile to close an open .rov or .rox file when it is not needed. For example, you can close this file and free up memory after you finish setting and writing parameter values to a new .rov file.

See also AcReqReadFile

AcReqConnectConnects to the specified server.

Syntax Basic: Function AcReqConnect( server As String, username As String, password As String ) As Long

C/C++: long AcReqConnect( LPCSTR server, LPCSTR username, LPCSTR password )

Parameter serverThe name of the iServer to which to connect.

usernameThe user name to use to log in to iServer.

passwordThe user password to use to log in to iServer.

Description To access files and generate reports on iServer, you must call AcReqConnect to connect to iServer. Once your program establishes a connection to iServer, you can call any of the Requester API functions to access .rov, .rox, or .roi files on iServer.

When your program has finished executing tasks on iServer, call AcReqDisconnect to disconnect from iServer.

Returns A number indicating the connection handle.

-1 if the connection failed.

C h a p t e r 2 2 , R e q u e s t e r A P I r e f e r e n c e 377

A c R e q D i s c o n n e c t

See also AcReqDisconnect

AcReqDisconnectDisconnects from the specified server.

Syntax Basic: Sub AcReqDisconnect( connectionHandle As Long )

C/C++: VBBOOL AcReqDisconnect( long connectionHandle )

Parameter connectionHandleThe handle to the connection to close. This value is returned by AcReqConnect when a connection to iServer is established.

Description When your program has finished executing tasks on iServer, call AcReqDisconnect to disconnect from iServer. Call AcReqDisconnect before AcReqUninitialize, which clears the Requester API from memory.

See also AcReqConnect

AcReqGenerateReportGenerates a report (.roi) from a report executable (.rox) or a parameter values (.rov) file.

Syntax Basic: Function AcReqGenerateReport( filename As String, options As Long, fileNumber As Long ) As Long

C/C++: long AcReqGenerateReport( LPCSTR filename, long options, long fileNumber)

Parameter filenameThe name of the .rox or .rov file to use to generate the report. Specify the full path name if the file is not in the current directory.

If the file resides on a server, use the following format:

rotp:[//<server>]/<path>/<filename>[;<version>]

378 P r o g r a m m i n g e . R e p o r t s

A c R e q G e n e r a t e R e p o r t

optionsA set of constants you can use to specify how the End User Desktop application runs. When specifying multiple options, logically add them using the plus (+) character. The following table lists and describes the constants.

Option Description

AC_REQ_LAUNCH_ALWAYS Runs a new instance of an End User Desktop application to generate the report. AC_REQ_LAUNCH_ALWAYS and AC_REQ_LOCAL are mutually exclusive.

AC_REQ_LOCAL Generates the report in the current instance of e.Report Designer, e.Report Designer Professional, or End User Desktop. AC_REQ_LAUNCH_ALWAYS and AC_REQ_LOCAL are mutually exclusive.

AC_REQ_GENERATE Generates the report.

AC_REQ_VIEW Displays the generated report.

AC_REQ_PRINT Prints the generated report.

AC_REQ_ASYNC Runs this process asynchronously. The function returns immediately and the report generates in the background.

AC_REQ_HIDE Does not display the End User Desktop application while it generates the report.

AC_REQ_RETURN_HANDLE Returns a handle to the synchronous report generation request.

AC_REQ_STAY_OPEN Keeps the End User Desktop application open after it generates the report. This option is ignored if the report is generated in the current instance of the End User Desktop.

AC_REQ_SHOW_PROG_WND Displays the progress window of the End User Desktop, e.Report Designer, or e.Report Designer Professional while a report generates.

AC_REQ_REPLACE Overwrites the latest report. When this option is omitted, the report is created with a new version number.

AC_REQ_USE_HANDLE Reserved.

C h a p t e r 2 2 , R e q u e s t e r A P I r e f e r e n c e 379

A c R e q G e n e r a t e R e p o r t

Scope of optionsThe following table shows which options apply to reports generated locally or on iServer and launched from either local or server applications.

If you do not specify any generation options, Actuate does the following by default:

■ Generates the report with the current instance of the End User Desktop application. If an End User Desktop application is not running, Actuate attempts to launch a new instance, but only if you specified the location with the AcReqSetEUDTPath function.

■ Runs the process synchronously. The function returns after the report is generated.

■ Displays the End User Desktop application as it generates the report only if the report is local.

fileNumberIf generating a report from an .rov file, enter 0. If generating a report from an .rox file, enter the file number AcReqReadFile returned.

The following examples show how to specify arguments for AcReqGenerateReport:

AcReqGenerateReport( "Detail.rov", AC_REQ_VIEW, 0 )AcReqGenerateReport( "Detail.rov", AC_REQ_PRINT+AC_REQ_HIDE, 0)AcReqGenerateReport( "Detail.rox", AC_REQ_LOCAL, fileNum )

OptionsLocal reportLocal launch

Server reportLocal launch

Server reportServer launch

AC_REQ_LAUNCH_ALWAYS Yes Yes, if report viewing needed

No

AC_REQ_LOCAL Yes, if using Actuate Basic

No No

AC_REQ_VIEW Yes Yes No

AC_REQ_PRINT Yes Yes Yes

AC_REQ_ASYNC Yes Yes Yes

AC_REQ_HIDE Yes, if report viewing not needed

Yes, if report viewing not needed

No

AC_REQ_RETURN_HANDLE Yes Yes Yes

AC_REQ_STAY_OPEN Yes Yes, if report viewing needed

No

AC_REQ_REPLACE No Yes Yes

380 P r o g r a m m i n g e . R e p o r t s

A c R e q G e n e r a t e R e p o r t

The first call passes the name of a parameter file, the constant representing the message to display the generated report, and zero to generate a report from the parameter file. The second call is the same as the first except it passes two constants that represent a message to generate and print the generated report without displaying the End User Desktop. The third call passes an executable file, a constant that represents a message to generate the report in the current instance of e.Report Designer, e.Report Designer Professional or End User Desktop, and the file number AcReqReadFile returned.

The following call generates the report on iServer with a stored file:

rsMyRov = "rotp://" + RotpHost + RotpFolder + "/" + "mydetail" + ".rov"requestHandle = AcReqGenerateReport(rsMyRov, AC_REQ_GENERATE, 0)

The following call passes an executable file, a constant that represents a message to return a handle to the report generation request, and the file number AcReqReadFile returned. Requests must be run synchronously:

requestHandle = AcReqGenerateReport("rotp://Rs/Test/Forecast.rox", AC_REQ_RETURN_ HANDLE, fileNum)

Description Use AcReqGenerateReport to generate a report based on parameter values specified in an .rov or .rox file. Use this function to incorporate report generation in your application. This capability is useful for batch report creation.

To generate a report from an .rov file, Actuate runs the .rox file associated with the .rov file you specify. It looks for the .rox file in the same directory where the .rov file resides. If the .rox file is not in the same directory as the .rov file, Actuate displays “Can’t access <file name>.rox” and displays an open file dialog which you can use to find the .rox file.

To run a report in batch mode, specify the .rox file programmatically. To do so, set the .rox file name parameter, represented by the constant, AC_REQ_ROX, to the name of the .rox to use before writing the parameter values to a new .rov file. The .rox file name is a hidden parameter that can only be set programmatically, it does not appear in the Requester dialog. To set the .rox file name parameter, use AcReqSetValueString as the following example shows:

AcReqSetValueString( fileNum, AC_REQ_ROX, "C:\Test\Myreport.rox" )

If the .rox you want to run is in the same directory as the .rov file, you do not have to set the .rox file name parameter.

By default, the .roi file that AcReqGenerateReport creates has the same root name as the .rox file used to create the report, but you can change the .roi file name with AcReqSetValueString. For more information, see “AcReqSetValueString,” later in this chapter.

C h a p t e r 2 2 , R e q u e s t e r A P I r e f e r e n c e 381

A c R e q G e n e r a t e R e p o r t

Returns Use the AcReqGetError function to check for errors for reports generated asynchronously. For reports generated synchronously, the return value from AcReqGenerateReport indicates the result of the report execution and any error codes as the following table shows.

See also AcReqGetErrorAcReqGetErrorStringAcReqGetReportVersionAcReqSetEUDTPathAcReqSetRequestPriorityAcWReqGetErrorString

Return valueReport generation mode Indication

0 Report generated asynchronously

Report executed successfully on a local client.

1 to 1023 Report generated asynchronously

Report execution failed.The return value indicates the error code. This method returns the same error codes as AcReqGetError. For more information, see “AcReqGetError.”

1024 or greater Report generated asynchronously

Report executed successfully on iServer. The return value is a request handle that can be used to get more information about the report, such as the report version number.

0 or less than 0 Report generated synchronously

Report executed successfully on iServer.

greater than 0 Report generated synchronously

Report execution failed. To get an error number, call AcReqGetError using the return value as an input parameter. To get the error description, call AcReqGetErrorString or AcWReqGetErrorString using the return value as an input parameter.

382 P r o g r a m m i n g e . R e p o r t s

A c R e q G e t A d h o c

AcReqGetAdhocReturns True or False, depending on whether the parameter is an ad hoc parameter or not.

Syntax Basic: Function AcReqGetAdhoc( fileNumber As Long, parmName As String ) As Boolean

C/C++: VBBOOL AcReqGetAdhoc( long fileNumber, LPCSTR ParmName )

Parameter fileNumberThe file number of the .rov or .rox file you opened with AcReqReadFile.

parmNameThe name of the parameter whose ad hoc attribute you want. If you do not know the names of the parameters, use AcReqGetFirstParameter and AcReqGetNextParameter to get the parameter names.

Description Use AcReqGetAdhoc to find out if a parameter was designed as an ad hoc parameter. An ad hoc parameter accepts a conditional expression that extends the Where clause of a query when the report is generated.

Returns True if the parameter is an ad hoc parameter, False otherwise.

See also AcReqGetFirstParameterAcReqGetNextParameterAcReqSetScopedParameterName

AcReqGetAliasReturns the alternate name of the specified parameter.

Syntax Basic: Function AcReqGetAlias( fileNumber As Long, parmName As String ) As String

C/C++: BSTR AcReqGetAlias( long fileNumber, LPCSTR parmName )

Parameter fileNumberThe file number of the .rov or .rox file you opened with AcReqReadFile.

parmNameThe name of the parameter whose alias you want. If you do not know the names of the parameters, use AcReqGetFirstParameter and AcReqGetNextParameter to get the parameter names.

C h a p t e r 2 2 , R e q u e s t e r A P I r e f e r e n c e 383

A c R e q G e t D e f a u l t V a l u e C u r r e n c y

Description Use AcReqGetAlias to get the alias of a parameter. When defining parameters, you use aliases to create descriptive prompts that appear in the Requester dialog. For example, Customer Name is more descriptive than Cust_Name.

If you are building a custom requestor interface in a Visual Basic form, for example, you can use the alias that AcReqGetAlias returns to create an interface similar to the Requester dialog in e.Report Designer or e.Report Designer Professional.

Returns The alias of the specified parameter.

An empty string if there is no alias or if an error occurred.

See also AcReqGetFirstParameterAcReqGetNextParameterAcReqSetScopedParameterName

AcReqGetDefaultValueCurrencyReturns the default value of the specified parameter as a currency.

Syntax Basic: Function AcReqGetDefaultValueCurrency( fileNumber As Long, parmName As String ) As Currency

C/C++: REQCYTYPE AcReqGetDefaultValueCurrency( long fileNumber, LPCSTR parmName )

Parameter fileNumberThe file number of the .rov or .rox file you opened with AcReqReadFile.

parmNameThe name of the parameter whose default value you want. If you do not know the names of the parameters, use AcReqGetFirstParameter and AcReqGetNextParameter to get the parameter names.

Description Use AcReqGetDefaultValueCurrency to get the default value of a parameter as a currency. The programmer defines the default value at design time. This value is used if the user does not supply a value when the report runs. Required parameters always have default values. A default value is constant and independent of the value a user sets through the Requester.

When calling AcReqGetDefaultValueCurrency, the parameter you specify as an argument must be of type Currency. If you specify a parameter of any other type, AcReqGetDefaultValueCurrency returns the default value for that type. To pass an argument of any type, use AcReqGetDefaultValueStr. The value AcReqGetDefaultValueStr always returns a string.

Use AcReqGetParmType to check the data type of a parameter.

384 P r o g r a m m i n g e . R e p o r t s

A c R e q G e t D e f a u l t V a l u e D a t e

In C/C++, the structure REQCYTYPE stores up to 64 bits. If you need to retrieve default currency values that require a 96-bit structure, use AcReqGetDefaultValueString to return the value. Convert the string value to a currency value within your application program. When you call AcReqGetDefaultValueCurrency to return a default currency value larger than 64 bits, the GetError function returns an error number.

Returns The default value of the specified parameter as a currency.

See also AcReqGetDefaultValueStrAcReqGetFirstParameterAcReqGetNextParameterAcReqGetParmTypeAcReqSetScopedParameterName

AcReqGetDefaultValueDateReturns the default value of the specified parameter as a date.

Syntax Basic: Function AcReqGetDefaultValueDate( fileNumber As Long, parmName As String ) As Date

C/C++: double AcReqGetDefaultValueDate( long fileNumber, LPCSTR parmName )

Parameter fileNumberThe file number of the .rov or .rox file you opened with AcReqReadFile.

parmNameThe name of the parameter whose default value you want. If you do not know the names of the parameters, use AcReqGetFirstParameter and AcReqGetNextParameter to get the parameter names.

Description Use AcReqGetDefaultValueDate to get the default value of a parameter as a date. The programmer defines the default value at design time. This value is used if the user does not supply a value when the report runs. Required parameters always have default values. A default value is constant and independent of the value a user sets through the Requester.

When calling AcReqGetDefaultValueDate, the parameter you specify as an argument must be of type Date. If you specify a parameter of any other type, AcReqGetDefaultValueDate returns the default value for that type. To pass an argument of any type, use AcReqGetDefaultValueStr. The value AcReqGetDefaultValueStr returns is always a string.

Use AcReqGetParmType to check the data type of a parameter.

C h a p t e r 2 2 , R e q u e s t e r A P I r e f e r e n c e 385

A c R e q G e t D e f a u l t V a l u e D o u b l e

Returns The default value of the specified parameter as a date.

The following example shows how to work with dates expressed as C++ doubles:

int fileNumber; double inDate, outDate; COleDateTime oleDate( 1967, 12, 6, 0, 0, 0 ); // y m d h m s inDate = oleDate; fileNumber = AcReqReadFile( szSourceRox ); outDate = AcReqGetDefaultValueDate(fileNumber, "aDate"); oleDate = outDate; AcReqSetValueDate( fileNumber, "aDate", inDate ); AcReqCloseFile( fileNumber );

See also AcReqGetDefaultValueStrAcReqGetFirstParameterAcReqGetNextParameterAcReqGetParmTypeAcReqSetScopedParameterName

AcReqGetDefaultValueDoubleReturns the default value of the specified parameter as a double.

Syntax Basic: Function AcReqGetDefaultValueDouble( fileNumber As Long, parmName As String ) As Double

C/C++: double AcReqGetDefaultValueDouble( long fileNumber, LPCSTR parmName )

Parameter fileNumberThe file number of the .rov or .rox file you opened with AcReqReadFile.

parmNameThe name of the parameter whose default value you want. If you do not know the names of the parameters, use AcReqGetFirstParameter and AcReqGetNextParameter to get the parameter names.

Description Use AcReqGetDefaultValueDouble to get the default value of a parameter as a double. The programmer defines the default value at design time. This value is used if the user does not supply a value when the report runs. Required parameters always have default values. A default value is constant and independent of the value a user sets through the Requester.

When calling AcReqGetDefaultValueDouble, the parameter you specify as an argument must be of type Double. If you specify a parameter of any other

386 P r o g r a m m i n g e . R e p o r t s

A c R e q G e t D e f a u l t V a l u e I n t e g e r

type, AcReqGetDefaultValueDouble returns the default value for that type. To pass an argument of any type, use AcReqGetDefaultValueStr. The value AcReqGetDefaultValueStr returns is always a string.

Use AcReqGetParmType to check the data type of a parameter.

Returns The default value of the specified parameter as a double.

See also AcReqGetDefaultValueStrAcReqGetFirstParameterAcReqGetNextParameterAcReqGetParmTypeAcReqSetScopedParameterName

AcReqGetDefaultValueIntegerReturns the default value of the specified parameter as an integer.

Syntax Basic: Function AcReqGetDefaultValueInteger( fileNumber As Long, parmName As String ) As Integer

C/C++: long AcReqGetDefaultValueInteger( long fileNumber, LPCSTR parmName )

Parameter fileNumberThe file number of the .rov or .rox file you opened with AcReqReadFile.

parmNameThe name of the parameter whose default value you want. If you do not know the names of the parameters, use AcReqGetFirstParameter and AcReqGetNextParameter to get the parameter names.

Description Use AcReqGetDefaultValueInteger to get the default value of a parameter as an integer. The programmer defines the default value at design time. This value is used if the user does not supply a value when the report runs. Required parameters always have default values. A default value is constant and independent of the value a user sets through the Requester.

When calling AcReqGetDefaultValueInteger, the parameter you specify as an argument must be of type Integer. If you specify a parameter of any other type, AcReqGetDefaultValueInteger returns the default value for that type. To pass an argument of any type, use AcReqGetDefaultValueStr. The value AcReqGetDefaultValueStr returns is always a string.

Use AcReqGetParmType to check the data type of a parameter.

Returns The default value of the specified parameter as an integer.

C h a p t e r 2 2 , R e q u e s t e r A P I r e f e r e n c e 387

A c R e q G e t D e f a u l t V a l u e S t r

See also AcReqGetDefaultValueStrAcReqGetFirstParameterAcReqGetNextParameterAcReqGetParmTypeAcReqSetScopedParameterName

AcReqGetDefaultValueStrReturns the default value of the specified parameter as a string.

Syntax Basic: Function AcReqGetDefaultValueStr( fileNumber As Long, parmName As String ) As String

C/C++: BSTR AcReqGetDefaultValueStr( long fileNumber, LPCSTR parmName )

Parameter fileNumberThe file number of the .rov or .rox file you opened with AcReqReadFile.

parmNameThe name of the parameter whose default value you want. If you do not know the names of the parameters, use AcReqGetFirstParameter and AcReqGetNextParameter to get the parameter names.

Description Use AcReqGetDefaultValueStr to get the default value of any parameter as a string. The parameter you specify as an argument can be of any type. To get the default value as the type with which the parameter was declared, use type-specific functions such as AcReqGetDefaultValueInteger or AcReqGetDefaultValueCurrency.

The programmer defines the default value at design time. This value is used if the user does not supply a value when the report runs. Required parameters always have default values. A default value is constant and independent of the value a user sets through the Requester.

Returns The default value of the specified parameter as a string.

See also AcReqGetDefaultValueCurrencyAcReqGetDefaultValueDateAcReqGetDefaultValueDoubleAcReqGetDefaultValueIntegerAcReqGetDefaultValueStringAcReqGetFirstParameterAcReqGetNextParameterAcReqGetParmType

388 P r o g r a m m i n g e . R e p o r t s

A c R e q G e t D e f a u l t V a l u e S t r i n g

AcReqGetDefaultValueStringReturns the default value of the specified parameter as a string.

Syntax Basic: Function AcReqGetDefaultValueString( fileNumber As Long, parmName As String ) As String

C/C++: BSTR AcReqGetDefaultValueString( long fileNumber, LPCSTR parmName )

Parameter fileNumberThe file number of the .rov or .rox file you opened with AcReqReadFile.

parmNameThe name of the parameter whose default value you want. If you do not know the names of the parameters, use AcReqGetFirstParameter and AcReqGetNextParameter to get the parameter names.

Description Use AcReqGetDefaultValueString to get the default value of a parameter as a string. The programmer defines the default value at design time. This value is used if the user does not supply a value when the report runs. Required parameters always have default values. A default value is constant and independent of the value a user sets through the Requester.

When calling AcReqGetDefaultValueString, the parameter you specify as an argument must be of type String. If you specify a parameter of any other type, AcReqGetDefaultValueString returns the default value for that type. To pass an argument of any type, use AcReqGetDefaultValueStr. The value AcReqGetDefaultValueStr returns is always a string.

Use AcReqGetParmType to check the data type of a parameter.

Returns The default value of the specified parameter as a string.

See also AcReqGetDefaultValueStrAcReqGetFirstParameterAcReqGetNextParameterAcReqGetParmTypeAcReqSetScopedParameterName

C h a p t e r 2 2 , R e q u e s t e r A P I r e f e r e n c e 389

A c R e q G e t E r r o r

AcReqGetErrorReturns the error number of the last error that occurred during an API function call.

Syntax To check errors for an AcReqGenerateReport function call, use:

Basic: Function AcReqGetError( returnValue As Long ) As Long

C/C++: long AcReqGetError( long returnValue )

To check errors for other API function calls, use:

Basic: Function AcReqGetError( fileNumber As Long ) As Long

C/C++: long AcReqGetError( long fileNumber )

Parameter returnValueThe return value from the AcReqGenerateReport function call.

fileNumberThe file number of an .rov or .rox file you opened with AcReqReadFile.

Description Use AcReqGetError to check for error conditions and return the error number. The following table lists the error numbers that AcReqGetError returns. To get the error string, use AcReqGetErrorString.

Error number Error string

00 No error.

01 Could not find file number.

02 File not an .rox or .rov file.

03 Could not save .rov file.

04 Could not close file.

05 Error while generating report.

06 There are no groups in the file.

07 There are no more groups in the file.

08 There is no group by given name.

09 There are no parameters in group specified by given name.

10 There are no more parameters in group specified by given name.

11 There is no parameter by specified name.

12 Type of parameter not found. Using default of string.

390 P r o g r a m m i n g e . R e p o r t s

A c R e q G e t E r r o r

13 Could not set printer name.

14 Could not set printer property.

15 Could not open .rox file.

16 Could not open .rov file.

17 Not connected with iServer.

18 Could not find object on iServer.

19 Could not connect to iServer.

20 Invalid connection handle.

21 Invalid request handle.

22 Invalid file read from iServer.

23 Could not find .rov file on iServer.

24 Could not find .roi file on iServer.

25 Could not generate request on iServer.

26 Cannot run report locally, not in Actuate Environment.

27 Operation not supported in 16 bit.

28 Illegal combination of options.

29 File must be of type .roi.

30 Could not print report.

31 Could not find related .rox.

32 Error interfacing with an existing Actuate Viewer.

33 iServer does not support the operation.

34 Unable to set .rov dependency.

35 Error retrieving object properties.

36 Error while reading object from iServer.

37 Could not find related .rox object.

38 Could not find .rox file on iServer.

39 Error getting object ID.

40 Unable to submit print request.

42 Error creating temporary .rov file.

43 Unable to launch Viewer.

45 Error converting the currency value from the stored 96-bit format to the 64-bit format.

Error number Error string

C h a p t e r 2 2 , R e q u e s t e r A P I r e f e r e n c e 391

A c R e q G e t E r r o r S t r i n g

Returns The error number of the last error.

Example The following example shows you how to handle errors from AcReqGenerateReport.

long ret = AcReqGenerateReport ( )if (ret > 0 And < 1024)

long error = AcReqGetError (ret)

See also AcReqGetErrorString

AcReqGetErrorStringReturns a string that describes the last error that occurred during an API function call.

Syntax Basic: Function AcReqGetErrorString( fileNumber As Long ) As String

C/C++: BSTR AcReqGetErrorString( long fileNumber )

Parameter fileNumberThe file number of an .rov or .rox file you opened with AcReqReadFile.

Description Use AcReqGetErrorString to check for error conditions and retrieve a description of the error. To get the error number, use AcReqGetError. For a list of the error strings that AcReqGetErrorString can return, see AcReqGetError.

Returns The error string of the last error.

See also AcReqGetError

AcReqGetFirstGroupReturns the name of the first parameter group in the specified parameter value (.rov) file or parameter definition section of the specified .rox file.

Syntax Basic: Function AcReqGetFirstGroup( fileNumber As Long ) As String

C/C++: BSTR AcReqGetFirstGroup( long fileNumber )

Parameter fileNumberThe file number of the .rov or .rox file you opened with AcReqReadFile.

Description Use AcReqGetFirstGroup in conjunction with AcReqGetNextGroup, AcReqGetFirstParameter, and AcReqGetNextParameter to get information

392 P r o g r a m m i n g e . R e p o r t s

A c R e q G e t F i r s t P a r a m e t e r

about the organization of parameters in a specified .rov or .rox file. If you are building a custom requestor interface in a Visual Basic form, for example, you can use the strings that these functions return to create a structure similar to the Requester interface in e.Report Designer or e.Report Designer Professional.

You can organize parameters into groups for ease of use. For example, CustomerName, CustomerPhone, and Credit_Rank might be parameters in a Customer parameters group, and City and State might be parameters in an Office parameters group.

If there are no parameter groups, the parameters have an empty string (“ “) as their group name.

Returns The name of the first parameter group in the specified .rov or .rox file, if a group exists.

An empty string if there are no groups or if an error occurred.

See also AcReqGetFirstParameterAcReqGetNextGroupAcReqGetNextParameter

AcReqGetFirstParameterReturns the name of the first parameter in the specified parameter group.

Syntax Basic: Function AcReqGetFirstParameter( fileNumber As Long, parmGroup As String ) As String

C/C++: BSTR AcReqGetFirstParameter( long fileNumber, LPCSTR parmGroupName )

Parameter fileNumberThe file number of the .rov or .rox file you opened with AcReqReadFile.

parmGroupThe name of the parameter group in which to find the first parameter. If you do not know the name of parameter groups, use AcReqGetFirstGroup and AcReqGetNextGroup to get the group names. To get all parameters that belong in any group, specify an empty string for this argument.

Description Use AcReqGetFirstParameter in conjunction with AcReqGetNextParameter, AcReqGetFirstGroup, and AcReqGetNextGroup to get information about the organization of parameters in a specified .rov or .rox file. If you are building a custom requestor interface in a Visual Basic form, for example, you can use the strings that these functions return to create a structure similar to the Requester interface in e.Report Designer or e.Report Designer Professional.

C h a p t e r 2 2 , R e q u e s t e r A P I r e f e r e n c e 393

A c R e q G e t H i d d e n

Returns The name of the first parameter in the specified parameter group.

An empty string if there are no parameters or if an error occurred.

See also AcReqGetFirstGroupAcReqGetNextGroupAcReqGetNextParameter

AcReqGetHiddenReturns True or False, depending on whether or not the parameter is defined as hidden.

Syntax Basic: Function AcReqGetHidden( fileNumber As Long, parmName As String ) As Boolean

C/C++: VBBOOL AcReqGetHidden( long fileNumber, LPCSTR parmName )

Parameter fileNumberThe file number of the .rov or .rox file you opened with AcReqReadFile.

parmNameThe name of the parameter whose hidden attribute you want. If you do not know the names of the parameters, use AcReqGetFirstParameter and AcReqGetNextParameter to get the parameter names.

Description Use AcReqGetHidden to find out if a parameter is defined as hidden. If a parameter is hidden, you can only set the parameter value programmatically, users cannot set the value of through the Requester. For example, define a path name parameter as hidden to prevent users from changing this value.

Returns True if the parameter is defined as hidden, False otherwise.

See also AcReqGetFirstParameterAcReqGetNextParameterAcReqSetScopedParameterName

AcReqGetHideTextReturns True or False, depending on whether the parameter is defined to display asterisks or actual text as users type the value in the Requester.

Syntax Basic: Function AcReqGetHideText( fileNumber As Long, parmName As String ) As Boolean

C/C++: VBBOOL AcReqGetHideText( long fileNumber, LPCSTR parmName )

394 P r o g r a m m i n g e . R e p o r t s

A c R e q G e t N e x t G r o u p

Parameter fileNumberThe file number of the .rov or .rox file you opened with AcReqReadFile.

parmNameThe name of the parameter whose hide text attribute you want. If you do not know the names of the parameters, use AcReqGetFirstParameter and AcReqGetNextParameter to get the parameter names.

Description Use AcReqGetHideText to find out if a parameter is defined to display asterisks or actual text as users type the value in the Requester. If the hide text attribute is True, Actuate displays asterisks as users type the parameter value.

Returns True if the parameter was defined to display asterisks as users type the value.

False if the parameter was defined to display the text that users type.

See also AcReqGetFirstParameterAcReqGetNextParameterAcReqSetScopedParameterName

AcReqGetNextGroupReturns the name of the next parameter group in the specified .rov file or parameter definition section of the specified .rox file.

Syntax Basic: Function AcReqGetNextGroup( fileNumber As Long ) As String

C/C++: BSTR AcReqGetNextGroup( long fileNumber )

Parameter fileNumberThe file number of the .rov or .rox file you opened with AcReqReadFile.

Description Use AcReqGetNextGroup in conjunction with AcReqGetFirstGroup, AcReqGetFirstParameter, and AcReqGetNextParameter to get information about the organization of parameters in a specified .rov or .rox file. You must call AcReqGetFirstGroup before calling AcReqGetNextGroup. To get the names of all parameter groups, call AcReqGetNextGroup until it returns an empty string. An empty string indicates that the function has returned the last parameter group.

If you are building a custom requester interface in a Visual Basic form, for example, you can use the strings that these functions return to create a structure similar to the Requester interface in e.Report Designer or e.Report Designer Professional.

You can organize parameters into groups for ease of use. For example, CustomerName, CustomerPhone, and Credit_Rank might be parameters in a Customer parameters group, and City and State might be parameters in an Office parameters group.

C h a p t e r 2 2 , R e q u e s t e r A P I r e f e r e n c e 395

A c R e q G e t N e x t P a r a m e t e r

Returns The name of the next group in the specified .rov or .rox file, if one exists.

An empty string if there are no more groups or if an error occurred.

See also AcReqGetFirstGroupAcReqGetFirstParameterAcReqGetNextParameter

AcReqGetNextParameterReturns the name of the next parameter in the specified parameter group.

Syntax Basic: Function AcReqGetNextParameter( fileNumber As Long, parmGroup As String ) As String

C/C++: BSTR AcReqGetNextParameter( long fileNumber, LPCSTR parmGroup)

Parameter fileNumberThe file number of the .rov or .rox file you opened with AcReqReadFile.

parmGroupThe name of the parameter group in which to find the next parameter. If you do not know the name of parameter groups, use AcReqGetFirstGroup and AcReqGetNextGroup to get the group names. To get all parameters that belong in any group, specify an empty string for this argument.

Description Use AcReqGetNextParameter in conjunction with AcReqGetFirstParameter, AcReqGetFirstGroup, and AcReqGetNextGroup to get information about the organization of parameters in a specified .rov or .rox file. You must call AcReqGetFirstParameter before calling AcReqGetNextParameter. To get the names of all parameters in a group, call AcReqGetNextParameter until it returns an empty string. An empty string indicates that the function has returned the last parameter.

If you are building a custom requestor interface in a Visual Basic form, for example, you can use the strings that these functions return to create a structure similar to the Requester interface in e.Report Designer or e.Report Designer Professional.

Returns The name of the next parameter in the specified parameter group.

An empty string if there are no more parameters or if an error occurred.

See also AcReqGetFirstGroupAcReqGetFirstParameterAcReqGetNextGroup

396 P r o g r a m m i n g e . R e p o r t s

A c R e q G e t P a r m T y p e

AcReqGetParmTypeReturns the data type of the specified parameter as a string.

Syntax Basic: Function AcReqGetParmType( fileNumber As Long, parmName As String ) As String

C/C++: BSTR AcReqGetParmType( long fileNumber, LPCSTR parmName )

Parameter fileNumberThe file number of the .rov or .rox file you opened with AcReqReadFile.

parmNameThe name of the parameter whose data type you want. If you do not know the names of the parameters, use AcReqGetFirstParameter and AcReqGetNextParameter to get the parameter names.

Description Use AcReqGetParmType to find out the parameter’s data type. You can use this information to determine how to set a parameter value. You can also use this information to determine which function to use to get a parameter’s default value or its current value.

You set parameter values with functions such as AcReqSetValueDate, AcReqSetValueString, and so on. You get the default values for parameters with functions such as AcReqGetDefaultValueDate, AcReqGetDefaultValueString, and so on. You get a parameter’s current value with functions such as AcReqGetValueDate, AcReqGetValueString, and so on.

Returns The data type of the specified parameter as a string.

See also AcReqGetFirstParameterAcReqGetNextParameterAcReqGetTypeAcReqSetScopedParameterName

AcReqGetReportVersionReturns the version of the report AcReqGenerateReport generated.

Syntax Basic: Function AcReqGetReportVersion( requestHandle As Long ) As Long

C/C++: long AcReqGetReportVersion( long requestHandle )

Parameter requestHandleAcReqGenerateReport returns the request handle in its return value. This value is greater than or equal to 1024.

C h a p t e r 2 2 , R e q u e s t e r A P I r e f e r e n c e 397

A c R e q G e t R e q u i r e d

Description Use AcReqGetReportVersion to get the version of a report that AcReqGenerateReport generated. You can view the report using the full file name including the version number. For report generation requests that complete successfully, AcReqGenerateReport returns the request handle in the return value. If you generate the report asynchronously, you must wait until the report has been generated before you can get the report’s version number.

Returns The version number of the generated report.

Zero if an error occurred.

See also AcReqGenerateReport

AcReqGetRequiredReturns True or False, depending on whether or not the parameter is defined as required.

Syntax Basic: Function AcReqGetRequired( fileNumber As Long, parmName As String ) As Boolean

C/C++: VBBOOL AcReqGetRequired( long fileNumber, LPCSTR parmName )

Parameter fileNumberThe file number of the .rov or .rox file you opened with AcReqReadFile.

parmNameThe name of the parameter whose required attribute you want. If you do not know the names of the parameters, use AcReqGetFirstParameter and AcReqGetNextParameter to get the parameter names.

Description Use AcReqGetRequired to find out if a parameter was defined as required or optional. If a parameter is required, Actuate generates the report only if a value for the parameter is provided.

Use the boolean value that AcReqGetRequired returns to determine if you need to set a parameter value before generating a report. You set parameter values with functions such as AcReqSetValueString, AcReqSetValueDate, and so on.

Returns True if the parameter is required to generate the report, False if the parameter is optional.

See also AcReqGetFirstParameterAcReqGetNextParameterAcReqSetScopedParameterName

398 P r o g r a m m i n g e . R e p o r t s

A c R e q G e t T y p e

AcReqGetTypeReturns the data type of the specified parameter as an enumeration.

Syntax Basic: Function AcReqGetType( fileNumber As Long, parmName As String ) As Long

C/C++: long AcReqGetType( long fileNumber, LPCSTR parmName )

Parameter fileNumberThe file number of the .rov or .rox file you opened with AcReqReadFile.

parmNameThe name of the parameter whose data type you want. If you do not know the names of the parameters, use AcReqGetFirstParameter and AcReqGetNextParameter to get the parameter names.

Description Use AcReqGetType to find out the parameter’s data type. This method returns an enumeration of the data type rather than a text string. You can use the data type to determine how to set a parameter value. You can also use this information to determine which function to use to get a parameter’s default value or its current value.

You get the default values for parameters with AcReqGetDefaultValueDate, AcReqGetDefaultValueString, and so on. You set parameter values with AcReqSetValueDate, AcReqSetValueString, and so on. You get a parameter’s current value with AcReqGetValueDate, AcReqGetValueString, and so on.

Returns An enumeration of the data type as the following table shows.

See also AcReqGetFirstParameterAcReqGetNextParameterAcReqGetParmTypeAcReqSetScopedParameterName

Data type Enumeration

AC_REQ_UNKNOWN 0

AC_REQ_STRING 1

AC_REQ_INTEGER 2

AC_REQ_DOUBLE 3

AC_REQ_DATETIME 4

AC_REQ_CURRENCY 5

C h a p t e r 2 2 , R e q u e s t e r A P I r e f e r e n c e 399

A c R e q G e t V a l u e C u r r e n c y

AcReqGetValueCurrencyReturns the current value of the specified parameter as a currency.

Syntax Basic: Function AcReqGetValueCurrency( fileNumber As Long, parmName As String ) As Currency

C/C++: REQCYTYPE AcReqGetValueCurrency( long fileNumber, LPCSTR parmName )

Parameter fileNumberThe file number of the .rov or .rox file you opened with AcReqReadFile.

parmNameThe name of the parameter whose current value you want. If you do not know the names of the parameters, use AcReqGetFirstParameter and AcReqGetNextParameter to get the parameter names.

Description Use AcReqGetValueCurrency to get the current value of a parameter as a currency. The current value is the value last entered in the .rov file. If you are accessing an .rox file, the current value is the default value defined at design time.

When calling AcReqGetValueCurrency, the parameter you specify as an argument must be of type Currency. If you specify a parameter of any other type, AcReqGetValueCurrency returns the default value for that type. To pass an argument of any type, use AcReqGetValueStr. AcReqGetValueStr always returns a string.

Use AcReqGetParmType to check the data type of a parameter.

In C/C++, the structure REQCYTYPE, stores up to 64 bits. If you need to retrieve currency values that require a 96-bit structure, use the AcReqGetValueString function to return the value. Then, convert the string value to a currency value within your application program. If you call AcReqGetValueCurrency to return a currency value larger than 64 bits, the GetError function returns an error message number.

Returns The current value of the specified parameter as a currency.

See also AcReqGetFirstParameterAcReqGetNextParameterAcReqGetParmTypeAcReqGetValueStrAcReqSetScopedParameterName

400 P r o g r a m m i n g e . R e p o r t s

A c R e q G e t V a l u e D a t e

AcReqGetValueDateReturns the current value of the specified parameter as a date.

Syntax Basic: Function AcReqGetValueDate( fileNumber As Long, parmName As String ) As Date

C/C++: double AcReqGetValueDate( long fileNumber, LPCSTR parmName )

Parameter fileNumberThe file number of the .rov or .rox file you opened with AcReqReadFile.

parmNameThe name of the parameter whose current value you want. If you do not know the names of the parameters, use AcReqGetFirstParameter and AcReqGetNextParameter to get the parameter names.

Description Use AcReqGetValueDate to get the current value of a parameter as a date. The current value is the value last entered in the .rov file. If you are accessing an .rox file, the current value is the default value defined at design time.

When calling AcReqGetValueDate, the parameter you specify as an argument must be of type Date. If you specify a parameter of any other type, AcReqGetValueDate returns the default value for that type. To pass an argument of any type, use AcReqGetValueStr. AcReqGetValueStr always returns a string.

Use AcReqGetParmType to check the data type of a parameter.

Returns The current value of the specified parameter as a date.

Example The following example shows how to work with dates expressed as C++ doubles:

int fileNumber; double inDate, outDate; COleDateTime oleDate( 1967, 12, 6, 0, 0, 0 ); // y m d h m s inDate = oleDate; fileNumber = AcReqReadFile( szSourceRox ); outDate = AcReqGetValueDate(fileNumber, "aDate"); oleDate = outDate; AcReqSetValueDate( fileNumber, "aDate", inDate ); AcReqCloseFile( fileNumber );

See also AcReqGetFirstParameterAcReqGetNextParameterAcReqGetParmTypeAcReqGetValueStrAcReqSetScopedParameterName

C h a p t e r 2 2 , R e q u e s t e r A P I r e f e r e n c e 401

A c R e q G e t V a l u e D o u b l e

AcReqGetValueDoubleReturns the current value of the specified parameter as a double.

Syntax Basic: Function AcReqGetValueDouble( fileNumber As Long, parmName As String ) As Double

C/C++: double AcReqGetValueDouble( long fileNumber, LPCSTR parmName )

Parameter fileNumberThe file number of the .rov or .rox file you opened with AcReqReadFile.

parmNameThe name of the parameter whose current value you want. If you do not know the names of the parameters, use AcReqGetFirstParameter and AcReqGetNextParameter to get the parameter names.

Description Use AcReqGetValueDouble to get the current value of a parameter as a double. The current value is the value last entered in the .rov file. If you are accessing an .rox file, the current value is the default value defined by the programmer at design time.

When calling AcReqGetValueDouble, the parameter you specify as an argument must be of type Double. If you specify a parameter of any other type, AcReqGetValueDouble returns the default value for that type. To pass an argument of any type, use AcReqGetValueStr. AcReqGetValueStr always returns a string.

Use AcReqGetParmType to check the data type of a parameter.

Returns The current value of the specified parameter as a double.

See also AcReqGetFirstParameterAcReqGetNextParameterAcReqGetParmTypeAcReqGetValueStrAcReqSetScopedParameterName

AcReqGetValueIntegerReturns the current value of the specified parameter as an integer.

Syntax Basic: Function AcReqGetValueInteger( fileNumber As Long, parmName As String ) As Integer

C/C++: long AcReqGetValueInteger( long fileName, LPCSTR parmName )

402 P r o g r a m m i n g e . R e p o r t s

A c R e q G e t V a l u e S t r

Parameter fileNumberThe file number of the .rov or .rox file you opened with AcReqReadFile.

parmNameThe name of the parameter whose current value you want. If you do not know the names of the parameters, use AcReqGetFirstParameter and AcReqGetNextParameter to get the parameter names.

Description Use AcReqGetValueInteger to get the current value of a parameter as an integer. The current value is the value last entered in the .rov file. If you are accessing an .rox file, the current value is the default value defined by the programmer at design time.

When calling AcReqGetValueInteger, the parameter you specify as an argument must be of type Integer. If you specify a parameter of any other type, AcReqGetValueInteger returns the default value for that type. To pass an argument of any type, use AcReqGetValueStr. AcReqGetValueStr always returns a string.

Use AcReqGetParmType to check the data type of a parameter.

Returns The current value of the specified parameter as an integer.

See also AcReqGetFirstParameterAcReqGetNextParameterAcReqGetParmTypeAcReqGetValueStrAcReqSetScopedParameterName

AcReqGetValueStrReturns the current value of the specified parameter as a string.

Syntax Basic: Function AcReqGetValueStr( fileNumber As Long, parmName As String ) As String

C/C++: BSTR AcReqGetValueStr( long fileNumber, LPCSTR parmName )

Parameter fileNumberThe file number of the .rov or .rox file you opened with AcReqReadFile.

parmNameThe name of the parameter whose current value you want. If you do not know the names of the parameters, use AcReqGetFirstParameter and AcReqGetNextParameter to get the parameter names.

C h a p t e r 2 2 , R e q u e s t e r A P I r e f e r e n c e 403

A c R e q G e t V a l u e S t r i n g

Description Use AcReqGetValueStr to get the current value of a parameter as a string. The current value is the value last entered in the .rov file. If you are accessing an .rox file, the current value is the default value defined by the programmer at design time.

Use AcReqGetValueStr to get the current value of any parameter as a string. The parameter you specify as an argument can be of any type. To get the current value as the type with which the parameter was declared, use type-specific functions such as AcReqGetValueInteger or AcReqGetValueCurrency.

Returns The current value of the specified parameter as a string.

See also AcReqGetFirstParameterAcReqGetNextParameterAcReqGetParmTypeAcReqGetValueCurrencyAcReqGetValueDateAcReqGetValueDoubleAcReqGetValueIntegerAcReqGetValueStringAcReqSetScopedParameterName

AcReqGetValueStringReturns the current value of the specified parameter as a string.

Syntax Basic: Function AcReqGetValueString( fileNumber As Long, parmName As String ) As String

C/C++: BSTR AcReqGetValueString( long fileNumber, LPCSTR parmName )

Parameter fileNumberThe file number of the .rov or .rox file you opened with AcReqReadFile.

parmNameThe name of the parameter whose current value you want. If you do not know the names of the parameters, use AcReqGetFirstParameter and AcReqGetNextParameter to get the parameter names.

Description Use AcReqGetValueString to get the current value of a parameter as a string. The current value is the value last entered in the .rov file. If you are accessing an .rox file, the current value is the default value defined by the programmer at design time.

404 P r o g r a m m i n g e . R e p o r t s

A c R e q G e t V e r s i o n N u m b e r

When calling AcReqGetValueString, the parameter you specify as an argument must be of type String. If you specify a parameter of any other type, AcReqGetValueString returns the default value for that type. To pass an argument of any type, use AcReqGetValueStr. AcReqGetValueStr always returns a string.

Use AcReqGetParmType to check the data type of a parameter.

Returns The default value of the specified parameter as a string.

See also AcReqGetFirstParameterAcReqGetNextParameterAcReqGetParmTypeAcReqGetDefaultValueStrAcReqSetScopedParameterName

AcReqGetVersionNumberReturns Actuate requester API version information as a string.

Syntax Basic: Function AcReqGetVersionNumber( ) As String

C/C++: BSTR AcReqGetValueStr( )

Description Use AcReqGetVersionNumber to get the version information of the requester API.

Returns Version information as a string in the following format:

r.v.m.p - nnnn

The following table describes the values in the string.

For example, when used with Actuate 7, AcReqGetVersionNumber returns the following string:

7.0.0.0 - 2172

Number Description

r Release number

v Version number

m Maintenance version

p Patch number

nnnn Build number

C h a p t e r 2 2 , R e q u e s t e r A P I r e f e r e n c e 405

A c R e q H a s D e f a u l t V a l u e

AcReqHasDefaultValueReturns True if a default value was assigned to a specified parameter.

Syntax Basic: Function AcReqHasDefaultValue( fileNumber As Long, parmName As String ) As Boolean

C/C++: BSTR AcReqHasDefaultValue( long fileNumber, LPCSTR parmName )

Parameter fileNumberThe file number of the .rov or .rox file you opened with AcReqReadFile.

parmNameThe name of the parameter with the default value you want. If you do not know the names of the parameters, use AcReqGetFirstParameter and AcReqGetNextParameter to get the parameter names.

Description Use AcReqHasDefaultValue to determine if a default value was assigned to a parameter. The parameter you specify as an argument can be of any type. AcReqGetValueInteger returns zero if no default value is set or if the default value is set to zero. For this reason, always call AcReqHasDefaultValue to determine whether a default value is set, then call AcReqGetValueInteger to the value.

Returns True if a default value was assigned, False otherwise.

See also AcReqGetDefaultValueCurrencyAcReqGetDefaultValueDateAcReqGetDefaultValueDoubleAcReqGetDefaultValueIntegerAcReqGetDefaultValueStringAcReqGetFirstParameterAcReqGetNextParameterAcReqGetParmTypeAcReqSetScopedParameterName

AcReqInitializeInitializes the DLLs. This must be the first function you call.

Syntax Basic: Function AcReqInitialize( ) As Long

C/C++: long AcReqInitialize( )

406 P r o g r a m m i n g e . R e p o r t s

A c R e q P r i n t R e p o r t

Description This function initializes the DLLs and prepares the Requester API for use in your program. When you no longer need to use the Requester API, call AcReqUnInitialize to close the library and free resources the API uses.

Returns A handle to the initialized session.

See also AcReqUnInitialize

AcReqPrintReportPrints the specified report (.roi).

Syntax Basic: Function AcReqPrintReport( filename As String, options As Long ) As Long

C/C++: long AcReqPrintReport( LPCSTR fileName, long options )

Parameter filenameThe name of the report (.roi) to print. Specify the full path name if the file is not in the current directory.

If the file resides on a server, use the following format:

<service>:[//<server>]/<path>/<filename>[;<version>]

optionsA set of constants you can use to specify how the End User Desktop application runs. When specifying multiple options, use the plus (+) character between the options. The following table lists and describes the constants.

Constant Description

AC_REQ_LAUNCH_ALWAYS Runs a new instance of an End User Desktop application to print the report.

AC_REQ_PRINT Prints the generated report.

AC_REQ_ASYNC Runs this process asynchronously. The function returns immediately and the report prints in the background. If not specified, the function returns after the report prints.

AC_REQ_HIDE Does not display the End User Desktop application while it prints the report.

AC_REQ_STAY_OPEN Keeps the End User Desktop application open after it prints the report. This option is ignored if the report is printed in the current instance of the End User Desktop.

C h a p t e r 2 2 , R e q u e s t e r A P I r e f e r e n c e 407

A c R e q R e a d F i l e

The following examples of how to specify options with AcReqPrintReport:

AcReqPrintReport( "detail.roi", AC_REQ_HIDE )AcReqPrintReport( "detail.roi", AC_REQ_LAUNCH_ALWAYS+AC_REQ_HIDE )

The first call passes the name of the document file and a constant that represents a message to hide the End User Desktop while it prints the report. The second call passes the name of the document file and constants that represent a message to run a new instance of the End User Desktop and to hide the End User Desktop while it prints the report.

Description Use AcReqPrintReport to print an existing report on a local system. To print a report immediately after you generate it with AcReqGenerateReport, use the AC_REQ_PRINT option in AcReqGenerateReport.

If you want to change the printer setup before printing the report, use the printer-related functions such as AcReqSetPrinterName, AcReqSetPrinterNumberCopies, and AcReqSetPrinterOrientation.

Returns Use AcReqGetError to check for errors for reports generated asynchronously. For reports generated synchronously, the return value is zero when the report printed successfully. Non-zero return values indicate the report did not print.

See also AcReqSetPrinterCollateAcReqSetPrinterColorAcReqSetPrinterDuplexAcReqSetPrinterFormNameAcReqSetPrinterNameAcReqSetPrinterNumberCopiesAcReqSetPrinterOrientationAcReqSetPrinterPaperSizeAcReqSetPrinterScale

AcReqReadFileOpens a parameter value (.rov) file or a report executable (.rox) file.

Syntax Basic: Function AcReqReadFile( filename As String ) As Long

C/C++: long AcReqReadFile( LPCSTR fileName )

Parameter filenameThe name of the .rov or .rox file to open. Specify the full path name if the file is not in the current directory.

If the file resides on a server, use the following format:

<service>:[//<server>]/<path>/<filename>[;<version>]

408 P r o g r a m m i n g e . R e p o r t s

A c R e q R e p o r t S t a t u s

Description Use AcReqReadFile to open an .rov or .rox file to change or get information about parameter values before generating a report. The .rov contains parameter values that users set when they run a report. The .rox file contains the parameter definitions. If you open an .rox, the default values assigned to the parameters at design time are read into memory.

You can call AcReqReadFile multiple times to open multiple files. Each file is assigned a unique file number. Keep track of the file number—many API functions need this number as an argument.

Returns The file number of the open file.

-1 if the user does not have permission to open the file.

AcReqReportStatusReturns the status of a specified report generation request on iServer.

Syntax Basic: Sub AcReqReportStatus( RequestHandle As Long ) As Integer

C/C++: UNSIGNED SHORT AcReqReportStatus( long RequestHandle )

Parameter RequestHandleThe value that identifies a specific report generation request. AcReqGenerateReport returns this value when a request is issued successfully on a server. Only values greater than 1024 are valid.

Description Call AcReqReportStatus to determine the status of a report-generation request on iServer. For example, getting the generation status is useful before calling AcReqViewReport to display the completed report. The status information is also useful in error-handling routines.

Returns One of the values as the following table shows.

See also AcReqGetErrorAcReqGetErrorString

Value Description

0 The generation process is complete.

1 The generation process is active.

2 An error occurred during report generation.

3 An unknown, non-generation error occurred. For example, the argument passed to AcReqReportStatus is invalid.

C h a p t e r 2 2 , R e q u e s t e r A P I r e f e r e n c e 409

A c R e q S e l e c t C l i e n t

AcReqSelectClientSelect the client product to use for client-side viewing, printing, and running reports.

Syntax Basic: Function AcReqSelectClient( clientCode As Integer, installDir As String ) As Boolean

C/C++: VBBOOL AcReqSelectClient( int clientCode, const char *installDir )

Parameter clientCodeThe client code as the following table shows.

installDirThe directory where Actuate is installed. You must use the standard product search extension directory names because Actuate uses these names to locate the proper product DLL The following table shows the standard Actuate search extension directory names.

The following example shows one way to specify installDir for e.Report Designer Professional:

C:\Program Files\Actuate7\ErdPro

Description Use this function to select the Actuate client product to use for client-side viewing, printing and running reports. Not all products can perform all operations.

AcReqSelectClient supersedes AcReqSetEUDTPath. You must call this function before using the file cache functions or the AFC installation functions.

Client code Actuate client product

AC_DWB e.Report Designer Professional

AC_ERD e.Report Designer

AC_EUDT End User Desktop

AC_VIEWER Actuate Viewer

Product Standard Actuate search extension directory

e.Report Designer Erd

e.Report Designer Professional

ErdPro

End User Desktop Eudt

Report Viewer Viewer

410 P r o g r a m m i n g e . R e p o r t s

A c R e q S e t D e f a u l t P r i n t e r

You must call this function or its predecessor, AcReqSetEUDTPath, before calling the functions for printing, viewing or running a report locally.

Returns True if the client code and install directory are valid, False otherwise.

See also AcReqSetEUDTPath

AcReqSetDefaultPrinterReverts to the system’s default printer for the next print job.

Syntax Basic: Sub AcReqSetDefaultPrinter( )

C/C++: void AcReqSetDefaultPrinter( )

Description Use AcReqSetDefaultPrinter to revert to the system’s default printer after sending a print job to another printer specified with AcReqSetPrinterName.

See also AcReqPrintReportAcReqSetPrinterName

AcReqSetEUDTPathSpecifies the location of the End User Desktop application to use for report generation or the location of the Viewer application to use for report viewing.

Syntax Basic: Sub AcReqSetEUDTPath( pathName As String )

C/C++: void AcReqSetEUDTPath( LPCSTR pathName )

Parameter pathNameThe location of the End User Desktop or Viewer application to run.

The following examples show how to specify the End User Desktop and Viewer application to run:

AcReqSetEUDTPath( "C:\Program Files\Actuate7\Eudt\Bin\Runview.exe" )AcReqSetEUDTPath( "C:\Program Files\Actuate7\Viewer\Bin\Viewer.exe" )

Description Use AcReqSetEUDTPath to specify the location of the End User Desktop to use for report generation. If generating reports on iServer, do not set this path. Call AcReqSetEUDTPath in the following situations:

■ If you run the End User Desktop remotely, for example, from a Visual Basic application.

C h a p t e r 2 2 , R e q u e s t e r A P I r e f e r e n c e 411

A c R e q S e t P r i n t e r C o l l a t e

■ If you do not specify the AC_REQ_LOCAL option with AcReqGenerateReport. The AC_REQ_LOCAL option specifies that the report be generated in the current instance of e.Report Designer, e.Report Designer Professional, or End User Desktop.

■ If you are opening a report for viewing, you can use AcReqSetEUDTPath to specify the End User Desktop or Viewer application to display the report.

See also AcReqGenerateReportAcReqViewReportAcReqSelectClient

AcReqSetPrinterCollateSpecifies whether or not the printer collates multiple copies of a document.

Syntax Basic: Sub AcReqSetPrinterCollate( collate As Boolean )

C/C++: void AcReqSetPrinterCollate( VBBOOL collate )

Parameter collateTrue collates multiple copies of a document.

Description Before sending a print job, use AcReqSetPrinterCollate to specify whether or not to collate documents. To print a report, use AcReqPrintReport.

See also AcReqPrintReport

AcReqSetPrinterColorSpecifies if the report is printed in color.

Syntax Basic: Sub AcReqSetPrinterColor( color As Boolean )

C/C++: void AcReqSetPrinterColor( VBBOOL color )

Parameter colorTrue prints the report in color.

Description If printing to a color printer, use AcReqSetPrinterColor before sending a print job to specify whether or not to print in color. To print a report, use AcReqPrintReport.

See also AcReqPrintReport

412 P r o g r a m m i n g e . R e p o r t s

A c R e q S e t P r i n t e r D u p l e x

AcReqSetPrinterDuplexSpecifies if the printer prints on both sides or one side of the paper.

Syntax Basic: Sub AcReqSetPrinterDuplex( duplex As Integer )

C/C++: void AcReqSetPrinterDuplex( short duplex )

Parameter duplexThe duplex mode. Specify one of the following integer values.

Description If your printer supports duplexing, use AcReqSetPrinterDuplex before sending a print job to specify whether the printer prints on both sides or one side of the paper. AcReqSetPrinterDuplex works on local files or those stored on a Windows server. You cannot use this function on a UNIX server. To print a report, use AcReqPrintReport.

See also AcReqPrintReport

AcReqSetPrinterFormNameSpecifies the paper size by type, for example, Letter, Legal, or Executive.

Syntax Basic: Sub AcReqSetPrinterFormName( formName As String )

C/C++: void AcReqSetPrinterFormName( LPCSTR formName )

Parameter formNameThe type of paper, such as letter, legal, or others. Check your printer documentation for valid settings.

Description Before sending a print job, use AcReqSetPrinterFormName to specify the paper size by type. To specify the paper size using actual size dimensions, use AcReqSetPrinterPaperSize. To print a report, use AcReqPrintReport.

See also AcReqPrintReport

Value Duplex mode

1 Simplex mode (no duplex)

2 Horizontal duplex mode

3 Vertical duplex mode

C h a p t e r 2 2 , R e q u e s t e r A P I r e f e r e n c e 413

A c R e q S e t P r i n t e r N a m e

AcReqSetPrinterNameSpecifies the printer to use.

Syntax Basic: Sub AcReqSetPrinterName( printerName As String )

C/C++: void AcReqSetPrinterName( LPCSTR printerName )

Parameter printerNameThe name of the printer to use.

Description Before sending a print job, use AcReqSetPrinterName to specify a printer other than the default one. To revert to the system’s default printer after printing to the printer you specify with this function, call AcReqSetDefaultPrinter. To print a report, use AcReqPrintReport.

See also AcReqPrintReportAcReqSetDefaultPrinter

AcReqSetPrinterNumberCopiesSpecifies the number of copies to print.

Syntax Basic: Sub AcReqSetPrinterNumberCopies( numCopies As Integer )

C/C++: void AcReqSetPrinterNumberCopies( short numCopies )

Parameter numCopiesThe number of copies to print.

Description Before sending a print job, use AcReqSetPrinterNumberCopies to change the default setting for number of copies to print. To collate multiple copies of a document, use AcReqSetPrinterCollate. To print a report, use AcReqPrintReport.

See also AcReqSetPrinterCollateAcReqPrintReport

AcReqSetPrinterOrientationSets the printer’s page orientation to portrait or landscape.

Syntax Basic: Sub AcReqSetPrinterOrientation( orientation As Integer )

C/C++: void AcReqSetPrinterOrientation( short orientation )

414 P r o g r a m m i n g e . R e p o r t s

A c R e q S e t P r i n t e r P a p e r S i z e

Parameter orientation1 for portrait, 2 for landscape.

Description Before sending a print job, use AcReqSetPrinterOrientation to specify a different page orientation from the default one. To print a report, use AcReqPrintReport.

See also AcReqPrintReport

AcReqSetPrinterPaperSizeSpecifies the paper size.

Syntax Basic: Sub AcReqSetPrinterPaperSize( size As Integer, length As Integer, width As Integer)

C/C++: void AcReqSetPrinterPaperSize( short size, short length, short width )

Parameter sizeAn enum value between 1 and 68. Each value represents a paper size. If you set the size argument, set the length and width arguments to zero. The following table lists the enum values for the size argument and the corresponding paper sizes.

Enum value Paper size

1 Letter 8 1/2 x 11 in

2 Letter small 8 1/2 x 11in

3 Tabloid 11 x 17 in

4 Ledger 17 x 11 in

5 Legal 8 1/2 x 14 in

6 Statement 5 1/2 x 8 1/2 in

7 Executive 7 1/4 x 10 1/2 in

8 A3 sheet 297 x 420 mm

9 A4 sheet 210 x 297 mm

10 A4 Small 210 x 297 mm

11 A5 sheet 148 x 210 mm

12 B4 sheet 250 x 354 mm

13 B5 sheet 182 x 257 mm

14 Folio 8 1/2 x 13 in

15 Quarto 215 x 275 mm

C h a p t e r 2 2 , R e q u e s t e r A P I r e f e r e n c e 415

A c R e q S e t P r i n t e r P a p e r S i z e

16 10 x 14 in

17 11 x 17 in

18 Note 8 1/2 x 11 in

19 Envelope #9 3 7/8 x 8 7/8 in

20 Envelope #10 4 1/8 x 9 1/2 in

21 Envelope #11 4 1/2 x 10 3/8 in

22 Envelope #12 4 3/4 x 11 in

23 Envelope #14 5 x 11 1/2 in

24 C sheet 17 x 22 in

25 D sheet 22 x 34 in

26 E sheet 34 x 44 in

27 Envelope DL 110 x 220 mm

28 Envelope C5 162 x 229 mm

29 Envelope C3 324 x 458 mm

30 Envelope C4 229 x 324 mm

31 Envelope C6 114 x 162 mm

32 Envelope C65 114 x 229 mm

33 Envelope B4 250 x 353 mm

34 Envelope B5 176 x 250 mm

35 Envelope B6 176 x 125 mm

36 Envelope 110 x 230 mm

37 Envelope Monarch 3.875 x 7.5 in

38 6 3/4 Envelope 3 5/8 x 6 1/2 in

39 US Std Fanfold 14 7/8 x 11 in

40 German Std Fanfold 8 1/2 x 12 in

41 German Legal Fanfold 8 1/2 x 13 in

42 B4 (ISO) 250 x 353 mm

43 Japanese Postcard 100 x 148 mm

44 9 x 11 in

45 10 x 11 in

46 15 x 11 in

47 Envelope Invite 220 x 220 mm

48 RESERVED--DO NOT USE

Enum value Paper size

416 P r o g r a m m i n g e . R e p o r t s

A c R e q S e t P r i n t e r P a p e r S i z e

length, widthThe physical length and width of the paper in tenths of a millimeter. If you set the length and width arguments, set the size argument to zero. To convert inches to tenths of a millimeter, multiply the number by 254. For example, to specify a paper size of 8.5 by 11 inches, specify 2159 (8.5 * 254) for the width argument, and 2794 (11 * 254) for the length argument.

Description Before sending a print job, use AcReqSetPrinterPaperSize to specify the paper size on which to print. When working with a server running on a Windows platform, you can specify either logical or physical paper size. On a UNIX platform, you can only specify logical paper size. To print a report, use AcReqPrintReport.

See also AcReqPrintReport

49 RESERVED--DO NOT USE

50 Letter Extra 9 \275 x 12 in

51 Legal Extra 9 \275 x 15 in

52 Tabloid Extra 11.69 x 18 in

53 A4 Extra 9.27 x 12.69 in

54 Letter Transverse 8 \275 x 11 in

55 A4 Transverse 210 x 297 mm

56 Letter Extra Transverse 9\275 x 12 in

57 SuperA/SuperA/A4 227 x 356 mm

58 SuperB/SuperB/A3 305 x 487 mm

59 Letter Plus 8.5 x 12.69 in

60 A4 Plus 210 x 330 mm

61 A5 Transverse 148 x 210 mm

62 B5 (JIS) Transverse 182 x 257 mm

63 A3 Extra 322 x 445 mm

64 A5 Extra 174 x 235 mm

65 B5 (ISO) Extra 201 x 276 mm

66 A2 420 x 594 mm

67 A3 Transverse 297 x 420 mm

68 A3 Extra Transverse 322 x 445 mm

Enum value Paper size

C h a p t e r 2 2 , R e q u e s t e r A P I r e f e r e n c e 417

A c R e q S e t P r i n t e r S c a l e

AcReqSetPrinterScaleSpecifies the size of the image to print.

Syntax Basic: Sub AcReqSetPrinterScale( scale As Integer )

C/C++: void AcReqSetPrinterScale( short scale )

Parameter scaleThe percentage of the original size at which to print. Check your printer documentation for the valid range.

Description Before sending a print job, use AcReqSetPrinterScale to specify the size of the image to print. To print a report, use AcReqPrintReport.

See also AcReqPrintReport

AcReqSetPrinterTraySpecifies the printer tray for the paper source.

Syntax Basic: Sub AcReqSetPrinterTray( tray as Short)

C/C++: void AcReqSetPrinterTray( short tray)

Parameter trayAn enum value indicating the printer tray. The following table lists the enum values and the corresponding printer tray for the paper source. These values are not the same across all printers. Refer to you printer documentation for appropriate printer tray numbers.

Enum value Description

1 Use paper from upper bin.

2 Use paper from lower bin.

3 Use paper from middle bin.

4 Wait for manual insertion of each sheet of paper.

5 Use envelopes from the envelope feeder.

6 Use envelopes from the envelope feeder, but wait for manual insertion.

7 Use paper from the current default bin.

8 Use paper fed from the tractor feeder.

9 Use paper from the small paper feeder.

418 P r o g r a m m i n g e . R e p o r t s

A c R e q S e t R e q u e s t P r i o r i t y

Description Before sending a print job, use AcReqSetPrinterTray to specify the paper tray. AcReqSetPrinterTray passes the tray number directly to the DEVMODE structure’s dmDefaultSource member.

See also AcReqPrintReport

AcReqSetRequestPrioritySpecifies the priority for report generation on iServer.

Syntax Basic: Sub AcReqSetRequestPriority( priority as Long)

C/C++: void AcReqSetRequestPriority( long priority )

Parameter priorityThe priority for report generation: from 0 - 1000.

Description Before generating a report, call AcReqSetRequestPriority to specify the priority level on iServer. A higher number indicates greater priority. iServer can restrict the priority to the range permitted for the current user.

See also AcReqGenerateReport

AcReqSetScopedParameterNameSpecifies how parameter names are retrieved.

Syntax Basic: Sub AcReqSetScopedParameterName( fileNumber As Long, scopedParam As Boolean )

C/C++: void AcReqSetScopedParameterName( Long fileNumber, VBBOOL scopedParam )

Parameter fileNumberThe file number of the .rov or .rox file you opened with AcReqReadFile.

10 Use paper from the large paper bin.

11 Use paper from the large capacity feeder.

14 Use paper from the attached cassette cartridge.

Enum value Description

C h a p t e r 2 2 , R e q u e s t e r A P I r e f e r e n c e 419

A c R e q S e t V a l u e C u r r e n c y

scopedParamDetermines the return type of the AcReqGetFirstParameter and AcReqGetNextParameter methods. If True, the retrieved parameter names are fully scoped. If False, the retrieved parameter names are not fully scoped. The default value is False.

Description Call AcReqSetScopedParameterName to specify whether on not parameter names are retrieved fully scoped. Call AcReqSetScopedParameterName repeatedly to specify how parameter names are retrieved.

Example The following examples show how to specify whether or not parameter names are retrieved fully scoped. In both examples, the parameter name is fully scoped as NewReportApp::DataSource::param1.

In the following example, the value of CurrentParameter is NewReportApp::DataSource::param1:

AcReqSetScopedParameterName( fileNumber, TRUE )CurrentGroup = AcReqGetFirstGroup(fileNumber)CurrentParameter = AcReqGetFirstParameter(fileNumber, CurrentGroup)

In the following example, the value of CurrentParameter is param1:

AcReqSetScopedParameterName( fileNumber, FALSE )CurrentGroup = AcReqGetFirstGroup(fileNumber)CurrentParameter = AcReqGetFirstParameter(fileNumber, CurrentGroup)

See also AcReqGetFirstParameterAcReqGetNextParameter

AcReqSetValueCurrencySets the value of the specified parameter as a currency.

Syntax Basic: Sub AcReqSetValueCurrency( fileNumber As Long, parmName As String, value As Currency )

C/C++: void AcReqSetValueCurrency( long fileNumber, LPCSTR parmName, REQCYTYPE value )

Parameter fileNumberThe file number of the .rov or .rox file you opened with AcReqReadFile.

parmNameThe name of the parameter whose value you want to set. If you do not know the names of the parameters, use AcReqGetFirstParameter and AcReqGetNextParameter to get the parameter names.

420 P r o g r a m m i n g e . R e p o r t s

A c R e q S e t V a l u e D a t e

valueThe currency value to assign to the parameter.

Description Use AcReqSetValueCurrency to assign a currency value to a parameter. The parameter whose value you want to set must be of type Currency. Use AcReqGetParmType to check the data type of a parameter before setting its value.

In C/C++, the structure REQCYTYPE, stores up to 64 bits. If you need to assign a currency value to a parameter that requires a 96-bit structure, convert the currency value to a string value, then call AcReqSetValueString to assign the value. If you call AcReqSetValueCurrency to assign a currency value larger than 64 bits, GetError returns an error number.

See also AcReqGetFirstParameterAcReqGetNextParameterAcReqGetParmTypeAcReqSetScopedParameterName

AcReqSetValueDateSets the value of the specified parameter as a date.

Syntax Basic: Sub AcReqSetValueDate( fileNumber As Long, parmName As String, value As Date )

C/C++: void AcReqSetValueDate( long fileNumber, LPCSTR parmName, double value )

Parameter fileNumberThe file number of the .rov or .rox file you opened with AcReqReadFile.

parmNameThe name of the parameter whose value you want to set. If you do not know the names of the parameters, use AcReqGetFirstParameter and AcReqGetNextParameter to get the parameter names.

valueThe date value to assign to the parameter. The date value is a floating point number containing the number of days from midnight on December 30, 1899. Hours are shown as a fraction of a day. For example, the value for December 30, 1899 is 0.0. The date value for January 1, 1900 at 6 A.M. is 2.25.

Description Use AcReqSetValueDate to assign a date value to a parameter. The parameter whose value you want to set must be of type Date. Use AcReqGetParmType to check the data type of a parameter before setting its value. Ensure that the date value passed to AcReqSetValueDate is a floating point number expressed

C h a p t e r 2 2 , R e q u e s t e r A P I r e f e r e n c e 421

A c R e q S e t V a l u e D o u b l e

using the format described for the value parameter. On Windows servers, you can call the C++ function, COleDateTime, to convert the date for AcReqSetValueDate.

Example The following example shows how to work with dates expressed as C++ doubles on Windows NT:

int fileNumber;double inDate, outDate;COleDateTime oleDate( 1967, 12, 6, 0, 0, 0 ); // y m d h m sinDate = oleDate;fileNumber = AcReqReadFile( szSourceRox );outDate = AcReqGetDefaultValueDate(fileNumber, "aDate");oleDate = outDate;AcReqSetValueDate( fileNumber, "aDate", inDate );AcReqCloseFile( fileNumber );

See also AcReqGetFirstParameterAcReqGetNextParameterAcReqGetParmTypeAcReqSetScopedParameterName

AcReqSetValueDoubleSets the value of the specified parameter as a double.

Syntax Basic: Sub AcReqSetValueDouble( fileNumber As Long, parmName As String, value As Double )

C/C++: void AcReqSetValueDouble( long fileNumber, LPCSTR parmName, double value )

Parameter fileNumberThe file number of the .rov or .rox file you opened with AcReqReadFile.

parmNameThe name of the parameter whose value you want to set. If you do not know the names of the parameters, use AcReqGetFirstParameter and AcReqGetNextParameter to get the parameter names.

valueThe double value to assign to the parameter.

Description Use AcReqSetValueDouble to assign a double value to a parameter. The parameter whose value you want to set must be of type Double. Use AcReqGetParmType to check the data type of a parameter before setting its value.

422 P r o g r a m m i n g e . R e p o r t s

A c R e q S e t V a l u e I n t e g e r

See also AcReqGetFirstParameterAcReqGetNextParameterAcReqGetParmTypeAcReqSetScopedParameterName

AcReqSetValueIntegerSets the value of the specified parameter as an integer.

Syntax Basic: Sub AcReqSetValueInteger( fileNumber As Long, parmName As String, value As Integer )

C/C++: void AcReqSetValueInteger( long fileNumber, LPCSTR parmName, long value )

Parameter fileNumberThe file number of the .rov or .rox file you opened with AcReqReadFile.

parmNameThe name of the parameter whose value you want to set. If you do not know the names of the parameters, use AcReqGetFirstParameter and AcReqGetNextParameter to get the parameter names.

valueThe integer value to assign to the parameter.

Description Use AcReqSetValueInteger to assign an integer value to a parameter. The parameter whose value you want to set must be of type Integer. Use AcReqGetParmType to check the data type of a parameter before setting its value.

See also AcReqGetFirstParameterAcReqGetNextParameterAcReqGetParmTypeAcReqSetScopedParameterName

AcReqSetValueStringSets the value of the specified parameter as a string.

Syntax Basic: Sub AcReqSetValueString( fileNumber As Long, parmName As String, value As String )

C h a p t e r 2 2 , R e q u e s t e r A P I r e f e r e n c e 423

A c R e q U n I n i t i a l i z e

C/C++: void AcReqSetValueString( long fileNumber, LPCSTR parmName, LPCSTR value )

Parameter fileNumberThe file number of the .rov or .rox file you opened with AcReqReadFile.

parmNameThe name of the parameter whose value you want to set. If you do not know the names of the parameters, use AcReqGetFirstParameter and AcReqGetNextParameter to get the parameter names.

valueThe string value to assign to the parameter.

Description Use AcReqSetValueString to assign a string value to a parameter. The parameter whose value you want to set must be of type String. Use AcReqGetParmType to check the data type of a parameter before setting its value.

See also AcReqGetFirstParameterAcReqGetNextParameterAcReqGetParmTypeAcReqSetScopedParameterName

AcReqUnInitializeCloses the Requester API library and frees resources.

Syntax Basic: Function AcReqUninitialize( sessionHandle ) As Boolean

C/C++: VBBOOL AcReqUnInitialize( long sessionHandle )

Parameter sessionHandleThe handle to the session to uninitialize. AcReqInitialize returns this value when the Requester API is initialized.

Description When you are finished using the Requester API, call AcReqUninitialize to close the library and free resources it used. Call AcReqUninitialize at the end of your program.

Returns AcReqUnInitialize always returns True.

See also AcReqInitialize

424 P r o g r a m m i n g e . R e p o r t s

A c R e q V i e w R e p o r t

AcReqViewReport Displays the specified report (.roi).

Syntax Basic: Function AcReqViewReport( filename As String, options As Long ) As Long

C/C++: long AcReqViewReport( LPCSTR filename, long options )

Parameter filenameThe name of the report (.roi) to display. Specify the full path name if the file is not in the current directory.

If the file resides on a server, use the following format:

<service>:[//<server>]/<path>/<filename>[;<version>]

optionsA set of constants you can use to specify how the End User Desktop application runs. When specifying multiple options, use the plus (+) character between the options. The following table lists and describes the constants.

The following examples show how to specify options with AcReqViewReport:

AcReqViewReport("detail.roi", AC_REQ_LAUNCH_ALWAYS)AcReqViewReport("detail.roi", AC_REQ_LAUNCH_ALWAYS+AC_REQ_ASYNC)

The first call passes the name of the document file and a constant that represents a message to run a new instance of the End User Desktop. The second call passes the name of the document file and constants that represent a

Constant Description

AC_REQ_LAUNCH_ALWAYS Runs a new instance of an End User Desktop application to display the report.

AC_REQ_LOCAL Displays the report in the current instance of e.Report Designer, e.Report Designer Professional, or End User Desktop.

AC_REQ_VIEW Displays the generated report.

AC_REQ_ASYNC Runs this process asynchronously. The function returns immediately and the report displays in the background. If not specified, the function returns after the report displays.

C h a p t e r 2 2 , R e q u e s t e r A P I r e f e r e n c e 425

A c R e q W r i t e F i l e

message to run a new instance of the End User Desktop and to run the request asynchronously.

Description Use AcReqViewReport to display an existing report. To display a report immediately after you generate it with AcReqGenerateReport, use the AC_REQ_VIEW option in AcReqGenerateReport.

Returns 0 if the report was displayed.

Any number other than zero if the report was not displayed.

See also AcReqGenerateReport

AcReqWriteFileCreates a parameter value (.rov) file.

Syntax Basic: Sub AcReqWriteFile( fileNumber As Long, filename As String )

C/C++: void AcReqWriteFile( long fileNumber, LPCSTR filename )

Parameter fileNumberThe file number of the .rov or .rox file you opened with AcReqReadFile.

filenameThe name of the.rov file to create. The file name must include the.rov filename extension.

If the file resides on a server, use the following format:

<service>:[//<server>]/<path>/<filename>[;<version>]

Description Use AcReqWriteFile to write the parameter values to an .rov file. You set parameter values using functions such as AcReqSetValueString or AcReqSetValueInteger. Before calling AcReqWriteFile or any of the functions to change or inspect parameter values, you must call AcReqReadFile to open the appropriate .rox or .rov file.

After creating the .rov file, you can call AcReqGenerateReport to create a report from that .rov file.

See also AcReqReadFile

AcWReqConnectConnects to the specified server.

426 P r o g r a m m i n g e . R e p o r t s

A c W R e q G e n e r a t e R e p o r t

Syntax Basic: Function AcWReqConnect( server As String, username As String, password As String ) As Long

C/C++: long AcWReqConnect( LPCTSTR server, LPCTSTR user, LPCTSTR password )

Parameter serverThe name of iServer to which to connect.

userThe user name to use to log into iServer.

passwordThe password to use to log into iServer.

Description To access files and generate reports on a server, you must call AcWReqConnect to connect to iServer. Once your program establishes a connection to iServer, you can call any of the Requester API functions to access files on iServer.

When your program has finished executing tasks on iServer, call AcReqDisconnect to disconnect from iServer.

Returns A number indicating the connection handle.

-1 if the connection failed.

See also AcReqDisconnect

AcWReqGenerateReportGenerates a report (.roi) from a report executable (.rox) file or a parameter values (.rov) file.

Syntax Basic: Function AcWReqGenerateReport( filename As String, options As Long, fileNumber As Long ) As Long

C/C++: long AcWReqGenerateReport( LPCTSTR aFileName, long options, long fileHandle )

Parameter aFileNameThe name of the .rox or .rov file to use to generate the report. Specify the full path name if the file is not in the current directory.

If the file resides on a server, use the following format:

rotp:[//<server>]/<path>/<filename>[;<version>]

For information about specifying server file names, see Chapter 2, “Specifying an iServer file name—Requester API.”

C h a p t e r 2 2 , R e q u e s t e r A P I r e f e r e n c e 427

A c W R e q G e n e r a t e R e p o r t

optionsA set of constants you can use to specify how the End User Desktop application runs. When specifying multiple options, logically add them using the plus (+) character. The following table lists and describes the constants.

Option Description

AC_REQ_LAUNCH_ALWAYS Runs a new instance of an End User Desktop application to generate the report. AC_REQ_LAUNCH_ALWAYS and AC_REQ_LOCAL are mutually exclusive.

AC_REQ_LOCAL Generates the report in the current instance of e.Report Designer, e.Report Designer Professional, or End User Desktop. AC_REQ_LAUNCH_ALWAYS and AC_REQ_LOCAL are mutually exclusive.

AC_REQ_GENERATE Generates the report.

AC_REQ_VIEW Displays the generated report.

AC_REQ_PRINT Prints the generated report.

AC_REQ_ASYNC Runs this process asynchronously. The function returns immediately and the report generates in the background.

AC_REQ_HIDE Does not display the End User Desktop application while it generates the report.

AC_REQ_RETURN_HANDLE Returns a handle to the synchronous report request.

AC_REQ_STAY_OPEN Keeps the End User Desktop application open after it generates the report. This option is ignored if the report is generated in the current instance of the End User Desktop.

AC_REQ_SHOW_PROG_WND Displays the progress window of the End User Desktop, e.Report Designer, or e.Report Designer Professional while a report generates.

AC_REQ_REPLACE Overwrites the latest report. When omitted, the report is created with a version number.

AC_REQ_USE_HANDLE Reserved.

428 P r o g r a m m i n g e . R e p o r t s

A c W R e q G e n e r a t e R e p o r t

Scope of optionsThe following table shows which options apply to reports generated locally or on iServer and launched from either local or server applications.

If you do not specify any generation options, Actuate does the following by default:

■ Generates the report with the current instance of the End User Desktop application. If an End User Desktop application is not running, Actuate attempts to launch a new instance, but only if you specified the location with the AcWReqSetEUDTPath function.

■ Runs the process synchronously. The function returns after the report is generated.

■ Displays the End User Desktop application as it generates the report only if the report is local.

fileHandleThe handle to the file you opened with AcReqReadFile or AcWReqReadFile.

Description Use AcWReqGenerateReport to generate a report based on parameter values specified in an .rov or .rox file. Using this function, you incorporate report generation in your application. This capability is useful for batch creation of reports.

To generate a report from an .rov file, Actuate runs the .rox file associated with the .rov file you specify. It looks for the .rox file in the same directory where the .rov file resides. If the .rox file is not in the same directory as the .rov file,

OptionsLocal reportLocal launch

Server reportLocal launch

Server reportServer launch

AC_REQ_LAUNCH_ALWAYS Yes Yes, if report viewing needed

No

AC_REQ_LOCAL Yes, if using Actuate Basic

No No

AC_REQ_VIEW Yes Yes No

AC_REQ_PRINT Yes Yes Yes

AC_REQ_ASYNC Yes Yes Yes

AC_REQ_HIDE Yes, if report viewing not needed

Yes, if report viewing not needed

No

AC_REQ_RETURN_HANDLE Yes Yes Yes

AC_REQ_STAY_OPEN Yes Yes, if report viewing needed

No

AC_REQ_REPLACE No Yes Yes

C h a p t e r 2 2 , R e q u e s t e r A P I r e f e r e n c e 429

A c W R e q G e n e r a t e R e p o r t

Actuate displays “Can’t access <file name>.rox” and displays an open file dialog box which you can use to find the .rox file.

To run a report in batch mode, specify the .rox file programmatically. To do this, set the .rox file name parameter represented by the constant AC_REQ_ROX to the name of the .rox file to use before you write the parameter values to a new .rov file. The .rox file name is a hidden parameter that can only be set programmatically. To set the .rox file name parameter, use AcWReqSetValueString as the following example shows:

AcWReqSetValueString( fileNum, AC_REQ_ROX, "C:\Test\Myreport.rox" )

If the .rox you want to run is in the same directory as the .rov file, you do not have to set the .rox file name parameter.

By default, the .roi file that AcWReqGenerateReport creates has the same root name as the .rox file used to create the report, but you can change the .roi file name with AcWReqSetValueString. For more information, see “AcWReqSetValueString,” later in this chapter.

For more information and an example on generating a report, see Chapter 2, “Using the Requester API in Visual Basic.”

Returns Use AcReqGetError function to check for errors for reports generated asynchronously. For reports generated synchronously, the return value from AcWReqGenerateReport indicates the result of the report execution and any error codes as the following table shows.

Return valueReport generation mode Indication

0 Report generated asynchronously

Report executed successfully on a local client.

1 to 1023 Report generated asynchronously

Report execution failed.The return value indicates the error code. This method returns the same error codes as AcReqGetError. For more information, see “AcReqGetError.”

1024 or greater Report generated asynchronously

Report executed successfully on iServer. The return value is a request handle that can be used to get more information about the report, such as the report version number.

0 or less than 0 Report generated synchronously

Report executed successfully on iServer.

greater than 0 Report generated synchronously

Report execution failed.

430 P r o g r a m m i n g e . R e p o r t s

A c W R e q G e t A d h o c

See also AcReqGetReportVersionAcReqSetRequestPriorityAcWReqSetEUDTPath

AcWReqGetAdhocReturns True if the parameter is an ad hoc parameter, False if the parameter is not an ad hoc parameter.

Syntax Basic: Function AcWReqGetAdhoc( fileNumber As Long, parmName As String ) As Boolean

C/C++ VBBOOL AcWReqGetAdhoc( long fileHandle, LPCTSTR aParmName )

Parameter fileHandleThe handle to the file you opened with AcReqReadFile or AcWReqReadFile.

aParmNameThe name of the parameter whose ad hoc attribute to return. If you do not know the names of the parameter, use AcWReqGetFirstParameter and AcWReqGetNextParameter to get the parameter names.

Description Use AcWReqGetAdhoc to find out if a parameter was designed as an ad hoc parameter. An ad hoc parameter accepts a conditional expression that extends the Where clause of a query when the report is generated.

Returns True if the parameter is ad hoc, False otherwise.

See also AcReqSetScopedParameterNameAcWReqGetFirstParameterAcWReqGetNextParameter

AcWReqGetAliasReturns the alternate name of the specified parameter.

Syntax Basic: Function AcWReqGetAlias( fileNumber As Long, parmName As String ) As String

C/C++: BSTR AcWReqGetAlias( long fileHandle, LPCTSTR aParmName )

Parameter fileHandleThe handle to the file you opened with AcReqReadFile or AcWReqReadFile.

C h a p t e r 2 2 , R e q u e s t e r A P I r e f e r e n c e 431

A c W R e q G e t D e f a u l t V a l u e C u r r e n c y

aParmNameThe name of the parameter whose alias you want. If you do not know the name of the parameter, use AcWReqGetFirstParameter and AcWReqGetNextParameter to get the parameter name.

Description Use AcWReqGetAlias to get the alias of a parameter. When defining parameters, use alias names to create descriptive prompts that appear in the Requester dialog box. For example, Customer Name is more descriptive than Cust_Name.

If building a custom requestor interface in a Visual Basic form, for example, you can use the alias names that AcWReqGetAlias returns to create an interface similar to the Requester dialog box in e.Report Designer or e.Report Designer Professional.

Returns The alias of the specified parameter.

An empty string if there is no alias or if an error occurred.

See also AcReqSetScopedParameterNameAcWReqGetFirstParameterAcWReqGetNextParameter

AcWReqGetDefaultValueCurrencyReturns the default value of the specified parameter as a currency.

Syntax Basic: Function AcWReqGetDefaultValueCurrency( fileNumber As Long, parmName As String ) As Currency

C/C++: REQCYTYPE AcWReqGetDefaultValueCurrency( long fileHandle, LPCTSTR aParmName )

Parameter fileHandleThe handle to the file you opened with AcReqReadFile or AcWReqReadFile.

aParmNameThe name of the parameter whose default value you want. If you do not know the names of the parameter, use AcWReqGetFirstParameter and AcWReqGetNextParameter to get the parameter name.

Description Use AcWReqGetDefaultValueCurrency to get the default value of a parameter as a currency. The default value is defined at design time. The default value is constant and independent of the value the user sets. Required parameters always have default values. The default value is used if the user does not supply a value when the report runs.

432 P r o g r a m m i n g e . R e p o r t s

A c W R e q G e t D e f a u l t V a l u e D a t e

When calling AcWReqGetDefaultValueCurrency, the parameter you specify as an argument must be of type Currency. If you specify a parameter of any other type, AcWReqGetDefaultValueCurrency returns the default value for that type. To pass an argument of any type, use AcWReqGetDefaultValueStr. AcWReqGetDefaultValueStr always returns a string.

To check the data type of a parameter, use AcWReqGetParmType.

In C/C++, the structure REQCYTYPE stores up to 64 bits. If you need to retrieve default currency values that require a 96-bit structure, use AcWReqGetDefaultValueString to return the value. Convert the string value to a currency value within your application program. When you call AcWReqGetDefaultValueCurrency to return a default currency value larger than 64 bits, the GetError function returns an error number.

Returns The default value of the specified parameter as a currency.

See also AcReqSetScopedParameterNameAcWReqGetDefaultValueStrAcWReqGetFirstParameterAcWReqGetNextParameterAcWReqGetParmType

AcWReqGetDefaultValueDateReturns the default value of the specified parameter as a date.

Syntax Basic: Function AcWReqGetDefaultValueDate( fileNumber As Long, parmName As String ) As Date

C/C++: double AcWReqGetDefaultValueDate( long fileHandle, LPCTSTR aParmName )

Parameter fileHandleThe handle to the file you opened with AcReqReadFile or AcWReqReadFile.

aParmNameThe name of the parameter whose default value you want. If you do not know the name of the parameter, use AcWReqGetFirstParameter and AcWReqGetNextParameter to get the parameter name.

Description Use AcWReqGetDefaultValueDate to get the default value of a parameter as a date. The default value is defined at design time. This value is used if the user does not supply a value when the report runs. A default value is constant and independent of the value the user sets. Required parameters always have default values.

C h a p t e r 2 2 , R e q u e s t e r A P I r e f e r e n c e 433

A c W R e q G e t D e f a u l t V a l u e D o u b l e

When calling AcWReqGetDefaultValueDate, the parameter you specify as an argument must be of type Date. If you specify a parameter of any other type, AcWReqGetDefaultValueDate returns the default value for that type. To pass an argument of any type, use AcWReqGetDefaultValueStr. AcWReqGetDefaultValueStr always returns a string.

Use AcWReqGetParmType to check the data type of a parameter.

Returns The default value of the specified parameter as a date.

Example The following example shows how to work with dates expressed as C++ doubles:

int fileNumber; double inDate, outDate; COleDateTime oleDate( 1967, 12, 6, 0, 0, 0 ); // y m d h m s inDate = oleDate; fileNumber = AcReqReadFile( szSourceRox ); outDate = AcWReqGetDefaultValueDate(fileNumber, "aDate"); oleDate = outDate; AcWReqSetValueDate( fileNumber, "aDate", inDate ); AcReqCloseFile( fileNumber );

See also AcReqSetScopedParameterNameAcWReqGetDefaultValueStrAcWReqGetFirstParameterAcWReqGetNextParameterAcWReqGetParmType

AcWReqGetDefaultValueDoubleReturns the default value of the specified parameter as a double.

Syntax Basic: Function AcWReqGetDefaultValueDouble( fileNumber As Long, parmName As String ) As Double

C/C++: double AcWReqGetDefaultValueDouble( long fileHandle, LPCTSTR aParmName )

Parameter fileHandleThe handle to the file you opened with AcReqReadFile or AcWReqReadFile.

aParmNameThe name of the parameter whose default value you want. If you do not know the name of the parameter, use AcWReqGetFirstParameter and AcWReqGetNextParameter to get the parameter name.

434 P r o g r a m m i n g e . R e p o r t s

A c W R e q G e t D e f a u l t V a l u e I n t e g e r

Description Use AcWReqGetDefaultValueDouble to get the default value of a parameter as a double. The default value is defined at design time. This value is used if the user does not supply a value when the report runs. A default value is constant and independent of the value the user sets. Required parameters always have default values.

When calling AcWReqGetDefaultValueDouble, the parameter you specify as an argument must be of type Double. If you specify a parameter of any other type, AcWReqGetDefaultValueDouble returns the default value for that type. To pass an argument of any type, use AcWReqGetDefaultValueStr. AcWReqGetDefaultValueStr always returns a string.

Use AcReqGetParmType to check the data type of a parameter.

Returns The default value of the specified parameter as a double.

See also AcReqSetScopedParameterNameAcWReqGetDefaultValueStrAcWReqGetFirstParameterAcWReqGetNextParameterAcWReqGetParmType

AcWReqGetDefaultValueIntegerReturns the default value of the specified parameter as an integer.

Syntax Basic: Function AcWReqGetDefaultValueInteger( fileNumber As Long, parmName As String ) As Integer

C/C++: long AcWReqGetDefaultValueInteger( long fileHandle, LPCTSTR aParmName )

Parameter fileHandleThe handle to the file you opened with AcReqReadFile or AcWReqReadFile.

aParmNameThe name of the parameter whose default value you want. If you do not know the name of the parameter, use AcWReqGetFirstParameter and AcWReqGetNextParameter to get the parameter name.

Description Use AcWReqGetDefaultValueInteger to get the default value of a parameter as an integer. The default value is defined at design time. This value is used if the user does not supply a value when the report runs. A default value is constant and independent of the value the user sets. Required parameters always have default values.

C h a p t e r 2 2 , R e q u e s t e r A P I r e f e r e n c e 435

A c W R e q G e t D e f a u l t V a l u e S t r

When calling AcWReqGetDefaultValueInteger, the parameter you specify as an argument must be of type Integer. If you specify a parameter of any other type, AcWReqGetDefaultValueInteger returns the default value for that type. To pass an argument of any type, use AcWReqGetDefaultValueStr. AcReqGetDefaultValueStr always returns a string.

Use AcWReqGetParmType to check the data type of a parameter.

Returns The default value of the specified parameter as an integer.

See also AcReqSetScopedParameterNameAcWReqGetDefaultValueStrAcWReqGetFirstParameterAcWReqGetNextParameterAcWReqGetParmType

AcWReqGetDefaultValueStrReturns the default value of the specified parameter as a string.

Syntax Basic: Function AcWReqGetDefaultValueStr( fileNumber As Long, parmName As String ) As String

C/C++: BSTR AcWReqGetDefaultValueStr( long fileHandle, LPCTSTR aParmName )

Parameter fileHandleThe handle to the file you opened with AcReqReadFile or AcWReqReadFile.

aParmNameThe name of the parameter whose default value you want. If you do not know the name of the parameter, use AcWReqGetFirstParameter and AcWReqGetNextParameter to get the parameter name.

Description Use AcWReqGetDefaultValueStr to get the default value of a parameter as a string. The parameter you specify as an argument can be of any type. To get the default value as the type with which the parameter was declared, use type-specific functions such as AcWReqGetDefaultValueInteger or AcWReqGetDefaultValueCurrency.

The default value is defined at design time. This value is used if the user does not supply a value when the report runs. A default value is constant and independent of the value the user sets. Required parameters always have default values.

Returns The default value of the specified parameter as a string.

436 P r o g r a m m i n g e . R e p o r t s

A c W R e q G e t D e f a u l t V a l u e S t r i n g

See also AcWReqGetDefaultValueCurrencyAcWReqGetDefaultValueDateAcWReqGetDefaultValueDoubleAcWReqGetDefaultValueIntegerAcWReqGetDefaultValueStringAcWReqGetFirstParameterAcWReqGetNextParameterAcWReqGetParmType

AcWReqGetDefaultValueStringReturns the default value of the specified parameter as a string.

Syntax Basic: Function AcWReqGetDefaultValueString( fileNumber As Long, parmName As String ) As String

C/C++: BSTR AcWReqGetDefaultValueString( long fileHandle, LPCTSTR aParmName )

Parameter fileHandleThe handle to the file you opened with AcReqReadFile or AcWReqReadFile.

aParmNameThe name of the parameter whose default value you want. If you do not know the name of the parameter use AcWReqGetFirstParameter and AcWReqGetNextParameter to get the parameter names.

Description Use AcWReqGetDefaultValueString to get the default value of a parameter as a string. The default value is defined at design time. This value is used if the user does not supply a value when the report runs. A default value is constant and independent of the value the user sets. Required parameters always have default values.

When calling AcWReqGetDefaultValueString, the parameter you specify as an argument must be of type String. If you specify a parameter of any other type, AcWReqGetDefaultValueString returns the default value for that type.To pass an argument of any type, use AcWReqGetDefaultValueStr. AcReqGetDefaultValueStr always returns a string.

Use AcWReqGetParmType to check the data type of a parameter.

Returns The default value of the specified parameter as a string.

See also AcReqSetScopedParameterNameAcWReqGetDefaultValueStrAcWReqGetFirstParameterAcWReqGetNextParameterAcWReqGetParmType

C h a p t e r 2 2 , R e q u e s t e r A P I r e f e r e n c e 437

A c W R e q G e t E r r o r S t r i n g

AcWReqGetErrorStringReturns a string describing the last error that occurred during an API function call.

Syntax Basic: Function AcWReqGetErrorString( fileNumber As Long ) As String

C/C++: BSTR AcWReqGetErrorString( long fileHandle )

Parameter fileHandleThe handle to the file you opened with AcReqReadFile or AcWReqReadFile.

Description Use AcWReqGetErrorString to check for error conditions and retrieve a description of the error. To get the error number, use AcWReqGetError. For a list of the error strings that AcSReqGetErrorString return, see AcWReqGetErrorStr.

Returns The error string of the last error.

AcWReqGetFirstGroupReturns the name of the first parameter group in the specified parameter value (.rov) file or parameter definition section of the specified .rox file.

Syntax Basic: Function AcWReqGetFirstGroup( fileNumber As Long ) As String

C/C++: BSTR AcWReqGetFirstGroup( long fileHandle )

Parameter fileHandleThe handle to the file you opened with AcReqReadFile or AcWReqReadFile.

Description Use AcWReqGetFirstGroup in conjunction with AcWReqGetNextGroup, AcWReqGetFirstParameter, and AcWReqGetNextParameter to get information about the organization of parameters in a specified .rov or .rox file. For example, if you are building a custom requestor interface in a Visual Basic form, you can use the strings that these functions return to create a structure similar to the Requester interface in e.Report Designer or e.Report Designer Professional.

You can organize parameters into groups for ease of use. For example, CustomerName, CustomerPhone, and Credit_Rank might be parameters in a Customer parameters group, and City and State might be parameters in an Office parameters group.

If there are no parameter groups, the parameters have an empty string (" ") as their group name.

438 P r o g r a m m i n g e . R e p o r t s

A c W R e q G e t F i r s t P a r a m e t e r

Returns The name of the first parameter group in the specified .rov or .rox file, if a group exists.

An empty string if there are no groups or if an error occurred.

See also AcWReqGetFirstParameterAcWReqGetNextGroupAcWReqGetNextParameter

AcWReqGetFirstParameterReturns the name of the first parameter in the specified parameter group.

Syntax Basic: Function AcWReqGetFirstParameter( fileNumber As Long, parmGroup As String ) As String

C/C++: BSTR AcWReqGetFirstParameter( long fileHandle, LPCTSTR aGroupName )

Parameter fileHandleThe handle to the file you opened with AcReqReadFile or AcWReqReadFile.

aGroupNameThe name of the parameter group in which to find the first parameter. To get all parameters that belong in any group, specify an empty string for this argument. If you do not know the name of the parameter group, use AcWReqGetFirstGroup and AcWReqGetNextGroup to get the group names.

Description Use AcWReqGetFirstParameter in conjunction with AcWReqGetNextParameter, AcWReqGetFirstGroup, and AcWReqGetNextGroup to get information about the organization of parameters in a specified .rov or .rox file. For example, if you are building a custom requestor interface in a Visual Basic form, you can use the strings that these functions return to create a structure similar to the Requester interface in e.Report Designer or e.Report Designer Professional.

Returns The name of the first parameter in the specified parameter group.

An empty string if there are no parameters or if an error occurred.

See also AcWReqGetFirstGroupAcWReqGetNextGroupAcWReqGetNextParameter

C h a p t e r 2 2 , R e q u e s t e r A P I r e f e r e n c e 439

A c W R e q G e t H i d d e n

AcWReqGetHiddenReturns True if parameter is defined as hidden, False if the parameter is not defined as hidden.

Syntax Basic: Function AcWReqGetHidden( fileNumber As Long, parmName As String ) As Boolean

C/C++: VBBOOL AcWReqGetHidden( long fileHandle, LPCTSTR aParmName )

Parameter fileHandleThe handle to the file you opened with AcReqReadFile or AcWReqReadFile.

aParmNameThe name of the parameter whose hidden attribute you want. If you do not know the name of the parameter, use AcWReqGetFirstParameter and AcWReqGetNextParameter to get the parameter name.

Description Use AcWReqGetHidden to find out if a parameter is defined as hidden. If a parameter is hidden, its value can be set only through code. For example, define a path name parameter as hidden to prevent users from changing this value.

Returns True if the parameter is defined as hidden, False otherwise.

See also AcReqSetScopedParameterNameAcWReqGetFirstParameterAcWReqGetNextParameter

AcWReqGetHideTextReturns True if the parameter is defined to display asterisks as users type the value, False if the parameter is defined to display the text that users type.

Syntax Basic: Function AcWReqGetHideText( fileNumber As Long, parmName As String ) As Boolean

C/C++: VBBOOL AcWReqGetHideText( long fileHandle, LPCTSTR aParmName )

Parameter fileHandleThe handle to the file you opened with AcReqReadFile or AcWReqReadFile.

440 P r o g r a m m i n g e . R e p o r t s

A c W R e q G e t N e x t G r o u p

aParmNameThe name of the parameter whose hide text attribute you want. If you do not know the name of the parameter, use AcWReqGetFirstParameter and AcWReqGetNextParameter to get the parameter names.

Description Use AcWReqGetHideText to find out if a parameter is defined to display asterisks or actual text as users type the value. If the hide text attribute is True, Actuate displays asterisks as users type the parameter value.

Returns True if the parameter is defined to display asterisks as users type the value, False if the parameter is defined to display the text that users type.

See also AcReqSetScopedParameterNameAcWReqGetFirstParameterAcWReqGetNextParameter

AcWReqGetNextGroupReturns the name of the next parameter group in the specified .rov file or parameter definition section of the specified .rox file.

Syntax Basic: Function AcWReqGetNextGroup( fileNumber As Long ) As String

C/C++: BSTR AcWReqGetNextGroup( long fileHandle )

Parameter fileHandleThe handle to the file you opened with AcReqReadFile or AcWReqReadFile.

Description Use AcWReqGetNextGroup in conjunction with AcWReqGetFirstGroup, AcWReqGetFirstParameter, and AcWReqGetNextParameter to get information about the organization of parameters in a specified .rov or .rox file. You must call AcWReqGetFirstGroup before calling AcWReqGetNextGroup. For example, if you are building a custom requester interface in a Visual Basic form, you can use the strings that these functions return to create a structure similar to the Requester interface in e.Report Designer or e.Report Designer Professional.

To get the names of all parameter groups, call AcWReqGetNextGroup until it returns an empty string. An empty string indicates that the function has returned the last parameter group.

You can organize parameters into groups for ease of use. For example, CustomerName, CustomerPhone, and Credit_Rank might be parameters in a Customer parameters group, and City and State might be parameters in an Office parameters group.

Returns The name of the next group in the specified .rov or .rox file, if there is another parameter group.

C h a p t e r 2 2 , R e q u e s t e r A P I r e f e r e n c e 441

A c W R e q G e t N e x t P a r a m e t e r

An empty string if there are no more groups or if an error occurred.

See also AcWReqGetFirstGroupAcWReqGetFirstParameterAcWReqGetNextParameter

AcWReqGetNextParameterReturns the name of the next parameter in the specified parameter group.

Syntax Basic: Function AcWReqGetNextParameter( fileNumber As Long, parmGroup As String ) As String

C/C++: BSTR AcWReqGetNextParameter( long fileHandle, LPCTSTR aGroupName )

Parameter fileHandleThe handle to the file you opened with AcReqReadFile or AcWReqReadFile.

aGroupNameThe name of the parameter group in which to find the next parameter. If you do not know the name of parameter group, use AcWReqGetFirstGroup and AcWReqGetNextGroup to get the group name. To get all parameters that belong in any group, specify an empty string for this argument.

Description Use AcWReqGetNextParameter in conjunction with AcWReqGetFirstParameter, AcWReqGetFirstGroup, and AcWReqGetNextGroup to get information about the organization of parameters in a specified .rov or .rox file. You must call AcWReqGetFirstParameter before calling AcWReqGetNextParameter.

For example, if you are building a custom requestor interface in a Visual Basic form, use the strings that these functions return to create a structure similar to the Requester interface in e.Report Designer or e.Report Designer Professional.

To get the names of all parameters in a group, call AcWReqGetNextParameter until it returns an empty string. An empty string indicates that the function has returned the last parameter.

Returns The name of the next parameter in the specified parameter group.

An empty string if there are no more parameters or if an error occurred.

See also AcWReqGetFirstGroupAcWReqGetFirstParameterAcWReqGetNextGroupAcWReqGetNextParameter

442 P r o g r a m m i n g e . R e p o r t s

A c W R e q G e t P a r m T y p e

AcWReqGetParmTypeReturns the data type of the specified parameter as a string.

Syntax Basic: Function AcWReqGetParmType( fileNumber As Long, parmName As String ) As String

C/C++: BSTR AcWReqGetParmType( long fileHandle, LPCTSTR aParmName )

Parameter fileHandleThe handle to the file you opened with AcReqReadFile or AcWReqReadFile.

aParmNameThe name of the parameter whose data type you want. If you do not know the name of the parameter, use AcWReqGetFirstParameter and AcWReqGetNextParameter to get the parameter name.

Description Use AcWReqGetParmType to find out the parameter’s data type. You can use this information to determine how to set a parameter value. You can also use this information to determine which function to use to get a parameter’s default or current value.

You set parameter values with functions such as AWcReqSetValueDate and AcWReqSetValueString. You get the default values for parameters with functions such as AcWReqGetDefaultValueDate and AcWeqGetDefaultValueString. You get a parameter’s current value with functions such as AcWReqGetValueDate and AcReqGetValueString.

Returns The data type of the specified parameter as a string.

See also AcReqGetTypeAcReqSetScopedParameterNameAcWReqGetFirstParameterAcWReqGetNextParameter

AcWReqGetRequiredReturns True if the parameter is defined as required, returns False if the parameter is defined as optional.

Syntax Basic: Function AcWReqGetRequired( fileNumber As Long, parmName As String ) As Boolean

C/C++: VBBOOL AcWReqGetRequired( long fileHandle, LPCTSTR aParmName )

C h a p t e r 2 2 , R e q u e s t e r A P I r e f e r e n c e 443

A c W R e q G e t V a l u e C u r r e n c y

Parameter fileHandleThe handle to the file you opened with AcReqReadFile or AcWReqReadFile.

aParmNameThe name of the parameter whose required attribute you want. If you do not know the name of the parameter, use AcWReqGetFirstParameter and AcWReqGetNextParameter to get the parameter name.

Description Use AcWReqGetRequired to find out if a parameter was defined as required or optional. If a parameter is required, Actuate generates the report only if a value for the parameter is provided.

Use the boolean value that AcWReqGetRequired returns to determine if you need to set a parameter value before generating a report with AcWReqGenerateReport. You set parameter values with functions such as AcWReqSetValueString and AcWReqSetValueDate.

Returns True if the parameter is required to generate the report, False if the parameter is optional.

See also AcReqSetScopedParameterNameAcWReqGetFirstParameterAcWReqGetNextParameter

AcWReqGetValueCurrencyReturns the current value of the specified parameter as a currency.

Syntax Basic: Function AcWReqGetValueCurrency( fileNumber As Long, parmName As String ) As Currency

C/C++: REQCYTYPE AcWReqGetValueCurrency( long fileHandle, LPCTSTR aParmName )

Parameter fileHandleThe handle to the file you opened with AcReqReadFile or AcWReqReadFile.

aParmNameThe name of the parameter whose current value you want. If you do not know the name of the parameter, use AcWReqGetFirstParameter and AcWReqGetNextParameter to get the parameter name.

Description Use AcWReqGetValueCurrency to get the current value of a parameter as a currency. The current value is the last value entered in the .rov file. If accessing an .rox file, the current value is the default value defined at design time.

When calling AcWReqGetValueCurrency, the parameter you specify as an argument must be of type Currency. If you specify a parameter of any other

444 P r o g r a m m i n g e . R e p o r t s

A c W R e q G e t V a l u e D a t e

type, AcWReqGetValueCurrency returns the default value for that type. To pass an argument of any type, use AcWReqGetValueStr. AcReqGetValueStr always returns a string.

Use AcWReqGetParmType to check the data type of a parameter.

In C/C++, the structure REQCYTYPE, stores up to 64 bits. To retrieve currency values that require a 96-bit structure, use AcWReqGetValueString function to return the value, then convert the string value to a currency value within your application. If you call AcWReqGetValueCurrency to return a currency value larger than 64 bits, the GetError function returns an error message number.

Returns The current value of the specified parameter as a currency.

See also AcReqSetScopedParameterNameAcWReqGetFirstParameterAcWReqGetNextParameterAcWReqGetParmTypeAcWReqGetValueStr

AcWReqGetValueDateReturns the current value of the specified parameter as a date.

Syntax Basic: Function AcWReqGetValueDate( fileNumber As Long, parmName As String ) As Date

C/C++: double AcWReqGetValueDate( long fileHandle, LPCTSTR aParmName )

Parameter fileHandleThe handle to the file you opened with AcReqReadFile or AcWReqReadFile.

aParmNameThe name of the parameter whose current value you want. If you do not know the name of the parameter, use AcWReqGetFirstParameter and AcWReqGetNextParameter to get the parameter names.

Description Use AcWReqGetValueDate to get the current value of a parameter as a date. The current value is the last value entered in the .rov file. If accessing an .rox file, the current value is the default value defined at design time.

When calling AcWReqGetValueDate, the parameter you specify as an argument must be of type Date. If you specify a parameter of any other type, AcWReqGetValueDate returns the default value for that type. To pass an argument of any type, use AcWReqGetValueStr. AcWReqGetValueStr always returns a string.

Use AcWReqGetParmType to check the data type of a parameter.

C h a p t e r 2 2 , R e q u e s t e r A P I r e f e r e n c e 445

A c W R e q G e t V a l u e D o u b l e

Returns The current value of the specified parameter as a date.

Example The following example shows how to work with dates expressed as C++ doubles:

int fileNumber; double inDate, outDate; COleDateTime oleDate( 1967, 12, 6, 0, 0, 0 ); // y m d h m s inDate = oleDate; fileNumber = AcReqReadFile( szSourceRox ); outDate = AcWReqGetValueDate(fileNumber, "aDate"); oleDate = outDate; AcWReqSetValueDate( fileNumber, "aDate", inDate ); AcReqCloseFile( fileNumber );

See also AcReqSetScopedParameterNameAcWReqGetFirstParameterAcWReqGetNextParameterAcWReqGetParmTypeAcWReqGetValueStr

AcWReqGetValueDoubleReturns the current value of the specified parameter as a double.

Syntax Basic: Function AcWReqGetValueDouble( fileNumber As Long, parmName As String ) As Double

C/C++: double AcWReqGetValueDouble( long fileHandle, LPCTSTR aParmName )

Parameter fileHandleThe handle to the file you opened with AcReqReadFile or AcWReqReadFile.

aParmNameThe name of the parameter whose current value you want. If you do not know the name of the parameter, use AcWReqGetFirstParameter and AcWReqGetNextParameter to get the parameter name.

Description Use AcWReqGetValueDouble to get the current value of a parameter as a double. The current value is the value last entered in the .rov file. If you are accessing an .rox file, the current value is the default value defined at design time.

446 P r o g r a m m i n g e . R e p o r t s

A c W R e q G e t V a l u e I n t e g e r

When calling AcWReqGetValueDouble, the parameter you specify as an argument must be of type Double. If you specify a parameter of any other type, AcWReqGetValueDouble returns the default value for that type. To pass an argument of any type, use AcWReqGetValueStr. AcReqGetValueStr always returns a string.

Use AcWReqGetParmType to check the data type of a parameter.

Returns The current value of the specified parameter as a double.

See also AcReqSetScopedParameterNameAcWReqGetFirstParameterAcWReqGetNextParameterAcWReqGetParmTypeAcWReqGetValueStr

AcWReqGetValueIntegerReturns the current value of the specified parameter as an integer.

Syntax Basic: Function AcWReqGetValueInteger( fileNumber As Long, parmName As String ) As Integer

C/C++: long AcWReqGetValueInteger( long fileHandle, LPCTSTR aParmName )

Parameter fileHandleThe handle to the file you opened with AcReqReadFile or AcWReqReadFile.

aParmNameThe name of the parameter whose current value you want. If you do not know the name of the parameter, use AcWReqGetFirstParameter and AcWReqGetNextParameter to get the parameter name.

Description Use AcWReqGetValueInteger to get the current value of a parameter as an integer. The current value is the value last entered in the .rov file. If you are accessing an .rox file, the current value is the default value defined by the programmer at design time.

When calling AcWReqGetValueInteger, the parameter you specify as an argument must be of type Integer. If you specify a parameter of any other type, AcWReqGetValueInteger returns the default value for that type. To pass an argument of any type, use AcWReqGetValueStr. AcReqGetValueStr always returns a string.

Use AcWReqGetParmType to check the data type of a parameter.

Returns The current value of the specified parameter as an integer.

C h a p t e r 2 2 , R e q u e s t e r A P I r e f e r e n c e 447

A c W R e q G e t V a l u e S t r

See also AcReqSetScopedParameterNameAcWReqGetFirstParameterAcWReqGetNextParameterAcWReqGetParmTypeAcWReqGetValueStr

AcWReqGetValueStrReturns the current value of the specified parameter as a string.

Syntax Basic: Function AcWReqGetValueStr( fileNumber As Long, parmName As String ) As String

C/C++: BSTR AcWReqGetValueStr( long fileHandle, LPCTSTR aParmName )

Parameter fileHandleThe handle to the file you opened with AcReqReadFile or AcWReqReadFile.

aParmNameThe name of the parameter whose current value you want. If you do not know the name of the parameter, use AcWReqGetFirstParameter and AcWReqGetNextParameter to get the parameter names.

Description Use AcWReqGetValueStr to get the current value of a parameter as a string. The parameter you specify as an argument can be of any type. The current value is the value last entered in the .rov file. If you are accessing an .rox file, the current value is the default value defined by the programmer at design time.

To get the current value as the type with which the parameter was declared, use type-specific functions such as AcWReqGetValueInteger or AcWReqGetValueCurrency.

Returns The current value of the specified parameter as a string.

See also AcReqSetScopedParameterNameAcWReqGetFirstParameterAcWReqGetNextParameterAcWReqGetParmTypeAcWReqGetValueCurrencyAcWReqGetValueDateAcWReqGetValueDoubleAcWReqGetValueIntegerAcWReqGetValueString

448 P r o g r a m m i n g e . R e p o r t s

A c W R e q G e t V a l u e S t r i n g

AcWReqGetValueStringReturns the current value of the specified parameter as a string.

Syntax Basic: Function AcWReqGetValueString( fileNumber As Long, parmName As String ) As String

C/C++: BSTR AcWReqGetValueString( long fileHandle, LPCTSTR aParmName )

Parameter fileHandleThe handle to the file you opened with AcReqReadFile or AcWReqReadFile.

aParmNameThe name of the parameter whose current value you want. If you do not know the name of the parameter, use AcWReqGetFirstParameter and AcWReqGetNextParameter to get the parameter name.

Description Use AcWReqGetValueString to get the current value of a parameter as a string. The current value is the value last entered in the .rov file. If you are accessing an .rox file, the current value is the default value defined by the programmer at design time.

When calling AcWReqGetValueString, the parameter you specify as an argument must be of type String. If you specify a parameter of any other type, AcWReqGetValueString returns the default value for that type. To pass an argument of any type, use AcWReqGetValueStr. AcReqGetValueStr always returns a string.

Use AcwReqGetParmType to check the data type of a parameter.

Returns The default value of the specified parameter as a string.

See also AcReqSetScopedParameterNameAcWReqGetFirstParameterAcWReqGetNextParameterAcWReqGetParmTypeAcWReqGetDefaultValueStr

AcWReqGetVersionNumberReturns Actuate requester API version information as a string.

Syntax Basic: Function AcWReqGetVersionNumber( ) As String

C/C++: BSTR AcWReqGetVersionNumber( )

C h a p t e r 2 2 , R e q u e s t e r A P I r e f e r e n c e 449

A c W R e q H a s D e f a u l t V a l u e

Description Use AcReqGetVersionNumber to get the version information of the requester API.

Returns Version information as a string in the following format:

r.v.m.p - nnnn

The following table describes the values in the string.

For example, when used with Actuate 7, AcReqGetVersionNumber returns the following string:

7.0.0.0 - 2172

AcWReqHasDefaultValueReturns True if a default value was assigned to a specified parameter.

Syntax Basic: Function AcWReqHasDefaultValue( fileNumber As Long, parmName As String ) As Boolean

C/C++: VBBOOL AcWReqHasDefaultValue( long fileNumber, LPCTSTR aParmName )

Parameter fileNumberThe file number of the file you opened with AcReqReadFile or AcWReqReadFile.

aParmNameThe name of the parameter whose default value you want. If you do not know the name of the parameter, use AcWReqGetFirstParameter and AcWReqGetNextParameter to get the parameter name.

Description Use AcWReqHasDefaultValue to determine if a default value was assigned to a parameter. The parameter you specify as an argument can be of any type. When you call a function such as AcWReqGetValueInteger to return the default value of a parameter, AcWReqGetValueInteger returns zero if no default value is set or if the default is set to zero. For this reason, always call AcWReqHasDefaultValue to determine whether a default value is set, then call AcWReqGetValueInteger to the value.

Number Description

r Release number

v Version number

m Maintenance version

p Patch number

nnnn Build number

450 P r o g r a m m i n g e . R e p o r t s

A c W R e q P r i n t R e p o r t

Returns True if a default value was assigned, False otherwise.

See also AcReqSetScopedParameterNameAcWReqGetDefaultValueCurrencyAcWReqGetDefaultValueDateAcWReqGetDefaultValueDoubleAcWReqGetDefaultValueIntegerAcWReqGetDefaultValueStringAcWReqGetFirstParameterAcWReqGetNextParameterAcWReqGetParmType

AcWReqPrintReportPrints the specified report.

Syntax Basic: Function AcWReqPrintReport( filename As String, options As Long ) As Long

C/C++: long AcWReqPrintReport( LPCTSTR aFileName, long options )

Parameter aFileNameThe name of the report to print. Specify the full path name if the file is not in the current directory.

If the file resides on a server, use the following format:

<service>:[//<server>]/<path>/<filename>[;<version>]

For information about specifying server file names, see Chapter 2, “Specifying an iServer file name—Requester API.”

optionsA set of constants you can use to specify how the End User Desktop application runs. When specifying multiple options, use the plus (+) character between the options. The following table lists and describes the constants.

Constant Description

AC_REQ_LAUNCH_ALWAYS Runs a new instance of an End User Desktop application to print the report.

AC_REQ_PRINT Prints the generated report.

C h a p t e r 2 2 , R e q u e s t e r A P I r e f e r e n c e 451

A c W R e q P r i n t R e p o r t

The following examples show how to specify options with AcWReqPrintReport:

AcWReqPrintReport( "detail.roi", AC_REQ_HIDE )AcWReqPrintReport( "detail.roi", AC_REQ_LAUNCH_ALWAYS+AC_REQ_HIDE )

The first call passes the name of the document file and a constant that represents a message to hide the End User Desktop application while it prints the report. The second call passes the name of the document file and constants that represent a message to run a new instance of the End User Desktop application but to hide it while it prints the report.

Description Use AcWReqPrintReport to print an existing report on a local system. To print a report immediately after you generate it with AcWReqGenerateReport, use the AC_REQ_PRINT option in AcWReqGenerateReport.

If you want to change the printer setup before printing the report, use the printer-related functions such as , AcWReqSetPrinterName, AcReqSetPrinterNumberCopies, and AcReqSetPrinterOrientation.

Returns For reports generated synchronously, zero when the report prints successfully. Use AcReqGetError to check for errors for reports generated asynchronously.

Non-zero if the report did not print.

See also AcReqSetPrinterCollateAcReqSetPrinterColorAcReqSetPrinterDuplexAcReqSetPrinterNumberCopiesAcReqSetPrinterOrientationAcReqSetPrinterPaperSizeAcReqSetPrinterScaleAcReqSetPrinterFormNameAcWReqSetPrinterName

AC_REQ_ASYNC Runs this process asynchronously. The function returns immediately and the report prints in the background. If not specified, the function returns after the report prints.

AC_REQ_HIDE Does not display the End User Desktop application while it prints the report.

AC_REQ_STAY_OPEN Keeps the End User Desktop application open after it prints the report. This option is ignored if the report is printed in the current instance of the End User Desktop.

Constant Description

452 P r o g r a m m i n g e . R e p o r t s

A c W R e q R e a d F i l e

AcWReqReadFileOpens a parameter value (.rov) file or a report executable (.rox) file.

Syntax Basic: Function AcWReqReadFile( filename As String ) As Long

C/C++: long AcWReqReadFile( LPCTSTR aFileName )

Parameter aFileNameThe name of the .rov or .rox file to open. Specify the full path name if the file is not in the current directory.

If the file resides on a server, use the following format:

<service>:[//<server>]/<path>/<filename>[;<version>]

For information about specifying server file names, see Chapter 2, “Specifying an iServer file name—Requester API.”

Description Use AcWReqReadFile to open an .rov or .rox file to change or get information about parameter values before generating a report. The .rov file contains parameter values that users set when they run a report. The .rox file contains the parameter definitions. If you open an .rox, the default values assigned to the parameters at design time are read into memory.

You can call AcWReqReadFile multiple times to open multiple files. Each file is assigned a unique file number.

Returns The file number of the open file.

-1 if the user does not have permission to open the file.

AcWReqSetEUDTPathSpecifies the location of the End User Desktop application to use for report generation or the location of the Viewer application to use for report viewing.

Syntax Basic: Sub AcWReqSetEUDTPath( pathName As String )

C/C++: void AcWReqSetEUDTPath( LPCTSTR aPath )

Parameter aPathThe location of the End User Desktop or Viewer application to run.

The following examples specify the End User Desktop and Viewer application to run:

AcWReqSetEUDTPath( "C:\Program Files\Actuate7\Eudt\Bin\Runview.exe" )AcWReqSetEUDTPath( "C:\Program Files\Actuate7\Viewer\Bin\Viewer.exe" )

C h a p t e r 2 2 , R e q u e s t e r A P I r e f e r e n c e 453

A c W R e q S e t P r i n t e r N a m e

Description Use AcWReqSetEUDTPath to specify the location of the End User Desktop to use for report generation. If generating reports on iServer, do not set this path. You need to call AcReqSetEUDTPath in the following situations:

■ If you run the End User Desktop remotely, for example, from a Visual Basic application.

■ If you do not specify the AC_REQ_LOCAL option with AcWReqGenerateReport. The AC_REQ_LOCAL option specifies that the report be generated in the current instance of e.Report Designer, e.Report Designer Professional, or End User Desktop.

If opening a report for viewing, you can use AcWReqSetEUDTPath to specify which End User Desktop or Viewer application displays the report.

See also AcWReqGenerateReportAcWReqViewReportAcReqSelectClient

AcWReqSetPrinterNameSpecifies the printer to use.

Syntax Basic: Sub AcWReqSetPrinterName( printerName As String )

C/C++: void AcWReqSetPrinterName( LPCTSTR printerName )

Parameter printerNameThe name of the printer to use.

Description Before sending a print job, use AcWReqSetPrinterName to specify a printer different than the default one. If you want revert to the system’s default printer after printing a job to the printer you specify with this function, call AcReqSetDefaultPrinter. To print a report, use AcWReqPrintReport.

See also AcReqSetDefaultPrinterAcWReqPrintReport

AcWReqSetValueCurrencySets the value of the specified parameter as a currency.

Syntax Basic: Sub AcWReqSetValueCurrency( fileNumber As Long, parmName As String, value As Currency )

C/C++: void AcWReqSetValueCurrency( long fileHandle, LPCTSTR aParmName, REQCYTYPE value )

454 P r o g r a m m i n g e . R e p o r t s

A c W R e q S e t V a l u e D a t e

Parameter fileHandleThe handle to the file you opened with AcReqReadFile or AcWReqReadFile.

aParmNameThe name of the parameter whose value you want to set. If you do not know the names of the parameters, use AcWReqGetFirstParameter and AcWReqGetNextParameter to get the parameter names.

valueThe currency value to assign to the parameter.

Description Use AcWReqSetValueCurrency to assign a currency value to a parameter. The parameter whose value you want to set must be of type Currency. Use AcWReqGetParmType to check the data type of a parameter before setting its value.

In C/C++, the structure REQCYTYPE, stores up to 64 bits. If you need to assign a currency value to a parameter that requires a 96-bit structure, convert the currency value to a string value. Then call AcWReqSetValueString to assign the value. If you call AcWReqSetValueCurrency to assign a currency value larger than 64 bits, GetError returns an error number.

See also AcReqSetScopedParameterNameAcWReqGetFirstParameterAcWReqGetNextParameterAcWReqGetParmType

AcWReqSetValueDateSets the value of the specified parameter as a date.

Syntax Basic: Sub AcWReqSetValueDate( fileNumber As Long, parmName As String, value As Date )

C/C++: void AcWReqSetValueDate( long fileHandle, LPCTSTR aParmName, double value )

Parameter fileHandleThe handle to the file you opened with AcReqReadFile or AcWReqReadFile.

aParmNameThe name of the parameter whose value you want to set. If you do not know the names of the parameters, use AcWReqGetFirstParameter and AcWReqGetNextParameter to get the parameter names.

C h a p t e r 2 2 , R e q u e s t e r A P I r e f e r e n c e 455

A c W R e q S e t V a l u e D o u b l e

valueThe date value to assign to the parameter. The date value is a floating point number containing the number of days from midnight on December 30, 1899. Hours are shown as a fraction of a day. For example, the value for December 30, 1899 is 0.0. The date value for January 1, 1900 at 6 A.M. is 2.25.

Description Use AcWReqSetValueDate to assign a date value to a parameter. The parameter whose value you want to set must be of type Date. Use AcWReqGetParmType to check the data type of a parameter before setting its value. Ensure that the date value passed to AcWReqSetValueDate is a floating point number expressed using the format described for the value parameter. On Windows servers, you can call the C++ function, COleDateTime, to convert the date for AcWReqSetValueDate.

Example The following example shows how to work with dates expressed as C++ doubles on Windows NT:

int fileNumber;double inDate, outDate;COleDateTime oleDate( 1967, 12, 6, 0, 0, 0 ); // y m d h m sinDate = oleDate;fileNumber = AcWReqReadFile( szSourceRox );outDate = AcWReqGetDefaultValueDate(fileNumber, "aDate");oleDate = outDate;AcWReqSetValueDate( fileNumber, "aDate", inDate );AcReqCloseFile( fileNumber );

See also AcReqSetScopedParameterNameAcWReqGetFirstParameterAcWReqGetNextParameterAcWReqGetParmType

AcWReqSetValueDoubleSets the value of the specified parameter as a double.

Syntax Basic: Sub AcWReqSetValueDouble( fileNumber As Long, parmName As String, value As Double )

C/C++: void AcWReqSetValueDouble( long fileHandle, LPCTSTR aParmName, double value )

Parameter fileHandleThe handle to the file you opened with AcReqReadFile or AcWReqReadFile.

aParmNamethe names of the parameters, use AcWReqGetFirstParameter and AcWReqGetNextParameter to get the parameter names.

456 P r o g r a m m i n g e . R e p o r t s

A c W R e q S e t V a l u e I n t e g e r

valueThe double value to assign to the parameter.

Description Use AcWReqSetValueDouble to assign a double value to a parameter. The parameter whose value you want to set must be of type Double. Use AcWReqGetParmType to check the data type of a parameter before setting its value.

For an example of how to set dates from C++ as doubles, see Chapter 2, “Using the Requester in a C++ application.”

See also AcReqSetScopedParameterNameAcWReqGetFirstParameterAcWReqGetNextParameterAcWReqGetParmType

AcWReqSetValueIntegerSets the value of the specified parameter as an integer.

Syntax Basic: Sub AcWReqSetValueInteger( fileNumber As Long, parmName As String, value As Integer )

C/C++: void AcWReqSetValueInteger( long fileHandle, LPCTSTR aParmName, long value )

Parameter fileHandleThe handle to the file you opened with AcReqReadFile or AcWReqReadFile.

aParmNameThe name of the parameter whose value you want to set. If you do not know the names of the parameters, use AcWReqGetFirstParameter and AcWReqGetNextParameter to get the parameter names.

valueThe integer value to assign to the parameter.

Description Use AcWReqSetValueInteger to assign an integer value to a parameter. The parameter whose value you want to set must be of type Integer. Use AcReqGetParmType to check the data type of a parameter before setting its value.

See also AcReqSetScopedParameterNameAcWReqGetFirstParameterAcWReqGetNextParameterAcWReqGetParmType

C h a p t e r 2 2 , R e q u e s t e r A P I r e f e r e n c e 457

A c W R e q S e t V a l u e S t r i n g

AcWReqSetValueStringSets the value of the specified parameter as a string.

Syntax Basic: Sub AcWReqSetValueString( fileNumber As Long, parmName As String, value As String )

C/C++: void AcWReqSetValueString( long fileHandle, LPCTSTR aParmName, LPCTSTR value )

Parameter fileHandleThe handle to the file you opened with AcReqReadFile or AcWReqReadFile.

AParmNameThe name of the parameter whose value you want to set. If you do not know the names of the parameters, use AcWReqGetFirstParameter and AcWReqGetNextParameter to get the parameter names.

valueThe string value to assign to the parameter.

Description Use AcWReqSetValueString to assign a string value to a parameter. The parameter whose value you want to set must be of type String. Use AcReqGetParmType to check the data type of a parameter before setting its value.

See also AcReqSetScopedParameterNameAcWReqGetFirstParameterAcWReqGetNextParameterAcWReqGetParmType

AcWReqViewReportDisplays the specified report (.roi).

Syntax Basic: Function AcWReqViewReport( filename As String, options As Long ) As Long

C/C++: long AcWReqViewReport( LPCTSTR aFileName, long options )

Parameter aFileNameThe name of the report (.roi) to display. Specify the full path name if the file is not in the current directory.

If the file resides on a server, use the following format:

<service>:[//<server>]/<path>/<filename>[;<version>]

458 P r o g r a m m i n g e . R e p o r t s

A c W R e q V i e w R e p o r t

For information about specifying server file names, see Chapter 2, “Specifying an iServer file name—Requester API.”

optionsA set of constants you can use to specify how the End User Desktop application runs. When specifying multiple options, use the plus (+) character between the options. The following table lists and describes the constants.

The following examples show how to specify options with AcWReqViewReport:

AcWReqViewReport("detail.roi", AC_REQ_LAUNCH_ALWAYS)AcWReqViewReport("detail.roi",

AC_REQ_LAUNCH_ALWAYS+AC_REQ_ASYNC)

The first call passes the name of the document file and a constant that represents a message to run a new instance of the End User Desktop. The second call passes the name of the document file and constants that represent a message to run a new instance of the End User Desktop and to run the request asynchronously.

Description Use AcWReqViewReport to display an existing report. To display a report immediately after you generate it with AcWReqGenerateReport, use the AC_REQ_VIEW option in AcWReqGenerateReport.

Returns 0 if the report was displayed.

Any number other than zero if the report was not displayed.

See also AcWReqGenerateReport

Constant Description

AC_REQ_LAUNCH_ALWAYS Runs a new instance of an End User Desktop application to display the report.

AC_REQ_LOCAL Displays the report in the current instance of e.Report Designer, e.Report Designer Professional, or End User Desktop.

AC_REQ_VIEW Displays the generated report.

AC_REQ_ASYNC Runs this process asynchronously. The function returns immediately and the report displays in the background. If not specified, the function returns after the report displays.

C h a p t e r 2 2 , R e q u e s t e r A P I r e f e r e n c e 459

A c W R e q W r i t e F i l e

AcWReqWriteFileCreates a parameter value (.rov) file.

Syntax Basic: Sub AcWReqWriteFile( fileNumber As Long, filename As String )

C/C++: void AcWReqWriteFile( long fileHandle, LPCTSTR aFileName )

Parameter fileHandleThe handle to the file you opened with AcReqReadFile or AcWReqReadFile.

aFileNameThe name of the.rov file to create. The file name must include the.rov filename extension.

If the file resides on a server, use the following format:

<service>:[//<server>]/<path>/<filename>[;<version>]

For information about specifying server file names, see Chapter 2, “Specifying an iServer file name—Requester API.”

Description Use AcWReqWriteFile to write the parameter values to an .rov file. you set the parameter values using functions such as AcWReqSetValueString or AcWReqSetValueInteger. Before calling AcWReqWriteFile or any of the functions to change or inspect parameter values, you must call AcWReqReadFile to open the appropriate .rox or .rov file.

After creating the .rov file, you can call AcWReqGenerateReport to create a report from that .rov file.

See also AcWReqReadFile

Undocumented functionsThe following functions are undocumented and are intended for internal use only. Actuate reserves the right to change these functions without notice and does not recommend their use for any purpose.

AcReqAddToCacheAcReqDropFromCacheAcReqGetCacheFileAcReqGetPrinterCapabilitiesAcReqInfo

460 P r o g r a m m i n g e . R e p o r t s

A c W R e q W r i t e F i l e

C h a p t e r 2 3 , S e a r c h e x t e n s i o n A P I u s e r g u i d e 461

C h a p t e r

Chapter 23Search extension APIuser guide

This chapter contains the following topics:

■ About the search extension API

■ Search extension API functions by programming task

■ Developing a search extension

■ Installing a custom search extension

462 P r o g r a m m i n g e . R e p o r t s

About the search extension APIActuate offers prebuilt search extensions for the third party applications such as Microsoft Excel, CorVu Graphical Analysis Module, and Brio Technology BrioQuery. Using the search extension API, you can add custom extensions for additional third party applications or build custom analysis tools.

Actuate products implement this functionality through the search extension API. As users configure and launch search operations from the desktop, Actuate products call functions in the search extension API. A custom application that implements the search extension functions tailors the search for a particular third party analysis tool. You cannot initiate a search from the API.

The search extension API supports the following fundamental use scenarios:

■ Extracting the results of a search and displaying them in another tool

■ Recording a set of searches and extractions run on a regular basis

■ Running a saved search and extracting the data to an external application

The search extension API works in conjunction with e.Report Designer, e.Report Designer Professional, End User Desktop, and ActiveX controls to provide two features:

■ Store ReportQuery definitions in the local file system

■ Extract and transfer the result from a ReportQuery to external applications

Search extension API functions by programming task

This section categorizes and lists the search extension API functions by the following general programming tasks:

■ Writing startup and cleanup code

■ Setting search parameters

■ Processing search results

For a complete description of each function, see Chapter 24, “Search extension API reference.”

C h a p t e r 2 3 , S e a r c h e x t e n s i o n A P I u s e r g u i d e 463

Writing startup and cleanup codeThe following table lists the functions for starting and ending a search session.

GetName and Open are startup operations called at the beginning of the search process. Close is called when the search is complete.

Setting search parametersThe following table lists the functions for working with search parameters.

InputParameters is called when the user clicks Options on the Search Extract Option dialog. Actuate calls GetParameters when it saves a search definition and SetParameters when it reads a search definition.

Actuate stores search parameters, including the extension-specific parameters, in an ROS file. The default directories for search definitions and search extensions are SrchDef and SrchExt, respectively. These directories are at the same level as the product directory, usually C:\Program Files\Actuate7. You can change the default directories by adding two entries to the Windows registry:

HKEY_CURRENT_USER/Software/Actuate/SearchDefDir

HKEY_CURRENT_USER/Software/Actuate/SearchExtDir

Each registry entry is a new string value that contains the fully qualified path to the search definition or extension folder. These registry entries are optional

Programming task API function

Close files or APIs and perform other cleanup operations. This function is required.

Close

Specify a user friendly name for the search extension. This function is required.

GetName

Open files or APIs used in the search process. This function is required.

Open

Programming task API function

Specify the extension-specific parameters for the search operation. This function is optional.

GetParameters

Collect extension-specific parameters from the user. This function is optional.

InputParameters

Pass extension-specific search definition parameters to the search extension DLL. This function is optional.

SetParameters

464 P r o g r a m m i n g e . R e p o r t s

and are not set when the product is installed. Make these additions carefully because improper changes to the registry can render your software or computer inoperative. For more information about working with the Windows registry, refer to Windows help.

Processing search resultsThe following table lists the functions for processing search results in Actuate 7.

GetColumnDelimiter and IncludeHeader define data format and are called before the search. PutRow transfers the search results to the extension.

Developing a search extensionThe Actuate 7 search extension API is a C++ API implemented as a standard Windows DLL. Developing a custom search extension includes the following tasks:

■ Write search extension code

■ Create a definition file for the exports

■ Create a header file defining the DLL exports

■ Compile the code into a DLL

Writing search extension codeWrite your search extension application as follows:

1 Provide a name for the extension.

The name GetName returned appears in the Search Extract Option dialog as one of the available extensions.

Programming task API function

Specify the delimiter character that separates columns of search data. This function is required.

GetColumnDelimiter

Specify whether or not the search data should include a header. This function is optional.

IncludeHeader

Transfer each row as it is created during the search process. This function is required.

PutRow

Retrieve the data type of each column in a row. SetDataTypeInfo

C h a p t e r 2 3 , S e a r c h e x t e n s i o n A P I u s e r g u i d e 465

2 Implement startup tasks.

Startup code, implemented in the Open function, typically opens files on the local file system.

3 Optionally, process search parameters.

If your extension requires extension-specific parameters, develop code for handling those parameters. To do this, use GetParameters, SetParameters, and InputParameters.

4 Set up search settings.

Specify the column delimiter character and specify handling of header information using GetColumnDelimiter and IncludeHeader.

5 Process the search results.

Process the search results using PutRow. Processing may include reformatting for third party applications.

6 Implement cleanup tasks.

Close any open files and perform any necessary cleanup operations using the Close function.

You must implement all functions in the interface except for the functions related to parameters.

Creating a definition fileThe following lines of code are from a definition file used during the link process of a specific search extension .dll file. The entries in the left column name each function. The actual function names are in the right column. Actuate uses this name mapping to find the functions for a specific implementation of the search extension API:

EXPORTSGetName =ExcelGetNameGetParameters =ExcelGetParametersSetParameters =ExcelSetParametersInputParameters =ExcelInputParametersGetColumnDelimiter =ExcelGetDelimiterIncludeHeader =ExcelIncludeHeaderOpen =ExcelOpenClose =ExcelClosePutRow =ExcelPutRow

466 P r o g r a m m i n g e . R e p o r t s

Creating a header fileThe following lines of code are from an include file for a specific implementation of a search extension. The function names match the names in the right column in the DEF file:

#define DllExport extern __declspec( dllexport )DllExport const char* FAR PASCAL ExcelGetName();DllExport const char* FAR PASCAL ExcelGetParameters();DllExport void FAR PASCAL ExcelSetParameters( const char* parms );DllExport BOOL FAR PASCAL ExcelInputParameters();DllExport const char* FAR PASCAL ExcelGetDelimiter();DllExport BOOL FAR PASCAL ExcelIncludeHeader();DllExport BOOL FAR PASCAL ExcelOpen();DllExport BOOL FAR PASCAL ExcelClose();DllExport BOOL FAR PASCAL ExcelPutRow( long rowIdx, const char* row );

Compiling the codeCompile the Actuate 7 search extension with Visual C++ 6.0.

Installing a custom search extensionA client station using a search extension API requires the following components:

■ Actuate e.Report Designer, e.Report Designer Professional, End User Desktop, or ActiveX controls

■ Custom DLL that implements the search extension API

You can use the Actuate Viewer to display reports for your API application if you set up the client station as follows:

1 Install e.Report Designer, e.Report Designer Professional, End User Desktop, or ActiveX controls.

2 Copy the search extension DLL to the search extension directory. The default search extension directory is SrchExt, located in the directory where you installed the Actuate product. The default install directory is C:\Program Files\Actuate7\srchext. You can override this location by setting the registry value HKEY_CURRENT_USER/Actuate 7/Searchextdir to a new directory.

Actuate detects your DLL and presents it as an option in the Search Extract Option dialog.

C h a p t e r 2 4 , S e a r c h e x t e n s i o n A P I r e f e r e n c e 467

C h a p t e r

Chapter 24Search extension APIreference

This reference alphabetically lists the functions in the search extension API. For a conceptual discussion of the search extension API, see Chapter 23, “Search extension API user guide.”

The function descriptions typically explain the code that you must write to implement the function rather than prebuilt functionality. You must implement all functions marked as required.

468 P r o g r a m m i n g e . R e p o r t s

C l o s e

CloseCloses files or APIs and performs other cleanup operations. This function is required.

Syntax BOOL Close(long event)

Parameter eventThe reason for closing the search extension:

0 - the search completed normally1 - the search was stopped by the user2 - the search was stopped due to the application closing3 - the search was not started

Description Actuate calls Close when the search extension is closing and passes a parameter indicating the event that terminated the search. For normal completion, the extension must implement code to close files, APIs, and other cleanup operations.

For all other cases, the results of the search are missing or incomplete. The extension must implement cleanup code, but should not launch a third-party application or create a partial report.

Returns True if the operation is successful, False otherwise.

See also Open

GetColumnDelimiterSpecifies the delimiter character that separates columns of search data. This function is required.

Syntax const char* GetColumnDelimiter( )

Description This function returns the delimiter Actuate uses when formatting a row. Actuate passes the formatted row to the extension in PutRow. The extension can modify the row delimiter before passing it on to the external application, when necessary.

Returns A null-terminated character string that defines the row delimiter.

See also PutRow

C h a p t e r 2 4 , S e a r c h e x t e n s i o n A P I r e f e r e n c e 469

G e t N a m e

GetNameSpecifies a user-friendly name for the search extension. This function is required.

Syntax const char* GetName( )

Description This function returns the name that Actuate uses to identify the extension. Actuate displays this name in the External Applications combo box on the Search options dialog.

Returns A character string that represents the name of the extension.

GetParametersSpecifies the extension-specific parameters for the search operation.

Syntax const char* GetParameters( )

Description This function returns a string that specifies the extension-specific parameters for the search operation. This information is typically the options collected during the InputParameters call. This function works in conjunction with SetParameters to allow the extension to store and retrieve information from the search definition file. Actuate returns this string to the extension application through the SetParameter argument. Actuate calls GetParameters before it saves the search definition file.

Returns A null-terminated character string containing search parameters. The search extension applications defines the content and format.

The default value if GetParameters is not implemented is an empty string.

See also InputParametersSetParameters

IncludeHeaderSpecifies whether or not the search data should include a header.

Syntax BOOL IncludeHeader( )

Description This function returns a Boolean indicating if the first row sent to the extension should be a header containing the names of the columns separated with the column delimiter.

470 P r o g r a m m i n g e . R e p o r t s

I n p u t P a r a m e t e r s

Returns True to include headers or False to exclude headers.

The default value is True if the function is not implemented.

See also PutRow

InputParametersCollects extension-specific parameters from the user.

Syntax BOOL InputParameters( )

Description Actuate calls this function when the user clicks Options in the Search Extract Option dialog. Typically, the search extension application opens a dialog that prompts the user for additional extension-specific parameters.

Returns True if any parameters have been modified, False otherwise.

The default value is False if the function is not implemented.

See also GetParametersSetParameters

OpenOpens files or APIs used in the search process. This function is required.

Syntax BOOL Open( )

Description Actuate calls this function when the search process begins. The extension should implement code to open files or APIs based on parameters or other relevant information.

Returns True if the function is successful, False otherwise.

See also Close

PutRowTransfers each row as it is created during the search process. This function is required.

Syntax BOOL PutRow( long rowIdx, const char* row )

C h a p t e r 2 4 , S e a r c h e x t e n s i o n A P I r e f e r e n c e 471

S e t D a t a T y p e I n f o

Parameter rowIdxA number indicating the row index for the search.

charA null terminated string containing all the data columns separated with the column delimiter.

Description Actuate calls this function for each row generated during the search process. The first row is a header row if the IncludeHeader function returns True.

Returns True to indicate acceptance of the row, False otherwise.

See also IncludeHeaderGetColumnDelimiter

SetDataTypeInfoProvides the data types for all columns of a row.

Syntax void SetDataTypeInfo( long numCols, long *dataTypes )

Parameter numColsThe number of columns in a row.

*dataTypesAn array of corresponding data types for each column. Valid data types are:

■ ANY_TP

■ ANYCLASS_TP

■ ARRAY_TP

■ BYTE_TP

■ CPOINTER_TP

■ CURRENCY_TP

■ DOUBLE_TP

■ DT_TIME_TP

■ EMPTY_TP

■ INSTANCE_TP

■ INT_TP

■ LONG_TP

■ NO_TP

472 P r o g r a m m i n g e . R e p o r t s

S e t P a r a m e t e r s

■ NULL_TP

■ OLE_TP

■ REF_TP

■ SINGLE_TP

■ STRING_TP

■ UNKNOWN_TP

■ USER_TP

■ VARIANT_TP

Description This function provides the data types for all the columns in a row. Implement is only if the data type information is needed in the search extension. Actuate calls SetDataTypeInfo after the Open function call. The pointer to the dataTypes array is temporary. This means you should copy its contents in the specific implementation.

SetParametersPasses extension-specific search definition parameters to the search extension DLL.

Syntax void SetParameters( const char* parms )

Parameter paramsA character string containing the extension-specific search parameters. This string matches the one returned by GetParameters.

Description Use this function to restore the extension-specific parameters retrieved from a search definition file. This function works in conjunction with the GetParameters function to allow the extension to store and retrieve information from the search definition file. Actuate calls SetParameters after it reads the search definition file.

See also GetParametersInputParameters

C h a p t e r 2 5 , A c t u a t e A c t i v e X c o n t r o l s u s e r g u i d e 473

C h a p t e r

Chapter 25Actuate ActiveX controlsuser guide

This chapter contains the following topics:

■ About Actuate’s ActiveX controls

■ About report files and the Actuate ActiveX controls

■ Actuate ActiveX methods by programming task

■ Visual Basic example

■ Installing Actuate ActiveX controls

474 P r o g r a m m i n g e . R e p o r t s

About Actuate’s ActiveX controlsActiveX controls, formerly known as OLE or OCX controls, are Microsoft Windows components for embedding prebuilt functionality into your custom applications. Using the Actuate Viewer and the Actuate Desktop ActiveX controls, you can add many of the Actuate Viewer and End User Desktop features to custom Windows applications.

Features of ActiveX controlsActuate ActiveX controls provide a programmatic interface for incorporating the following prebuilt functionality into your Windows applications:

■ Open and view a report (Desktop and Viewer ActiveX controls)

■ Navigate through the report (Desktop and Viewer ActiveX controls)

■ Run a report executable (.rox) file (Desktop ActiveX control only)

■ Print a report (Desktop and Viewer ActiveX controls)

Applications built with the Viewer ActiveX control can be distributed royalty-free, while a small royalty is charged for those built with the Desktop ActiveX control. Check your software license for details.

The primary component of the Actuate ActiveX control is a window for viewing Actuate reports. Developers place this window in the host application, along with other buttons and controls to implement the desired functionality.

Adding the Actuate ActiveX controls to your applicationYou add the control to your application using the tools available in your Basic and C++ development environment. Generally, you add the control to the workspace before adding it to your application so you can treat the Actuate controls like a standard component. Access the Actuate control features programmatically through Basic or C++ function calls to the ActiveX interface.

Adding the Actuate ActiveX controls to Visual BasicVisual Basic simplifies the process of adding custom controls to your application by treating them like standard controls. You add Actuate ActiveX controls to the toolbox along with the other standard controls and then build your application normally.

C h a p t e r 2 5 , A c t u a t e A c t i v e X c o n t r o l s u s e r g u i d e 475

Adding the Actuate ActiveX controls to C or C++Visual C++ handles custom controls through the Component Gallery, where you can add the Actuate control to your application. Once added, you implement the Actuate ActiveX features through standard C or C++ function calls. For more information about adding ActiveX controls to your application using Visual C++ or another compiler, see the compiler documentation.

Using ActiveX controls embedded in dialogsUse the CheckMessage interface in the ActiveX controls to program ActiveX controls embedded in dialogs. Using this programming interface ensures that ActiveX properly forwards messages to Actuate’s Search window and Table of Contents windows. Omitting the CheckMessage interface causes the application to hang.

The following example shows how to program a sample class that represents a modal dialog including the DeskOCX control. In the example, the member variable, m_desk represents the DeskOCX control. The class AcDeskDialog includes the method, PreTranslateMessage, of the CDialog class. PreTranslateMessage calls CheckMessage to properly handle message processing:

class AcDeskDialog:public CDialog{..// Overrides// ClassWizard generated virtual function overrides//{{AFX_VIRTUAL(AcDeskDialog)protected:virtual void DoDataExchange(CDateExchange* pDX); // DDX/DDV supportvirtual BOOL PreTranslateMessage(MSG* pMsg);//}}AFX_VIRTUAL>>>}BOOL AcViewerDialog::PreTranslateMessage(MSG* pMsg) {

if ( m_viewer.CheckMessage( (long*)pMsg ) )return TRUE;

return CDialog::PreTranslateMessage(pMsg);}

476 P r o g r a m m i n g e . R e p o r t s

About report files and the Actuate ActiveX controlsWhen using the controls, you work with the following files:

■ Report parameter values (.rov) file

The .rov file contains the parameter definitions and values used for report generation. You create and modify parameter files programmatically using the Requester API.

■ Report executable (.rox) file

The .rox file is used for creating a new report instance that contains current report information. The .rox uses the report parameter file, when specified, to set the parameter values used during execution.

■ Report object instance (.roi) file

The .roi file is the viewable report that appears in the ActiveX viewing window. The Actuate iServer System creates a new report document each time the .rox runs.

Specifying local file names for Actuate reportsThe term local file refers to a file stored on the native Windows file system, regardless of the actual physical location. Specify files on the native file system using the standard Windows format:

<drive>:\<path>\<filename>

<drive>The hard drive specification such as C.

<path>The full path to the file using Windows path separators.

<filename>The complete file name, including the .rox, .rov, or .roi file extension.

Specifying iServer file names for Actuate reportsSpecify files on iServer using the rotp format:

rotp: [//<server>]/<path>/<filename>[;<version>]

<server>Optional specification of iServer name. The default value is the current connection.

C h a p t e r 2 5 , A c t u a t e A c t i v e X c o n t r o l s u s e r g u i d e 477

<path>The full path to the file using UNIX path separators.

<filename>The complete file name including the .rox, .rov, or .roi file extension.

<version>Optional specification of the file version as the following table shows.

Actuate ActiveX methods by programming taskThis section categorizes and lists the groups of the programming files that the Actuate ActiveX controls implement:

■ Opening and closing a report instance

■ Navigating and viewing the report instance

■ Running a report (Desktop control only)

■ Printing, mailing, and saving a report

■ Invoking functions in an open report

■ Handling error conditions

Opening and closing a report instanceThe Actuate ActiveX controls can display reports either the Encyclopedia volume or the native file system store. To open and view a report stored in the volume, the application must connect to iServer as a user with read privilege for the report. If the file specifier is in the rotp format and the application has not yet established a server connection, the Actuate ActiveX control opens a dialog for entering a user name and password.

Value Description

Latest The most recent version of the file. This is the default value.

Oldest The oldest version of the file

LatestDev The most recent development version of the file

LatestRel The most recent released version of the file

<#> The specific version number of the file

<version name> The specific version name of the file

478 P r o g r a m m i n g e . R e p o r t s

The following methods implement server connections and report access.

Navigating and viewing the report instanceClient applications can navigate a report and extract data in the following ways:

■ Table of contents window

■ Search window

■ Go to page

■ Page forward and back

■ Hyperlink to a new report

■ Most recently viewed reports

The following tables summarize the navigation and viewing methods and events.

Method Description

ConnectToServer Establishes a server connection, which other methods use to access, view, and print reports stored in the Encyclopedia volume.

OpenReportInstance Opens a report, either in the Encyclopedia volume or the native file system, and displays the first page in the view window.

CloseReportInstance Closes the report.

GetLastError Gets the last error that occurred. Use this method to get the text of the error when a method returns a failure.

Method Description

AboutBox Opens the Actuate ActiveX About dialog

Back After a user follows a hyperlink, opens the previously viewed report

CurrentPage Returns the current page number of the open report

FirstPage Resets the report view to the first page

GetMostRecentListCount Returns the number of the most recently opened reports

C h a p t e r 2 5 , A c t u a t e A c t i v e X c o n t r o l s u s e r g u i d e 479

Running a reportThe Desktop ActiveX control runs reports only on the native file system. The first page of the new report instance automatically appears in the Actuate ActiveX control window when the report is available.

GetMostRecentListItemAt Returns the URL or path string of the specified report from the list of most recently opened reports

GoToPage Opens Actuate’s Go To Page dialog

LastPage Sets the report view to the last page

NextPage Advances the report view to the next page

OpenRecentReportInstance Opens the specified report from the list of most recently opened reports

PageCount Returns a page count of the open report

PreviousPage Moves to the previous page of the report

SearchWindow Opens the Actuate search window

SetScaleFactor Sets the scale factor of the report

SetWindowLayout Sets the Windows layout to right to left or left to right

TableOfContents Opens the Actuate table of contents window

Method Description

Event Description

BackDisable Occurs when the user has not followed an external hyperlink or when the list of previously viewed reports does not contain any reports.

BackEnable Occurs when a user has followed an external hyperlink

480 P r o g r a m m i n g e . R e p o r t s

The following table summarizes the methods for running reports.

Printing, mailing, and saving a reportThe following table summarizes the methods for printing, mailing, and saving reports.

Invoking functions in an open reportActuate reports can include custom functions that the report designer created using Actuate Basic. Functions in a report perform a variety of tasks, such as processing button events or computing report values.

Method Description

OpenReportExecutable (Desktop ActiveX Control only)

Opens a report executable (.rox) file. Use in conjunction with RunReport to generate a new report.

RunReport (Desktop ActiveX Control only)

Opens the standard parameter screen, runs the open report executable file, and displays the generated report.

RunReportWithParameters (Desktop ActiveX Control only)

Runs the open report executable file using a parameter file and displays the generated report.

CanRunReport (Desktop ActiveX Control only)

Indicates whether or not a report executable file is open and can run.

CancelReport (Desktop ActiveX Control only)

Cancels a currently executing request to run a report.

CloseReportExecutable (Desktop ActiveX Control only)

Closes the current report instance, if there is one, and the report executable file.

Method Description

BundleReportInstance Bundles a report executable file with a report object instance file.

MailReportInstance Displays the mail dialog with the current report instance attached.

PrintReport Opens the Windows print dialog where users can specify print options or prints with system defaults. Supersedes the Print method.

SaveAsXMLData Saves the open report in XML format.

C h a p t e r 2 5 , A c t u a t e A c t i v e X c o n t r o l s u s e r g u i d e 481

You access functions in a report from a Desktop or Viewer control using the CallBasicFunction. CallBasicFunction takes the name of the Actuate Basic function and its arguments and returns the result that the Actuate Basic function returns.

Handling error conditionsMost ActiveX methods provide status strings describing the actions that occurred n and their results. The following example shows how to check the status after each method call:

DIM count as IntegerDIM statusString1 as StringDIM statusString2 as String

' Clear any existing statusesResetStatus()

' Call OpenReport...OpenReportInstance( "Forecast.roi" )

' Check the statuses which came from calling OpenReport...count = GetStatusCount()

if ( count ){

' Get the status strings' The following assumes that ' only two status strings existstatusString1 = GetStatusCount( 0 );statusString2 = GetStatusCount( 1 );

}

' Clear the statuses againResetStatus()

' Continue with other ActiveX calls

482 P r o g r a m m i n g e . R e p o r t s

Visual Basic exampleThis section describes a sample Windows application developed in Visual Basic that uses the Desktop ActiveX control to implement the following features:

■ Open an existing report for viewing

■ Run a report executable file and view the new report instance

■ Print the screen

■ Page forward

■ Page backward

■ Open an Actuate table of contents

The sample application displays a start screen that contains the opening window for the Desktop ActiveX control and seven control buttons.

The center window is the primary Desktop control element. This window displays the open report instance. In this example, the Desktop control opens a report called forecast when the user clicks View or Run. Each button in the window invokes additional viewer functionality by making calls to the Desktop control interface.

Building the sample applicationBuild the sample application as follows:

■ Add the Desktop control to the toolbox.

C h a p t e r 2 5 , A c t u a t e A c t i v e X c o n t r o l s u s e r g u i d e 483

■ Add the Desktop control buttons and window to the application.

■ Program window and button events in Visual Basic.

The following sections describe how to perform these tasks.

How to add the Actuate Desktop ActiveX control to the toolbox

To include a custom control in your application, you add the control to the toolbox:

1 Choose Project➛Components.

Components appears.

2 Select Actuate Desktop Control. Choose OK.

The Actuate Desktop control appears in the toolbox.

How to add the Desktop control and button controls to your application

1 Select the Desktop ActiveX control and draw a viewing window in your application.

2 Using the Button tool, add control buttons around the viewing area to implement the functionality you want.

In this example, seven buttons implement the required features.

How to write Basic code for window and button events

1 Double-click the button.

2 Add Visual Basic code to link Windows events to Actuate functionality.

Button tool

Desktop ActiveX control

484 P r o g r a m m i n g e . R e p o r t s

The following Visual Basic window shows the completed code for each event.

Visual Basic code segment descriptionsWhen a user launches the application, the Desktop control window is blank. The View and Run buttons open the report for viewing. Other buttons implement navigation and printing operations. Each code segment is triggered by a button click, as described in the following sections.

Exit_ClickThe Exit button closes the report with CloseReportInstance(). Closing the report makes it available to other applications.

Next_ClickThe Next button uses NextPage() to advance the report to the next page, except at the last page. This navigation tool supports paging forward through the document.

C h a p t e r 2 5 , A c t u a t e A c t i v e X c o n t r o l s u s e r g u i d e 485

Prev_ClickThe Prev button uses PreviousPage() to back up one page in the report. This navigation tool supports paging backward through the document.

Print_ClickThe Print button opens the standard Windows dialog for user input. The argument of False means that the open document prints using the default printer settings.

Run_ClickThe Run button invokes two Desktop control methods. First, it opens the report executable file with OpenReportExecutable(), then it runs the report with RunReport().

Contents_ClickThe Contents button uses TableOfContents() to open Actuate’s table of contents window. Using the Contents window, users see a visual representation of the report contents and can jump directly to a specific section.

View_ClickThe View button uses the OpenReportInstance() method to open a report and display it in the Desktop control window. In this case, the application opens a report in the native file system, so it does not need to establish a server connection first. The display zooms to 50% using SetScaleFactor() to fit more of the report in the window.

Running the sample applicationThe Actuate ActiveX controls include a Visual Basic project file that implements the sample application. To use the sample application, you need the following products installed on your PC:

■ Visual Basic 5.0

■ Actuate Client Integration Technology

■ Actuate End User Desktop or Actuate e.Report Designer Professional

End User Desktop and e.Report Designer Professional include the sample database and drivers the sample report uses.

You can use the sample application either by running the Desktop executable file or by modifying the code. The following sections explain each option.

To run the sample application:

1 Navigate to the \Program Files\Actuate7\ClntIntTech\ActiveX Control\Examples directory.

486 P r o g r a m m i n g e . R e p o r t s

2 Double-click Desktop.exe.

The sample application opens and sets the default directory.

To compile and run the sample application:

1 Navigate to the \Program Files\Actuate7\ClntIntTech\ActiveX Control\Examples directory.

2 Double-click Desktop.vbp.

The sample application opens in Visual Basic and sets the default directory.

3 Compile and run the application in Visual Basic.

If the sample report does not open, check the following:

■ Make sure Sfdata is set up as an ODBC database on your machine. For more information about setting up Sfdata, see Chapter 1, “Designing an e.report with the report wizard,” in Developing Advanced e.Reports.

■ Verify that Visual Basic uses the Examples directory as the default directory. The sample application looks for Forecast.roi and Forecast.rox in the default directory.

Installing Actuate ActiveX controlsIf you plan to ship an Actuate ActiveX control with your application, your install program must copy the necessary files and register the Actuate ActiveX control.

To install the ActiveX controls:

1 Create a Jar directory on the same level as the client application. For example, if the client application is at C:\Program Files\[clientapp], place the Jar directory at C:\Program Files\Jar.

2 Copy the following files to the Jar directory. These files facilitate the use of chart technology.■ acf1j10chart.jar■ crimson.jar ■ jaxp.jar

3 Create the following directory structure for the ActiveX control.

afc

binetc

ActiveX

C h a p t e r 2 5 , A c t u a t e A c t i v e X c o n t r o l s u s e r g u i d e 487

4 Copy the following files to the bin directory: ■ Axdesk.dll■ Axview.dll■ acxcel.dll■ accorvu.dll■ acfile.dll■ acbrio.dll

5 Copy the version of the compiled library used to build your reports to the afc directory.

The compiled library name is Afcxxx.rox, where xxx is the version number. For more information about version numbers, see “Choosing API files,” later in this chapter.

6 Copy the following Actuate dynamic link libraries (.dll) to the Windows server System32 directory, or the Windows 95 or 98 System directory: ■ Acrsxxxx.dll■ Acrxxxx.dll

xxxx is the version number. For more information about version numbers, see “Choosing API files,” later in this chapter.

7 Copy the following Microsoft DLLs to the Windows server System32 directory, or the Windows 95 or 98 System directory:■ Msvcrt.dll■ Msvcirt.dll■ Mfc42.dll■ MfcanS32.dll■ Olepro32.dll■ Oc30.dll

8 Copy the following third-party DLLs to the Windows server System32 directory, or the Windows 95 or 98 System directory:■ Winrpc32.dll■ Ezrpcw32.dll■ Widge32.dll■ Gsjpg32.dll■ Gswag32.dll■ Gsw32.exe■ Gswdll32.dll

488 P r o g r a m m i n g e . R e p o r t s

■ LeadTools DLLs—Graphics control- Lfcmp10.dll- Ltkrn10n.dll- Ltdis10n.dll- Ltfil10n.dll- Ltwnd10n.dll- Ltdlg10n.dll

For proper functioning of the ActiveX control, the graphics server files (Gsw*.*) must be in the Windows server System32 directory, or the Windows 95 or 98 System directory.

9 Ensure that the client machine does not have duplicate or additional graphics server files in the following locations:■ Any directory included in the PATH, other than the Windows server

System32 directory, or the Windows 95 or 98 System directory.■ Current directory for your application.■ Directory that contains the .roi and.rox files.

10 Register the Actuate control using Regsvr32.

Use the following command line syntax for the Desktop product:

regsvr32 <drive> : <path> axdesk.dll

11 If your application uses iServer, set the following registry values:

HKEY_LOCAL_MACHINE\SOFTWARE\Actuate 7\Actuate iServer\AC_CLIENT_HOME = <drive> : <path>\ActiveX

Choosing API filesThe ActiveX controls utilize dynamic link libraries (.dll) and compiled library files (.rox) during execution. Actuate periodically updates the DLLs to enhance features, correct problems, and support different development environments. This section explains how to choose the correct DLL version for your application.

API file name conventionsThe following table summarizes the file naming conventions for Actuate 7

C h a p t e r 2 5 , A c t u a t e A c t i v e X c o n t r o l s u s e r g u i d e 489

.

API file versionsWhen choosing an API file for your application, follow these guidelines:

■ Use the Lib files that correspond to the DLLs for the release you are using. For example, if you use acrs7060.dll, the corresponding library file is acrs7060.lib.

■ Choose the .rox file used to compile the reports the Actuate ActiveX control will open. When necessary, you can copy multiple .rox versions to the \Afc directory.

■ Refer to the release notes for the most up-to-date information about DLL or Lib files.

If your applications use Actuate ActiveX with the Requester API, you must include the following Requester API DLL along with the Report Server API DLL shown in “API file name conventions.”

DLL File Name

Report server API DLL acrsxxyy.dll■ xx = Report server API version

yy = Visual C++ version (6.0)Example: acrs7060.dll

RogueWave DLL acrxxyy.dll■ xx = RogueWave version

yy = Visual C++ version (6.0)Example: acr7560.dll

Compiled library afcxxx.rox■ xxx = Compiled library version Example: afc853.rox

Actuate ActiveX controls release VC++ 6.0

7 acrq7060.dll

6.0 Service Pack 1 acrq6060.dll

6.0 acrq6060.dll

5.0 Service Pack 2 Patch 1 acrq5060.dll

5.0 Service Pack 2 acrq5060.dll

5.0 Service Pack 1 Patch 1 acrq5060.dll

5.0 Service Pack 1 acrq5060.dll

490 P r o g r a m m i n g e . R e p o r t s

5.0 acrq5060.dll

4.0 to 4.1 acrq4060.dll

Actuate ActiveX controls release VC++ 6.0

C h a p t e r 2 6 , A c t u a t e A c t i v e X c o n t r o l s r e f e r e n c e 491

C h a p t e r

Chapter 26Actuate ActiveX controlsreference

The Actuate Desktop and Viewer ActiveX controls conform to the Microsoft standard for ActiveX (OCX) controls. This reference describes the methods and events you can use with the controls. Some methods are available only with the Desktop control and are marked as such.

492 P r o g r a m m i n g e . R e p o r t s

A b o u t B o x

AboutBox Opens the Actuate ActiveX About dialog.

Syntax void AboutBox()

Description This method opens the Actuate ActiveX About dialog. The dialog displays the Actuate ActiveX version number and copyright information.

BackOpens the report the user viewed before following an external hyperlink.

Syntax short Back()

Description This method removes the path of the report the user viewed before following an external hyperlink from the back stack and opens that report. You cannot use the Back() method to open a previous location in the same report.

Returns 1 if the method succeeded, 0 otherwise.

BackDisableOccurs when the user has not followed an external hyperlink or when there are no reports in the list of recently opened reports.

Syntax BackDisable()

Description BackDisable occurs when the user has not followed an external hyperlink or when the list of previously viewed reports does not contain any reports. For example, you can use BackDisable to disable the Back button in your application if the user has not followed any external hyperlinks.

BackEnableOccurs when an external hyperlink has been followed.

Syntax BackEnable()

C h a p t e r 2 6 , A c t u a t e A c t i v e X c o n t r o l s r e f e r e n c e 493

B u n d l e R e p o r t I n s t a n c e

Description BackEnable occurs when a user followed an external hyperlink or if there are reports in the list of recently opened reports. For example, use BackEnable to enable the Back button that lets users return to the last report the user viewed.

BundleReportInstance Bundles a report executable (.rox) file with a report document (.roi) file.

Syntax BOOL BundleReportInstance(LPCTSTR fileName)

Parameter fileNameThe name of the bundled report.

Description This method bundles the report executable (.rox) file into the report document (.roi) file. BundleReportInstance saves the bundled report with the specified file name.

Returns True if the .rox was bundled with the .roi and saved to a file.

False if the bundled .roi was not saved to a file.

CallBasicFunctionCalls an Actuate Basic function in the open report.

Syntax long CallBasicFunction(LPCTSTR methodName, const VARIANT& arg1, const VARIANT& arg2, const VARIANT& arg3, const VARIANT& arg4, const VARIANT& arg5)

Parameter methodNameString containing the name of an Actuate Basic function to call. This function must be a global function in the report and must return an integer (long).

arg1 through arg5 (optional)Variants containing arguments for the called function. Valid Actuate Basic data types for these arguments are integer, long, double, float, Boolean, and string. Use similar types in your application.

Description This method invokes an Actuate Basic function in the open report. CallBasicFunction takes the name of the Actuate Basic function and up to five arguments and returns the value that the Actuate Basic function returns.

494 P r o g r a m m i n g e . R e p o r t s

C a n c e l R e p o r t

Returns The value the Actuate Basic function returns, unless an error occurs. If an error occurs, CallBasicFunction returns one of the following error codes.

CancelReport Desktop ActiveX Control only. Cancels report generation.

Syntax void CancelReport()

Description This method stops report generation requested with RunReport or RunReportWithParameters. Call this method during report generation.

See also RunReportRunReportWithParameters

CanRunReport Desktop ActiveX Control only. Indicates whether or not a report executable file can run.

Syntax BOOL CanRunReport()

Description A report can be generated if a report executable file is open and a report is not currently running. You can use the return value to enable or disable user interface elements.

Returns True if a report executable file can be run, False otherwise.

See also OpenReportExecutableRunReport

Error code Description

-1 No report instance open

-2 Could not find specified function

-3 Unsupported type specified as argument

-4 Wrong number of arguments

-5 Function did not return a value

-6 Function did not return an integer

C h a p t e r 2 6 , A c t u a t e A c t i v e X c o n t r o l s r e f e r e n c e 495

C l o s e R e p o r t E x e c u t a b l e

CloseReportExecutableDesktop ActiveX Control only. Closes the report executable file.

Syntax BOOL CloseReportExecutable()

Description This method closes the open report instance, if there is one, and the report executable file. Call this method after the report executable file finishes running.

Returns True if the method succeeded, False otherwise.

See also OpenReportExecutable

CloseReportInstanceCloses the open report.

Syntax short CloseReportInstance()

Description This method closes the open report and leaves the Actuate controls idle. Call this method when changing the view from one report to another.

Returns 1 if the method succeeded, 0 otherwise.

See also OpenReportInstanceOpenReportExecutable

ConnectToServerEstablishes an iServer connection.

Syntax BOOL ConnectToServer(LPCTSTR hostName, LPCTSTR userName, LPCTSTR password)

Parameter hostNameThe name of the host computer where iServer is running. iServer has the same name as the host computer.

userNameThe name of a valid user on the administration server.

passwordThe password associated with the userName.

496 P r o g r a m m i n g e . R e p o r t s

C u r r e n t P a g e

Description To access reports in an Encyclopedia volume, the client application must first connect to iServer as a user with the necessary read permissions.

This method makes the necessary server connection and validates the user name and password. If you attempt to open a report on a server before calling this method, a dialog appears for entering the user name and password. All other methods use this connection to exchange information with iServer. Accessing reports stored in the native file system does not require this connection.

Returns True if the connection succeeded, False otherwise.

CurrentPageReturns the current page number.

Syntax long CurrentPage()

Description This method is a navigation aid for client applications. Use this method to display page status, like page x of y.

Returns The current page number.

FirstPageResets the view to the first page of the report.

Syntax BOOL FirstPage()

Description This method returns the view to the beginning of a report. If the view is at the first page, this method has no effect.

Returns True if the change succeeded, False otherwise.

GetLastErrorReturns the last error message.

Syntax BSTR GetLastError()

Description This method returns a text description of the last error encountered. You typically invoke GetLastError after a method returns a Fail result code. This method does not return the result of the last executed method.

C h a p t e r 2 6 , A c t u a t e A c t i v e X c o n t r o l s r e f e r e n c e 497

G e t M o s t R e c e n t L i s t C o u n t

Returns A CString describing the error condition.

An empty string if no errors occurred.

GetMostRecentListCountReturns the number of items in the most recently opened reports list.

Syntax short GetMostRecentListCount()

Description This method returns the number of items in the recently opened reports list. Up to 20 reports are kept in the recently opened list.

The index for the recently opened reports list starts with 0.

Returns The number of most recently opened reports.

GetMostRecentListItemAtReturns the URL or path of the specified report from the recently opened reports list.

Syntax BSTR GetMostRecentListItemAt(long index)

Parameter indexThe list location of the item. The index starts with 0.

Description This method returns the URL or path string of the specified item from the recently opened reports list.

Returns The URL or path CString of the report.

GetStatusCountReturns the number of status messages in the stack.

Syntax long GetStatusCount()

Description This method returns the number of status messages in the stack. The stack holds a maximum of messages 500 messages.

Returns The number of status messages.

498 P r o g r a m m i n g e . R e p o r t s

G e t S t a t u s M e s s a g e A t

GetStatusMessageAtReturns the status message string from the specified point in the status stack.

Syntax BSTR GetStatusMessageAt(long index)

Parameter indexThe list location of the message. The index starts with 0.

Description This method returns the status message from the specified point in the status stack.

Returns The status message.

GoToPageChanges the view to a specific page number of the report.

Syntax BOOL GoToPage(long Page)

Parameter PageThe number of the desired page.

Description Use this method to move through reports when you know the content location.

Returns Returns True if the change succeeded, False otherwise.

LastPageAdvances the view to the last page of the report.

Syntax BOOL LastPage()

Description This method advances the view to the end of a report. If the view is at the last page, this method has no effect.

Returns True if the change succeeded, False otherwise.

LoadResourceLoads the NLS resource DLL.

Syntax BOOL LoadResource(LPCTSTR localeName)

C h a p t e r 2 6 , A c t u a t e A c t i v e X c o n t r o l s r e f e r e n c e 499

M a i l R e p o r t I n s t a n c e

Parameter localeNameThree-letter Windows language symbol such as JPN, ENU, or FRA.

Description This method loads the NLS resource DLL specified by the localeName. After executing LoadResource, the Actuate dialogs and error messages appear in the language localeName specifies.

LoadResource looks for the file <appname>.xxx in the Nls\Xxx\Directory. For example, if the application name is AxDesk and the localeName is jpn LoadResource looks for Nls\Jpn\Axdesk.jpn.

If LoadResource cannot find Nls\Xxx\<appname>.xxx, it looks forNls\Xxx\<appname>.dll. If a resource DLL is not found, the English resources in the executable file are used.

To view loaded language resources, your system must be set up for the appropriate language. For example, you can load a Japanese resource DLL under US English Windows but it will not display correctly.

Returns Returns True if the file was loaded, False otherwise.

MailReportInstanceDisplays the mail dialog with the current report instance attached.

Syntax BOOL MailReportInstance([bundle])

bundle (optional)True bundles the report executable (.rox) file into the report document (.roi) file before the report is mailed. False does not bundle the .rox file. The default value is False.

Description This method displays the mail dialog with the current report instance attached.

Returns True if the .roi was attached to an e-mail, False otherwise.

NextPageAdvances to the next page of the report.

Syntax BOOL NextPage()

Description This method advances the view to the next page of the report. If the view is at the last page, this method has no effect.

Returns True if the page change succeeded, False otherwise.

500 P r o g r a m m i n g e . R e p o r t s

O p e n R e c e n t R e p o r t I n s t a n c e

OpenRecentReportInstanceOpens the specified report from the recently opened reports list.

Syntax short OpenRecentReportInstance(long index)

Parameter indexThe list location of the desired report. The index starts at 0.

Description This method opens the specified report from the recently opened reports list.

Returns 1 if the file open succeeded, 0 otherwise.

OpenReportExecutableDesktop ActiveX Control only. Opens a report executable file.

Syntax BOOL OpenReportExecutable (LPCTSTR reportName)

Parameter reportNameThe fully qualified name of the report file (.rox), expressed as a Windows path and file name. The rotp format is not valid in this context.

Description This method opens a report executable file in preparation for report generation. Client applications use report executable files to generate reports with updated data. You can open only one report executable file at a time.

The Desktop ActiveX Control can read report executable files only from the local file system, so construct the report name as a Windows path and file name, such as C:\Eastern Region\Forecast.rox. To run reports on iServer or to extract report executable files from iServer for local execution, use the Report Server API in conjunction with the Desktop ActiveX control.

Returns True if the file open succeeded, False otherwise.

See also RunReportCloseReportInstanceCloseReportExecutable

C h a p t e r 2 6 , A c t u a t e A c t i v e X c o n t r o l s r e f e r e n c e 501

O p e n R e p o r t I n s t a n c e

OpenReportInstanceOpens a report in the Encyclopedia volume or the client file system.

Syntax short OpenReportInstance (LPCTSTR reportName)

Parameter reportNameThe fully qualified name of the report file (.roi) to open.

Description This method opens a report and displays the first page in the client application window. It retrieves the report from the Encyclopedia volume if reportName is formatted in the rotp format. For example, to open a report called Forecast in the Eastern Region folder in the Paradise Encyclopedia volume, as the reportName, type

rotp://Paradise/Eastern Region/Forecast.roi

The server enforces access permissions before opening the report. This means the user must have read permission to open the requested report. If this you call this method without an active server connection, it displays a dialog that prompts for a user name and password.

If the report file specification is formatted as a Windows path, such as C:\Eastern Region\Forecast.roi, this method retrieves the report from the PC’s file system. Only one report can be open at a time. For more information about specifying local or server reports, see “About report files and the Actuate ActiveX controls,”in Chapter 25, “Actuate ActiveX controls user guide.”

Returns 1 if the file open succeeded, 0 otherwise.

See also CloseReportInstanceConnectToServer

PageCountReturns the page count for the open report.

Syntax long PageCount()

Description This method is a navigation aid for client applications. You typically use this method to display report page information, such as page x of y, where y is the page count.

Returns The number of pages in the current view.

502 P r o g r a m m i n g e . R e p o r t s

P r e v i o u s P a g e

PreviousPageMoves to the previous page of the report.

Syntax BOOL PreviousPage()

Description This method is a navigation aid for client applications. You typically use this method to page backward through the report. At the first page, this procedure has no effect.

Returns True if the page change succeeded, False otherwise.

PrintOpens the standard Windows print dialog for report printing. Use in C++ applications only.

Syntax void Print(BOOL showDialog)

Parameter showDialogTrue opens the standard Windows print dialog. False prints with default print parameters.

Description Use this method to print the open report using the standard print utilities of the Windows operating system. Print options are either system defaults or user-selected.

PrintReport supersedes the Print method. Visual Basic developers must use PrintReport for report printing. C++ developers can continue to use Print.

See also PrintReport

PrintReportOpens the standard Windows print dialog for report printing. This method supersedes Print.

Syntax void PrintReport(BOOL showDialog)

Parameter showDialogTrue opens the standard Windows print dialog. False prints with default print parameters.

C h a p t e r 2 6 , A c t u a t e A c t i v e X c o n t r o l s r e f e r e n c e 503

R e s e t S t a t u s

Description Use this method to print the open report using the standard print utilities of the Windows operating system. Print options are either system defaults or user-selected. Visual Basic developers must use PrintReport for report printing. C++ developers can use either PrintReport or Print.

See also Print

ResetStatusClears the status stack.

Syntax void ResetStatus()

Description This method clears the status stack.

RunReport Desktop ActiveX Control only. Runs the open report executable file to generate a new report instance.

Syntax BOOL RunReport()

Description This method runs the open report executable file and generates a report instance in the local file system. Before calling this method, open the report executable file with OpenReportExecutable.

Before running the report, RunReport opens the parameter dialog for user input. This method returns when the report completes, encounters an error, or is canceled. While the report executes, the application continues to get window messages so that a Cancel button is effective. When the report is complete, RunReport displays the first page of the report in the Actuate control window of the client application.

Returns True if the report executed successfully, False otherwise.

See also OpenReportExecutableCancelReport

504 P r o g r a m m i n g e . R e p o r t s

R u n R e p o r t W i t h P a r a m e t e r s

RunReportWithParameters Desktop ActiveX Control only. Runs the open report executable file to generate a new report instance.

Syntax BOOL RunReportWithParameters(LPCTSTR parameterFile)

Parameter parameterFileThe fully qualified name of the report parameter values file (.rov) to open.

Description This method runs the open report executable file and generates a report instance in the local file system, using parameters specified in the parameter file. Before calling this method, open the report executable file with OpenReportExecutable.

RunReportWithParameters generates the report using parameters stored in the specified parameter file. This method returns when the report completes, encounters an error, or is canceled. While the report is executing, the application continues to get window messages, so a Cancel button is effective. When the report is complete, RunReportWithParameters displays the first page of the report in the Actuate control window of the client application.

Returns True if the report executed successfully, False otherwise.

See also OpenReportExecutableCancelReport

SaveAsXMLDataSaves the open report in XML format.

Syntax BOOL SaveAsXmlData(LPCTSTR filename)

Parameter filenameThe file name for XML output.

Description This method converts the open document to XML format and saves it to the users’s disk. The document is not saved in the Encyclopedia volume.

Returns True if the conversion was successful, False otherwise.

C h a p t e r 2 6 , A c t u a t e A c t i v e X c o n t r o l s r e f e r e n c e 505

S e a r c h W i n d o w

SearchWindowOpens a window for searching a report.

Syntax BOOL SearchWindow()

Description This method opens an Actuate search window. You can search objects in the open report for specific values or ranges. For example, from the Search dialog you could search the Company Name field for a specific company. The Actuate control search window is identical to the Viewer search window.

Returns True if the request succeeded, False otherwise.

SetScaleFactorSets the scale factor for the view.

Syntax BOOL SetScaleFactor(long factor)

Parameter factorThe scale factor for the view, stated as a percent. The minimum value is 25%. The maximum value is 400%. The default value is 100%.

Description This method is typically linked to a view control that lets you zoom in and out on reports.

Returns True if the scale factor request succeeded, False otherwise.

SetWindowLayoutSets the Windows layout to right to left or left to right.

Syntax BOOL SetWindowLayout(int orientation)

Parameter orientationThe Windows orientation:

■ 0 Windows layout is left to right

■ 1 Windows layout is right to left

Description Use this method for right to left languages. It sets the Windows layout for the Search, Table of Contents, and GoToPage windows. You must call SetWindowLayout before opening a report instance.

Returns True if the method succeeded, False otherwise.

506 P r o g r a m m i n g e . R e p o r t s

T a b l e O f C o n t e n t s

TableOfContentsOpens a window that displays Actuate’s table of contents window.

Syntax BOOL TableOfContents()

Description This method opens Actuate’s table of contents window for the open report. The table of contents window displays the sorting and grouping structure of the report. When finished, you can close the table of contents window using standard Windows procedures.

Returns True if the table of contents request succeeded, False otherwise.

I n d e x 507

IndexSymbols! (exclamation point) in code 267" (double quotation mark) in strings 268" (quotation mark) in strings 272# (number sign)

in dates 273, 274type declaration 267

$ (dollar sign) character in code 267, 273% (percent) character in code 266& (ampersand) character in code 266& operator 256( ) characters in expressions 256* (asterisk) as text string 394, 440* operator 254+ (plus) characters

line continuation 257multiple options in API function calls 378,

427+ operator 254. (dot) operator 39, 40, 276/ operator 254: (colon) as separation character 257:: operator 22< operator 255<= operator 255<> operator 255= operator

assignment 252comparisons 254, 255

> operator 255>= operator 255@ (at-sign) character in code 253, 267\ operator 254^ operator 254– (minus sign) in strings 270– operator 254’ (apostrophe) in code 256

Numerics32-bit applications 293

AAbout dialog box 492AboutBox method 478, 492abstract base classes 4, 21

Actuate-specific 4AC_DWB constant 409AC_ERD constant 409AC_EUDT constant 409AC_REQ_ASYNC constant 378, 379, 406,

424, 427, 428, 451, 458AC_REQ_CURRENCY type 398AC_REQ_DATETIME type 398AC_REQ_DOUBLE type 398AC_REQ_GENERATE constant 353, 356, 378,

427AC_REQ_HIDE constant 378, 379, 406, 427,

428, 451AC_REQ_INTEGER type 398AC_REQ_LAUNCH_ALWAYS constant 378,

379, 406, 424, 427, 428, 450, 458AC_REQ_LOCAL constant 378, 379, 411, 424,

427, 428, 453, 458AC_REQ_PRINT constant 356, 378, 379, 406,

427, 428, 450AC_REQ_REPLACE constant 378, 379, 427,

428AC_REQ_RETURN_HANDLE constant 378,

379, 427, 428AC_REQ_ROX constant 349AC_REQ_SHOW_PROG_WND

constant 378, 427AC_REQ_STAY_OPEN constant 378, 379,

406, 427, 428, 451AC_REQ_STRING type 398AC_REQ_UNKNOWN type 398AC_REQ_USE_HANDLE constant 378, 427AC_REQ_VIEW constant 353, 378, 379, 424,

427, 428, 458AC_VIEWER constant 409AcBaseFrame class 6, 11AcBasePage class 11acbrio.dll 487

508 P r o g r a m m i n g e . R e p o r t s

AcBTree class 14Access Control Lists 133

customizing 153–154displaying 139suppressing security IDs in 153

access control lists (ACLs)debugging 120

access restrictions 132, 154accessing

data xxiiireport sections 153

Java objects xxviionline documentation xxxii

accessing Actuate APIs 337accessing data

from external applications 81, 292, 304from multiple sources 98–103in flat files 94–98in input data sources 79in OLE objects 294, 295in SQL tables 85in text files 90methods specific to 31

accessing Java objects 316, 317–318accessing online help xxxiiaccessing report files 376, 426accessing reports

ActiveX method calls for 496in Encyclopedia volumes 335

AcCleanup function 310AcCollection class 14AcComponent class 5, 7AcConditionalSection class 10AcConnection class

overview 5, 8subclassing 85

AcControl class 6, 14accorvu.dll 487AcCurrency class 314AcCurrencyControl class 14AcDataAdapter class 6, 9, 78AcDatabaseSource class 9AcDataControl class 14AcDataFilter class 6, 9AcDataFrame class 11AcDataRow class 6AcDataSection class 10

AcDataSource classoverview 6, 9subclassing for custom data streams 94

AcDateTimeControl class 14AcDBConnection class 5, 8AcDBCursor class 9, 85AcDBStatement class 9, 85AcDetailGraph class 14AcDoubleControl class 14AcEllipseControl class 14acfile.dll 487AcFlow class 6, 11AcFrame class 12AcGraph class 14AcGroupSection class 10AcHLCGraph class 14AcImageControl class 14AcInformixConnection class 8AcIntegerControl class 14AcIterator class 14AcLabelControl class 14AcLeftRightPageList class 11, 73AcLineControl class 14AcList class 14AcMemoryBuffer class 10, 80AcMemoryDataSorter class 10AcMSSQLConnection class 8AcMultipleInputFilter class 10, 80, 98AcObjectArray class 14AcODBCConnection class 8AcOleContainerControl class 14AcOleControl class 14AcOracleConnection class 8AcOrderedCollection class 14AcPage class 11AcPageList class 6, 11, 73AcParallelReport class 10AcPopupMenu class 14AcProgressConnection class 8AcProgressSQL92Connection class 8AcRecordBuffer class 80AcRectangleControl class 14AcReport class

instantiating 66overview 6, 7subclassing 239XML-specific properties 231

I n d e x 509

AcReportComponent class 6, 7, 68XML-specific properties 232

AcReportController class 14AcReportSection class 10, 69AcReqAddToCache function 459AcReqCloseFile function 344, 354, 376AcReqConnect function 342, 376

error checking with 350AcReqDisconnect function 342, 354, 377

error checking with 350AcReqDropFromCache function 459AcReqGenerateReport function 348, 349, 353,

356, 377AcReqGetAdhoc function 345, 382AcReqGetAlias function 345, 382AcReqGetCacheFile function 459AcReqGetDefaultValueCurrency

function 346, 383AcReqGetDefaultValueDate function 346,

384AcReqGetDefaultValueDouble function 346,

385AcReqGetDefaultValueInteger function 346,

386AcReqGetDefaultValueStr function 346, 387AcReqGetDefaultValueString function 346,

388AcReqGetError function 389AcReqGetErrorString function 391AcReqGetFirstGroup function 345, 391AcReqGetFirstParameter function 345, 392AcReqGetHidden function 345, 393AcReqGetHideText function 345, 393AcReqGetNextGroup function 345, 394AcReqGetNextParameter function 345, 395AcReqGetParmType function 346, 396AcReqGetPrinterCapabilities function 459AcReqGetReportVersion function 344, 396AcReqGetRequired function 345, 397AcReqGetType function 346, 398AcReqGetValueCurrency function 347, 399AcReqGetValueDate function 347, 400AcReqGetValueDouble function 347, 401AcReqGetValueInteger function 347, 401AcReqGetValueStr function 347, 402AcReqGetValueString function 347, 403AcReqGetVersionNumber function 404

AcReqHasDefaultValue function 346, 405AcReqInfo function 459AcReqInitialize function 342, 351, 355, 405

error checking with 350AcReqPrintReport function 348, 353, 356, 406AcReqReadFile function 344, 407AcReqReportStatus function 350, 408

error checking with 350AcReqSelectClient function 342, 409AcReqSetDefaultPrinter function 348, 410

error checking with 350AcReqSetEUDTPath function 342, 355, 410

AcReqSelectClient and 409error checking with 350

AcReqSetPrinterCollate function 348, 411error checking with 350

AcReqSetPrinterColor function 348, 411error checking with 350

AcReqSetPrinterDuplex function 348, 350, 412

AcReqSetPrinterFormName function 348, 350, 412

AcReqSetPrinterName function 348, 353, 413error checking with 350

AcReqSetPrinterNumberCopies function 348, 350, 413

AcReqSetPrinterOrientation function 348, 350, 413

AcReqSetPrinterPaperSize function 348, 414error checking with 350

AcReqSetPrinterScale function 348, 417error checking with 350

AcReqSetPrinterTray function 348, 417error checking with 350

AcReqSetRequestPriority function 348, 418error checking with 350

AcReqSetScopedParameterName function 345, 418

AcReqSetValueCurrency function 347, 419AcReqSetValueDate function 347, 420AcReqSetValueDouble function 347, 421AcReqSetValueInteger function 347, 422AcReqSetValueString function 347, 349, 422AcReqUnInitialize function 342, 354, 356, 423

error checking with 350AcReqViewReport function 348, 356, 424

valid arguments for 344

510 P r o g r a m m i n g e . R e p o r t s

AcReqWriteFile function 344, 425acrq3041.dll 341acrq4060.dll 339acrq5060.dll 339acrs4060.dll 340acrs5060.dll 340AcSection class 6, 10AcSequentialSection class 10AcSimplePageList class 11, 73AcSingleInputFilter class 10, 80AcSingleList class 14AcSingleListIterator class 14AcSQLQuerySource class 10, 80AcSubPage class 11AcSummaryGraph class 14AcSybaseConnection class 8AcSybaseDBLibConnection class 8AcTextControl class 14AcTitleBodyPageList class 11, 73active connection 352Active Portal xxv

do_executereport.jsp JavaServer Page 217ActiveX API reference 491ActiveX controls xxv

adding 474, 483developing applications with 482embedding in dialogs 475error handling 481files associated with 476implementing with Requester API 489installing 486overview 292, 327programming tasks for 477selection guidelines for 330

ActiveX methodsalphabetical reference 491categorized 477

ActiveX viewing windowchanging views in 495displaying reports in 476, 479, 503, 504moving to specific page in 498, 499, 502resetting to first page 496scaling reports for 505

AcTopDownFlow class 11ActualPageNumber constant 137Actuate Basic xxv, xxix

breakpoints and 123calling C functions 310, 313, 314

calling functions from ActiveX controls 481, 493

class data types for 265cleanup code for 66, 463code elements 252–256code examples for 258, 358compared to Visual Basic 250control structures 285creating source files for 281debugging code 116, 118defining stored procedures with 192editing restrictions 55, 56, 60, 61editor for 48extending functionality 280, 310instantiating classes with 18Java type conversions for 318, 319multiple method definitions in 32naming conventions 257optimizing code 267, 272overview 250–251private and public variables in 26programming conventions 251, 256–258selecting API for 337simplifying programming tasks 280standard data types for 265startup code for 66, 463stopping debugging sessions for 125support for OLE automation 304tracking methods calls for 128variable type mappings 198–199

Actuate Desktop controls 483Actuate Foundation Class Library xxvActuate Foundation Class library

overview 4scoping conventions in 24

Actuate Foundation ClassesSee also classes; specific classbase classes described 5categorized 7class-specific types 265–266deriving classes from 20getting information about 48instantiating 4, 6, 24, 74overview 4predefined methods in 30programming language for 18XML extensions 230

Actuate home page xxvii

I n d e x 511

Actuate product suite xxivActuate product updates xxviiActuate SDK 337Actuate technology xxiActuate Viewer. See ViewerAcVisualComponent class 6AcWReqConnect function 342, 425

error checking with 350AcWReqGenerateReport function 348, 426AcWReqGetAdhoc function 345AcWReqGetAlias function 345, 430AcWReqGetDefaultValueCurrency

function 346, 431AcWReqGetDefaultValueDate function 346,

432AcWReqGetDefaultValueDouble

function 346, 433AcWReqGetDefaultValueInteger

function 434AcWReqGetDefaultValueStr function 346,

435AcWReqGetDefaultValueString

function 346, 436AcWReqGetErrorString function 350, 381,

437AcWReqGetFirstGroup function 345, 437AcWReqGetFirstParameter function 345, 438AcWReqGetHidden function 345, 439AcWReqGetHideText function 345, 439AcWReqGetNextGroup function 345, 440AcWReqGetNextParameter function 345, 441AcWReqGetParmType function 346, 442AcWReqGetRequired Function 442AcWReqGetRequired function 345AcWReqGetType function 346AcWReqGetValueCurrency function 347, 443AcWReqGetValueDate function 444AcWReqGetValueDouble function 347, 445AcWReqGetValueInteger function 347, 446AcWReqGetValueStr function 347, 447AcWReqGetValueString function 347, 448AcWReqGetVersionNumber function 448AcWReqHasDefaultValue function 346, 449AcWReqPrintReport function 348, 450AcWReqReadFile function 344, 452AcWReqSetEUDTPath function 342, 452

error checking with 350

AcWReqSetPrinterFormName function 348error checking with 350

AcWReqSetPrinterName function 453error checking with 350

AcWReqSetValueCurrency function 347, 453AcWReqSetValueDate function 347, 454AcWReqSetValueDouble function 347, 455AcWReqSetValueInteger function 347, 456AcWReqSetValueString function 347, 457AcWReqViewReport function 348, 457AcWReqWriteFile function 344, 459acxcel.dll 487ad hoc parameters 106

testing for 382, 430ad hoc queries xxviadapters. See data adaptersAdd 197Add Method dialog box 58AddFrame method 73adding

balloon help 162–163company names and logos 106components

in Design Editor 22to report designs 251

context menus 159–162context-sensitive help 163–165controls

for stored procedures 176objects 36

for Java applications 317for OLE containers 14from external applications 292, 296

OLE objects 296–299page number controls 137security IDs 134

adding balloon help 165adding context menus 160, 161adding context-sensitive help 163addition operator (+) 254AddMenuCommands method

creating context menus 159, 160, 161default action for 161implementing context-sensitive help 164

administrators 326afc directory 487AFC. See Actuate Foundation Classes

512 P r o g r a m m i n g e . R e p o r t s

aggregate controlsretrieving content for 72

AIX C++ compilers 338AIX servers 340Alias keyword 313aliases 265

getting parameter 382, 430nonstandard names 313user-defined types as 275

aligningbrowser code output 207

AllocateCursor method 85, 189allocating database cursors 85, 189alternate names. See aliasesAlternateText property

Actuate Viewer and 214browser scripting controls and 205, 208displaying 208dynamically generating values for 210PDF formats and 213setting in Factory 212

AltKey setting 158ambiguous methods calls 41ampersand (&) character in code 266analysis tools xxv, 327, 462analyzing data xxviancestor classes. See super classesAnd operator 255ANSI character codes 269ANSI strings 269ANY_TP type 471AnyClass type 36

assigning 34ANYCLASS_TP type 471apostrophe (’) in code 256applets 202application programming interfaces (APIs)

See also specific Actuate APIaccessing 337choosing libraries for 338, 488closing sessions for 353, 356developing with xxvierror checking for 349–350file naming conventions 339, 488initializing sessions 351, 355overview 326–328programming tasks for 341

selection guidelines for 329–331, 337setting up client stations for 340, 341uninstalling class libraries for 423

application servers xxiiiapplications

See also programsaccessing external 292, 304adding ActiveX controls to 474, 483building

with Requester API 350–357calling stored procedures from 188closing 353customizing xxv, 327debugging tools for 116deploying on Web 250deploying to client/server 334determining web context for 211developing 251, 256

with Actuate APIs 326, 329, 334, 464developing with ActiveX controls 482distributing 474e.reporting solutions for xxii, xxiiiembedding prebuilt functionality 474generating reports from 380, 428hanging 475including ActiveX controls with 486running Requester API 338, 339, 340sample xxviiisearch extensions for 327selecting clients 409standard interfaces and 20support for third-party 462testing 122

archive driver xxviarchiving tools xxviarguments 283

See also parametersC functions and 311, 312, 313, 314executable file as 352, 353, 358file names as 343getting names 345passing variables as 284procedures and 283, 285type restrictions for 312

arithmetic operators 254variants and 268

I n d e x 513

array types 263ARRAY_TP type 471arrays

adding multiple dimensions 264binary data and 269converting Java 319debugging Java 321declaring 263–264monitoring 126naming 53passing to C functions 315populating with different data types 263

As Any keyword 312As keyword 266, 283As Object keyword 317Asc function 269ASCII characters 258assigning

data types to variables 53, 252, 266–267methods to classes 58–59null values 43objects to variables 42strings to variables 268values to parameters 347, 396, 398, 442values to variables 42, 43, 252variables to classes 35

as any class 36variables to objects 24variables to parameters 25, 28variables to variables 37, 38

assignment operator (=) 252assignment statements 252

testing 449asterisk (*) as text string 394, 440asynchronous report generation 378, 381,

397, 427, 429at-sign (@) character in code 253, 267attaching to databases. See connectionsattributes 345

See also propertiesautomating repetitive tasks 280, 304, 330AutoScrollbar setting 207Available Libraries option 261Axdesk.dll 487Axview.dll 487

BBack buttons 492, 493Back method 478, 492back stack (web pages) 492, 493BackDisable event 479BackDisable method 492BackEnable event 479, 492background colors

DHTML converter and 204BalloonHelp method 162BalloonHelp property 162BAnd operator 254.BAS files. See source filesbase classes 4, 21

Actuate-specific 4Basic string 368Basic. See Actuate Basicbatch mode 327, 349, 380, 429bin directory 487binary data 269binary files 106binary string 368binary strings 269

comparing 270returning bytes in 269

BindColumn method 189BindParameter method 86bitwise And operator 254bitwise Or operator 254BLINK tag 223boolean type 318Boolean values

Java objects and 318performing calculations on 255returning 254

BOr operator 254borders

DHTML converter and 204Netscape Navigator and 222

bounding rectangle 212, 222bounds (arrays) 263Breakpoint icon 123breakpoints

running to 123setting 118, 119, 123

514 P r o g r a m m i n g e . R e p o r t s

BrioQuery 327, 462browser code

adjusting scaling factor 212aligning output for 207clipping output for 206–207, 213converting to PDF formats 213creating output dynamically 214debugging 208determining execution context 211displaying 208, 221generating dynamically 210–213including in report designs 205, 209supported formats 202

browser code functions 202, 211browser scripting controls

adding 205, 209, 210, 214to libraries 210, 215

adjusting size 212creating HTML forms with 210hiding 215nesting in designs 214, 215overview 202referencing global browser code in 209

browser source viewer 208BrowserClipping property 206, 207, 222BrowserCode method

overriding 210, 211, 212setting in Factory 212

BrowserCode propertychecking values of 208setting 205

BSTR strings 337, 368BSTR, defined 368buffers 10Build and Run command 65, 119Build method

AcReport 67AcReportComponent 68AcReportSection 69

build number 404, 449BuildFromRow method

AcControl 72AcFrame 71AcGroupSection 71AcReportComponent 68example for report bursting 242overriding 210, 212, 213

building ActiveX sample application 482building context-sensitive help 163building data streams 6, 76–82building reports 4, 64

report bursting techniques for 238, 239, 240

starting Factory process for 66–67with stored procedures 171, 176

built-in classesSee also Actuate Foundation Classes

built-in functions 250, 285See also functions; methods

built-in methods 30, 251See also methods

BundleReportInstance method 480, 493bundling report files 493Burst1.rod 240, 241Burst2.rod 240, 244bursting 238

examples 240button controls 483byte arrays 269byte type 318BYTE_TP type 471bytes 269ByVal keyword

arrays and 315C functions and 312, 315

CC functions

aliasing names for 313argument types for 312, 313calling 310, 314declaring 311–314including in programs 310, 311overview 310passing conventions for 312, 315–316pointers to 276renaming 313return values for 311reversing array dimensions 315type conversions 313–314, 316

C++ compilers 338C++ function calls 326, 327C++ sample application 351

I n d e x 515

C/C++ programsadding ActiveX controls 475creating Requester interface in 327displaying parameters in 371generating and displaying reports 368–

374selecting Actuate API for 337

cache 409calculated fields

getting values for 90–91calculations 260

cumulative totals 262powers and roots in 254procedures performing 252, 283temporary 262

calendar 273, 294Call keyword 285call stack 128Call Stack command 129callable methods 31CallBasicFunction method 481, 493calling

functions 202, 283, 285from ActiveX controls 480, 493from DLLs 310, 314restrictions for 459search extension API and 465

methods 40, 41procedures 281, 284

cancel buttons 503, 504canceling report generation 494CancelReport method 480, 494CanRunReport method 480, 494CanSeek method 79capitalization in code 257CascadeSecurity property 153case

code elements 257case sensitivity 257catalogs xxiiiCCur function 277CDate function 275, 277CDbl function 277changes, undoing in Component Editor 56changing

CLASSPATH variable 317data at runtime 108–113

default printers 348OLE objects 294, 295, 299–300, 302printers 413, 453properties 110–113report designs at runtime 104report parameters 336search extension default directories 463values 284variables 55web page scaling factor 212

Channel variable 95char type 318character arrays 269character codes 269character conversions 253character strings 269

See also stringscharacters in names 258, 313charts. See graphsCheckMessage interface 475Chr function 269CInt function 277class data types 265–266class IDs 44class libraries

See also Actuate Foundation Class libraryclosing 366, 423uninstalling 423

class namesin method calls 40returning 44scoping considerations and 22viewing 49

Class page (Component Editor) 49class protocol 4class scope 260, 280

default 22Class statement 18Class Variable dialog box 53Class Variable page 140class variables 24–29

declaring 263types supported 24

classesSee also Actuate Foundation Classesassigning methods to 58–59assigning variables to 35, 53, 260

516 P r o g r a m m i n g e . R e p o r t s

classes (continued)checking object status within 44customizing 35declaring 18–20

scope and 21variables private to 26

defined 18defining characteristics of 6defining for Java 317defining structure of 6deriving new 4, 20determining scope 22displaying list of 35displaying variables in 50extending functionality of 4, 6, 30getting information about 48, 49inspecting 48–49instantiating 74–75making private 49methods declared in 30naming 40, 257nesting 21, 23overriding methods and 57overview 4, 17, 18referencing 20, 22relationships described 20scope-resolution operator for 22subprocedures in 282testing status 44types described 4, 6user-defined types as 276viewing properties 51visibility 20

classifying data 264CLASSPATH variable 317cleanup code

API functions for 342, 353Factory services 66search extensions 463

cleanup functions 310clearing

breakpoints 123programs from memory 125status stack 503

client applications 329closing 353creating 351, 354

deploying to 334developing 335, 336displaying reports for 501, 502, 503, 504installing ActiveX controls for 488installing custom search extensions

for 466moving through reports 478running from Requester API 340, 341running on different platforms 330running reports for 353selecting clients for 409setting up accounts for 352

client code 409Client Integration Technology xxvclient-side reporting 409Clip property 207clipping

browser output 206, 213frames on report pages 73

ClipToControlSize setting 207CLng function 277clock 273Close function 463, 468Close method 306CloseReportExecutable method 480, 495CloseReportInstance method 478, 484, 495closing

API sessions 353, 356class libraries 366, 423connections 68, 70, 353data adapters 78, 81data streams 68, 70external applications 306input data sources 80OLE Automation objects 306report files 376reports 477, 484, 495search definition files 468

clusters xxvcode

See also Actuate Basicaccessing Java objects in 318accessing variables in 26adding breakpoints 123adding comments 256conventions for 256–258debugging 115

I n d e x 517

code (continued)displaying browser 208displaying specific methods in 128editing 48editing restrictions 55, 56, 60, 61examples for 258extending functionality 310getting values for 31handling invalid methods in 58implicit declarations and 260indenting 257language elements in 252–256locating errors in 117programming conventions for 251resuming execution of 124running 119setting watches 127startup/cleanup

Factory services 66Requester API 342, 353search extension API 463

stepping through 123, 125stopping execution of 125viewing comments in 49writing custom browser 209, 210

COleDateTime function 421, 455collating 411collection classes 14collections 15colon (:) as separation character 257color printing 411colors

DHTML converter and 204numbers representing 265setting as transparent 215

column delimiters (search extensions) 468column names

duplicate in stored procedures 175in search extensions 469

columns 81binding to data rows 189generating values at runtime 104getting from stored procedures 194reading values 82setting search extension data types for 472specifying for stored procedures 176

comments xxxiv

adding to source code 256viewing 49

commonly-used commands 159company names and logos 106Compare method 93comparison operators

overview 254precedence for 256

comparisonsconditions as 286expressions 254object reference variables 45, 255strings 255, 270

compilation errors 116compiled libraries 488, 489compilers 32, 337compiling search extensions 466completion notices 66component class 5Component Editor 34

accessing control values 110, 111adding company names and logos 107adding variables 24, 25connecting to flat files 95creating computed variables 90creating methods 58–59creating variables 53–55debugging with 118deleting methods 61deleting variables 56displaying methods 60dynamically embedding images 106editing methods 60editing variables 55filtering methods 52, 61filtering variables 50implementing browser scripting 205, 209inspecting classes 48–49inspecting methods 51–52inspecting variables 50–51interface described 48overriding methods 56–57overview 47properties in 74running 49setting properties 26undoing changes 56

518 P r o g r a m m i n g e . R e p o r t s

Component Gallery (Visual C++) 475Component Properties command 49component references (defined) 68component relationship map 66components

addingin Design Editor 22to report designs 251

appearing in structure pane 5creating 68

at runtime 104–106customizing 4instantiating 75, 104referencing 68, 74, 78returning references for 112

Components command 483compressed images 301computed columns

getting values for 90–91concatenation operator (&) 256concrete classes 6conditional expressions 382, 430conditional filters 91, 92conditional statements

control structures as 286setting at runtime 28

conditionally instantiating components 75conditions

applying to properties 108, 110control structures and 286instantiating components with 104

configurations 326data streams 76local 336printers 348Requester API and client-server 335

conjunction 255connection classes 5, 8connection components

adding 85placing in data streams 83, 84placing in sections 83, 84

connection handles 376, 426connections 83–86

API applications and 334as transient objects 45closing 68, 70, 353

customizing 83, 85establishing report server 334, 351failing 84flat files 95generic 5handling multiple 84implementing programmatically 478implementing through API functions 376,

425, 495input data sources and 80instantiating 8, 69, 83local reporting and 354multiple requests and 357precedence 84relationships for 85sharing 83SQL databases and 84

ConnectToServer method 478, 495Const statement 267constants 253, 258

declaring 267default values as 383enumerations and 265type definitions and 265

constructs 257container applications

See also OLE applicationsaccessing data in 294accessing OLE objects in 304defined 292

container objectsadding 296, 297, 298creating content for 68embedding objects in 5instantiating contents 75monitoring contents 126

containersframes as 12reports as 7

content management systems xxiiicontent structure (Factory) 67content-creation protocol (Factory) 67–72Contents buttons 485Contents window 475

opening 485, 506Contents_Click event 485context block (scripting control) 203, 205

I n d e x 519

context menus 14adding items 160creating 159–162customizing 161displaying 157, 161

context-sensitive help xxxii, 163–165Continue command 124Continue icon 124control buttons 483control classes 6, 13, 14control structures 250

exiting 287overview 285

control window. See ActiveX viewing window

ControlKey setting 158controlling program execution 123controls 156

accessing values 110, 110–113adding

for stored procedures 176adding to frames 111changing properties for 110changing values 108customizing 14, 108default scope for 22displaying 214instantiating 6, 14naming 23nesting 23overview 327providing help with 162retrieving content for 71, 72setting conditional properties for 108stacking 214

conversions 267binary to strings 106C data types 313–314C functions 316data types 253, 277inches to millimeters 416Java arrays 319Java strings 319Java types 318–320numbers to characters 253numbers to dates 275numbers to strings 270strings to binary 107

strings to currency 384, 399, 432, 444unintended 268variants to dates 275XML to DHTML formats 228, 230, 234

ConvertBFileToString method 106ConvertStringToBFile method 107Copy Link command 160copying

dynamic link libraries 340executable files 341functions 360hyperlinks 160strings from Java strings 319

copyright information 492CorVu modules 327, 462counter variables 272counters 24, 45, 287CPointer data type 314, 316

assigning values 276declaring 265stored procedures and 194, 195

CPOINTER_TP type 471CreateJavaObject function 317creating

applications 350, 354balloon help 162–163browser-specific menus 215, 218components 68

at runtime 104–106context menus 159–162context-sensitive help 163–165data rows 6, 81–82data sources 80, 81, 188dynamic hyperlinks 358–360HTML forms 202, 210, 222Java objects 317labels 36, 38methods 58–59multi-table reports 99, 101objects 34–37parameter values files 425, 459queries 81, 86reports 251report-specific online help xxxivsource files 281user-defined methods 251variables 53–55, 261

creating balloon help 165

520 P r o g r a m m i n g e . R e p o r t s

creating context menus 160, 161creating context-sensitive help 163creating queries

for report bursting 242creating reports

report bursting techniques for 238, 239, 240

with stored procedures 171creating stored procedures 171–174

for Oracle8 data sources 182–188criteria. See parameterscross-platform reporting xxivcrosstabs 4CSng function 277CSS attributes 207, 222CStr function 277CtrlKey Bor AltKey setting 158cumulative totals 262currency

converting strings to 384, 399, 432, 444getting as current value 399, 443getting as default 383, 431setting as default 420, 454

currency controls 14, 272Currency data type

assigning values 272, 273C functions and 313converting to 277declaring 267described 265returning as current 399, 443returning as default 383, 431specifying parameters as 419, 453

currency variables 272CURRENCY_TP type 471current date 274current release xxicurrent scaling factor 212current value

defined 399, 443getting 347testing for 396, 398, 442

CurrentPage method 478, 496cursor variables 194, 195cursors (SQL)

allocating 85, 189instantiating 9, 85

opening 80custom browser code

adjusting scaling factor 212aligning output for 207clipping output for 206–207, 213converting to PDF formats 213creating output dynamically 214debugging 208determining execution context 211displaying 208, 221generating dynamically 210–213including in report designs 205, 209supported formats 202

Custom Browser Code Editor 209, 210custom classes 35custom data sources

creating 80, 81flat files as 94, 95, 96generating computed columns from 90

custom data streams 90–103applying filters to 91–94creating 90

custom methods. See user-defined methodscustom Requester interface 383, 431custom search extensions 466CustomDHTMLFooter method

overriding 216CustomDHTMLFooter property

restrictions for 222setting 210

CustomDHTMLHeader methodoverriding 216

CustomDHTMLHeader propertyrestrictions for 222setting 210

customer profiles xxiiCustomer Support xxviiicustomizing

applications xxv, 327components 4connections 83, 84controls 14, 108data filters 81, 92objects 37reports xxv, 31, 89Requester 366–368, 392, 437

CVar function 277

I n d e x 521

Ddata

accessing xxiiifrom external applications 81, 292, 304in input data sources 79in OLE objects 294, 295in SQL tables 85methods specific to 31

analyzing xxvibinary strings as 269changing at runtime 108–113classifying 264collecting 6filtering 80, 91, 98formatting for XML reports 226getting values at runtime 28grouping 6, 70maintaining in multiple sources 295managing in data streams 10processing 6, 9retrieving 79, 80, 81, 82

from data adapters 6, 78from data streams 76from external data sources 6from flat files 94from multiple sources 98–103from nonstandard sources 90from text files 90

retrieving from stored procedures 176–177sharing 292, 304sorting 70, 93storing values 39

methods and 29variables and 113

tracking in multiple sources 295user-defined values as 275variants as 267

data adapters 79base class for 9closing 78, 81connections in 83filtering with 92forming data streams with 78implementing 80instantiating 78, 81opening 78, 81

retrieving data from 6sorting with 93

data controls 13data extraction 462, 478data filter classes 6, 80data filters 80–81

applying to custom data streams 91–94base class for 9connecting to data streams with 76, 78creating select 92–93creating sort 93–94customizing 81, 92defined 76instantiating 6, 10nonstandard 90parameters as 28processing rows in any order 80specifying multiple data sources for 98–

103data integrity xxivdata row class 6data rows 9

adding to group sections 71binding columns to 189creating 6, 81–82defining characteristics of 6filtering out selected 91–93getting from flat files 96instantiating 6, 81processing in any order 80retrieving 6, 78, 80, 81

from data streams 69from nonstandard data sources 90from stored procedures 189with database cursors 85with filters 91

returning search extension 470sorting 70, 93tracking position 85

data sets 188data sorter 10data source class 6data sources

accessing data in 79base class for 9building data streams with 76, 78creating 80, 81, 188

522 P r o g r a m m i n g e . R e p o r t s

data sources (continued)customizing 80, 81defined 76external applications as 292, 304filtering multiple 98–103flat files as 94implementing data adapters for 80instantiating external 6maintaining data in multiple 295nonstandard 90overview 80placing connections in 85retrieving data from 81tracking data in multiple 295

data stream classes 9data stream configurations 76data streams

as transient objects 45building 6, 76–82closing 68, 70connecting to 69, 83connection precedence in 84customizing 90–103getting data rows from 69instantiating 69managing data in 10placing connection components in 83, 84reusing 83with multiple data adapters 78

data type mappings 199data types 264–265

See also specific typeassigning to parameters 347assigning to variables 53, 252, 266–267C functions and 312, 315–316

type conversions for 313–314class specific 265–267constants and 267conversion functions for 277converting Java 318–320converting to common type 253creating user-defined 275–276declaring in procedures 283, 284getting as parameter defaults 346getting report parameter 396, 398, 442getting specified as current 347mismatched 268

mixing in expressions 253monitoring 126passing multiple 312program-specific 265returning 253setting as default 347setting search extension 471stored procedures and 179, 198variants and 267

database connection classes 5database cursors

allocating 85, 189instantiating 9, 85

database example filefor Oracle databases 184

database schemaverifying stored procedures 170

databasesaccessing

for stored procedures 173as input sources 76base class for 9calling stored procedures in 188connecting to 5, 83–86e.reporting solutions for xxii, xxiiiflat files as 80, 94frequent operations in 280improving performance 168interfaces for 5SQL support for 84

DataInputFile variable 95dataTypes array 472DataValue variable 108date controls 14Date data type

assigning values 273C functions and 316converting to 277described 265returning as current 400, 444returning as default 384, 432specifying parameters as 420, 454

date expressions 254Date function 274date functions 274date variables 273date/time literals 273, 274

I n d e x 523

datesarithmetic operators and 254assigning values 273expressed as C++ doubles 385, 400, 421,

433, 445, 455formatting 274–275getting as current value 400, 444getting as default 384, 432getting current 274setting as default 420, 455setting from C++ 368valid 265, 274

DateSerial function 274Day function 274DB2 database connections 84debug options 122debugging

access control lists 120browser code 208Java objects 321methods 118, 128overview 116reports with page security 120with page level security 139

debugging sessionsadding breakpoints 123adding watches 127controlling program execution in 123monitoring values 125saving parameters for 122starting 118stepping through code 123, 125stopping 125tracing object reference variables 126viewing stack 128

debugging tools 116debugging window 117DebugOption property 208decimals 272declarations

arrays 263–264C functions 311–314class 18–20constants 267functions 282

in Visual Basic forms 361global procedures 281

global variables 261instance variables 24local variables 262nesting 20object reference variables 34–36private variables 26procedures 282public variables 26static variables 24strings 268subprocedures 282type restrictions 312user-defined types 275variables 260–263

as specific type 266C++ sample code for 351type-declaration characters and 266user-defined types and 276

declarations section (source code) 261Declare statement

Alias keyword 313As Any keyword 312ByVal keyword 312, 315C functions in 311, 312, 313Null keyword 315specifying DLLs in 360

DEF files. See search definition filesDefault Action command 160, 161default mouse actions 157default paths 260default printers 353

changing 348, 413, 453specifying 410

default scope 22, 23, 24default values

Currency data type as 383, 431Date data type as 384, 432defined 431Double data type as 385, 433getting 346Integer data type as 386, 434setting 347setting report parameter 96String data type as 387, 388, 435, 436testing for 396, 398, 405, 442, 449

defaults 37DefineProcedureInputParameter method 189

524 P r o g r a m m i n g e . R e p o r t s

DefineProcedureOutputParameter method 189, 198

DELETE queries 86deleting

methods 61references to obsolete properties 117temporary files 107variables 56

delimiters (search extensions) 468deployment xxiii, xxvii, 250

supported environments for 338derived classes

creating 20restrictions for 4testing for 44

descendant classes. See subclassesDesign Editor 104

adding components with 22creating multiple input filters 99creating reports 251creating select filters 92creating sort filters 93designing reports with 18, 74displaying group section keys 109editing OLE objects 299, 300getting data from flat files 94inserting OLE custom controls 301inserting OLE objects 297, 298specifying data in 108subclassing reports 239

Design Emporium product catalog 234Design Properties command 120Design Properties dialog

setting debug options 122simulating page security viewing 120

design tools xxiv, 251designing e.Spreadsheet reports xxv, xxviidesigning reports xxiv

testing design 138, 141with page level security 135–140, 149with stored procedures 171, 176

designs 251adding browser scripting 205, 209adding objects from external

applications 292creating at runtime 104–107creating for flat file data sources 94, 97

creating with Design Editor 18, 74multiple data sources and 99, 102stacking controls in 214

Desktop ActiveX controlsSee also ActiveX controlsaccessing Actuate Basic functions

from 481adding 474canceling report generation from 494closing report executables from 495methods calls for 491opening report executables 500overview 327, 474running reports from 479, 494, 503, 504Visual Basic example for 482

Desktop control window 484, 485Desktop controls 483detail graphs 14detail reports 238

associating with master reports 243, 245creating from group sections 244, 245examples for 240, 241, 242, 243naming 243

Developer Workbenchsetting XML properties 230

developers 250, 256, 326developing applications

for Windows operating systems 474with ActiveX controls 477, 482with Requester API 350–357with search extension API 464–466

developing reports xxv, xxxivdevelopment cycles 329development languages xxvdevelopment tools xxv, xxvi, 338DHTML converter

generating HTML code 205processing scripting controls 202, 209properties ignored by 207scaling controls 212

DHTML formscreating 215submitting requests for 217

DHTML reportsSee also web pagesconverting to PDF formats 213debugging browser code for 208

I n d e x 525

DHTML reports (continued)displaying xxiiidisplaying controls in 214generating 64, 209, 228special characters in 202, 204viewing 202

DHTMLForm scripting control 215–217subclassing 217

DHTMLMenuControl scripting control 215, 218–222

subclassing 220dialog boxes

embedding ActiveX controls in 475prompting for parameters in 366setting language for 499

Dim statement 260creating OLE Automation objects 305creating text strings 268defining instance variables 24defining local variables 262defining object reference variables 34, 317dynamic arrays and 264procedures and 262specifying data types 266

dimensions. See arraysdirectories 409

ActiveX installations and 486default for search extensions 463

directory names 409See also paths

disconnecting from databases 84disconnecting from reporting servers 353,

377disjunction 255display layouts 505Display Sample Data option 205displaying

classes 49comments 49context menus 157, 161controls 214custom browser code 208, 221DHTML reports xxiii, 202error messages 117images 107methods 51, 60, 111, 128online documentation xxxii

predefined classes 35properties 51report parameters 394, 440reports xxvii, 155, 424, 457

ActiveX controls and 474, 485API functions for 348in C++ applications 368in Encyclopedia volumes 477in Visual Basic forms 362, 366in web pages 64, 202locally 336, 349, 356Requester API and 335, 336with Actuate Viewer 214, 341, 411, 453,

466with PDF converter 213–214with security restrictions 134

variables 50, 125web pages 212

displays 6, 265distributing applications 474DIV tags 205, 222division 254DLLs

ActiveX controls and 487calling C functions from 310, 314copying 340initializing 405Java requirements and 316procedures in 315relative paths and 360search extension 466selecting for ActiveX API files 488selecting for Requester API files 338–340selecting for Windows environments 339specifying 312, 360updating 338, 488

Do...Loop control structure 286do_executereport.jsp

Active Portal JavaServer Page 217document files

ActiveX controls and 476bundling with report executables 493described 343printing from Requester API 406, 450viewing 424, 457

document type definitions (DTDs) 226

526 P r o g r a m m i n g e . R e p o r t s

documentation xxixaccessing xxxiioverview xxviisyntax conventions for xxxvtypographical conventions for xxxv

dollar sign ($) character in code 267, 273dot notation 39, 40, 276Double data type

assigning values 272, 273C functions and 313, 316converting to 277declaring 267described 265Java objects and 318returning as current 401, 445returning as default 385, 433specifying parameters as 421, 455

double quotation marks in strings 268double type 318DOUBLE_TP type 471double-precision floating-point numbers. See

Double data typedrawing tools 14Drawing/Graphics palette 202DROP TABLE queries 86drop-down menus. See menusDT_TIME_TP type 471duplex modes 412duplexing 412duplicate names 41, 59dynamic arrays 264dynamic content delivery 251Dynamic HTML. See DHTMLdynamic hyperlinks

creating 358–360dynamic-link libraries. See DLLs

Ee.Analysis Option xxvie.Business applications xxiiie.Report Designer xxiv

developing for 334launching local copy of 336local reporting and 336, 355selecting client products for 409

e.Report Designer Professional xxvcustom browser code in 202

debugging tools for 116defaults 37developing for 334editing variables 55extending functionality of 250launching local copy of 336local reporting and 336, 355programming with 18Requester programming examples for 337resolving ambiguous method calls 41selecting client products for 409transient objects and 45

e.Report Engine xxviie.Report Option xxvie.reporting solutions xxi, xxiiie.reports 250

See also reportse.Spreadsheet Designer xxv, xxvie.Spreadsheet Engine xxviie.Spreadsheet Option xxvie.Spreadsheet reports

designing xxv, xxviigenerating xxvi

E_JAVAEXCEPTIONOCCURRED error 320E_JVMCLASSNOTFOUND error 320E_JVMCLASSPATHNOTFOUND error 320E_JVMCREATEJVMFAILED error 320E_JVMCREATEOBJECTFAILED error 320E_JVMINVALIDJAVAHANDLE error 320E_JVMMETHODFIELDACCESSFAILED

error 320E_JVMTYPECONVERSIONFAILED

error 320editing

data in OLE objects 294, 295, 299–300methods 60–61source code 48undoing changes 56variables 55

Editor. See Component Editorelectronic catalogs xxiiielements. See arraysellipse control 14Ellipsis property 207Else keyword 286ElseIf keyword 286embedded quotation marks 268, 272

I n d e x 527

embeddingimage controls 106–107, 295OLE objects 292–299

guidelines 296linking vs. 294

empty methods 4, 20empty strings 392, 437, 497empty variables 44EMPTY_TP type 471Encyclopedia

See also volumesmanaging volumes 326

Encyclopedia volumeaccessing items 335, 351viewing reports in 477

Encyclopedia volume. See Encyclopedia; volumes

Encyclopedia volumesgenerating documents for xxv

End User Desktop xxiv, 331, 474canceling report generation from 494displaying reports from 411, 453printing from 336, 406, 450running 378, 427running remotely 410, 453selecting client products for 409setting location of 410, 452viewing reports 424, 458

enhancements 338, 488enterprise reporting xxii, xxiiienumerations (enums) 265

returning data types as 398envelopes 415, 417environment variables

Requester API and 341UNIX platforms 340

equal to operator (=) 254, 255equivalence 255Eqv operator 255Erd directory 409Erdpro directory 409Err() function 320erroneous values 117error codes

getting 349, 389report generation 381, 429

error messagesAPI function calls 389, 494

displaying 117getting 391, 437, 496JavaScript 208setting language for 499

error-handling routines 408errors

ActiveX controls 481checking for 349–350, 389, 391, 437

in browser scripting controls 208fixing 116Java objects and 317, 320locating in code 117printing 407, 451types described 117

escape characters 202, 204Essential Property option 55Essential Property setting 26Eudt directory 409events 31

ActiveX controls 479, 484default mouse actions 157mouse 156, 157report viewing 156report-viewing 156–157search extensions 468

examining variables 125example database files

Oracle8 stored procedures 184Example folder xxviiiexample reports

report bursting techniques 240examples 258

accessing stored procedures 193, 195creating browser-specific libraries 215creating computed columns 90creating menu items 161embedding ActiveX controls in

dialogs 475filtering in custom data streams 91filtering nonstandard data sources 92mouse event actions 158Requester API and Actuate Basic 358–360Requester API and C++ 368–374Requester API and Visual Basic 360–368Requester API programming 337setting executable file names 349sorting data 94

528 P r o g r a m m i n g e . R e p o r t s

Excel applications 299, 304, 462changing 305creating objects for 305searching 327support for 292

Excel spreadsheetsdeveloping for xxv, xxviigenerating xxvi

exceptions 320exclamation point (!) in code 267exclusion 255executable files 488, 489

ActiveX controls and 476as report generation argument 352, 353,

358bundling with report documents 493closing 376, 495copying to client stations 341described 343generating reports from 377, 408, 426, 452,

503, 504getting parameter groups in 391, 394, 437,

440getting parameter values in 346getting specific parameter in 392, 395, 438,

441naming 352, 355opening 407, 452, 485, 500running 64, 349

Execute methodSQL statements 86stored procedures 189

executing programs 123line by line 123

executing queries 86executing reports

API functions for 348based on specified parameters 342batch mode for 327, 349, 380, 429C++ sample code for 353, 370default values and 383, 431from ActiveX controls 479, 485, 503, 504from End User Desktop 410, 453from parameter values files 352, 353, 355,

356locally 336, 349

sample application for 354

on report server 500Requester API and 335, 336Visual Basic sample code for 356

executing stored procedures 189Exit buttons 484Exit Do statement 287Exit For statement 287Exit Function statement 287Exit Sub statement 287Exit_Click event 484explicit declarations 260exponentiation 254, 273expressions

arithmetic operators and 254assignment statements and 252calling procedures from 284, 285comparing 254conditional statements and 286data type functions in 277embedding quotation marks in 272literal strings in 268logical operators and 255operator precedence in 256overview 253

external applications xxivaccessing data in 294accessing objects in 292, 304closing 306opening 305

external data sources 6, 81external functions

calling 310, 314copying 360

external hyperlinksevent handling for 479

external objects 321external security information 134external source code files 202Externally Defined Data Type option 54extracting data 462, 478extracting days from dates 274extracting report executables 500

FF1 key xxxiiFactory method 65

I n d e x 529

Factory servicebuilding data streams 76–82building reports 66–67content creation protocol for 67–72data row processing for 81defined 64establishing database connections 83–86instantiating classes 74–75overview 64–65page-creation process 72–74processing report content and creation 65starting 65, 66

failures 496fanfold paper settings 415Fetch method

AcDataAdapter 78AcDataFilter 81AcDataSource 80overriding

for data filters 91, 92for dynamically embedded images 106for flat file access 97for multiple data sources 99, 100, 102for stored procedures 189, 196to populate data rows 90

fields 81See also columnsaccessing in Java objects 317, 318

file cache 409file names 260, 380, 429

as arguments 343iServer files 476specifying 349, 476

file naming conventions 339, 488file numbers 379, 408files

accessing data in flat 94–98accessing external 292accessing on servers 376, 426bundling report 493closing 376copying executable 341deleting temporary 107generating multiple report 238generating report 342logging report generation to 66opening 407, 452, 470, 485, 500

overwriting generated report 378, 427referencing in API function calls 343report described 342running executable 64, 349server connections and 477specifying local names for 476specifying output 352, 355storing images in temporary 107

fill patterns 207FillPattern property 207filter options (Method Filtering) 52, 60, 61filter options (Variables Filtering) 50filtering data 80, 91, 98filters 80–81

applying to custom data streams 91–94applying to methods 52, 61applying to variables 50connecting to data streams with 76, 78creating merge 101creating multiple input 99creating select data 92–93creating sort data 93–94creating union 99customizing 92data-specific 76instantiating 10nonstandard 90parameters as 28processing data in any order 80specifying multiple data sources for 98–

103FindContentByClass method 112Finish method

AcControl 72AcDataAdapter 78AcDataFilter 81AcDataSource 80AcFrame 71AcGroupSection 71AcReportComponent 68AcReportSection 70overriding

for flat file access 97for generating reports 66for multiple data sources 100for runtime properties 108to customize data streams 90

530 P r o g r a m m i n g e . R e p o r t s

FinishFlow event 73FinishPage event 73FirstPage method 478, 496fixed-point numbers 272, 273fixed-size arrays 264flat file databases

connecting to 95getting data from 80, 94–98

float type 318floating-point division 254floating-point numbers

data as 420, 455data types for 272, 273date variables as 273getting as current value 401, 445getting as default 385, 434mathematical operations on 254setting as default 421, 456

flow (page layouts)placing frames in 6report viewing events and 156

flow class 6fonts

applying to web pages 222footers

building 74generating content for 72

For...Next control structurescounter variables in 272declaring 287

FORM tag 210, 216Format function 270formatting

dates 274–275displays 265strings 270

formatting datafor XML reports 226

Formula One product suite xxviiformulas. See expressionsforwarding messages 475foundation classes. See Actuate Foundation

Classesfractions 272, 273frames 156

accessing control values in different 113adding browser scripting controls 209adding controls 111

adding OLE custom controls 300adding OLE objects 296, 297, 298adding to reports 12building 10building dynamically 104, 105creating content for 6defining characteristics of 6determining page styles for 73generating content for 68, 71, 72instantiating 71placing in flows 6placing on pages 73

freeing resources 423Function statement

C functions in 311defining procedures from 281, 282

functions 250See also methodsaccessing external 310ActiveX alphabetical reference 491calling 202, 283, 285

from ActiveX controls 480, 493from DLLs 310, 314restrictions for 459search extension API and 465

copying 360CPointer data types and 276creating mapping 154date/time specific 274declaring 282

in Visual Basic forms 361error codes for API 389error handling for 349–350exiting 287instantiating classes and 18referencing report files in 343Requester API categorized 341–350Requester API reference 375returning object information 44search extension API categorized 462–464search extension API reference 467specifying multiple options for 378, 427stored procedures 182, 184subprocedures vs. 283type conversions 277undocumented 459

fundamental data types. See data types

I n d e x 531

GGenerateXML method 230, 233generating

reports xxvgenerating HTML tags 205generating report files 342

report bursting techniques for 238generating reports

API functions for 377, 426canceling requests for 494content creation protocol for 67–72for DHTML pages 228from ActiveX controls 494from report files 408, 452from Visual Basic forms 362, 365from Visual C++ forms 369, 370getting status reports for 408initializing global variables for 66overview 63, 64prioritizing requests for 418Requester API and 334sending completion notices for 66setting parameters and 397, 443

generation options 378, 379, 427, 428generic connections 5GetAppContext function 211GetClassID method 44GetClassName method 44GetColumnDelimiter function 464, 468GetControlValue method 110GetJavaException method 320GetKeyValue method 109GetLastError method 478, 496GetMostRecentListCount method 478, 497GetMostRecentListItemAt method 479, 497GetName function 463, 469GetOutputParameter method 189, 195GetParameters function 463, 469GetPosition method 79GetProcedureStatus method 189, 195GetReportContext function 211GetReportScalingFactor function 211, 212GetStatusCount method 497GetStatusMessageAt method 498GetText method 140

default value for 213overriding 210, 211, 213, 214

GetUserACL method 140, 152GetUserAgentString function 211GetXMLText method 233global custom browser code 209global procedures 281global scope

as default 24procedures and 280variables and 260

Global statement 34, 260, 261global variables

caution for using 113, 261creating 261declaring 260, 261initializing 66, 262monitoring 125overview 260storing values in 113watching 127

GlobalDHTMLCode propertyrestrictions for 223setting 209

GoToPage method 479, 498GrantExp property 134, 137graph controls 13graphical objects 13graphical user interfaces 329, 494graphics controls (third-party) 488graphics files

See also imagesaccessing 292embedding in reports 106, 295linking to reports 294

graphs 156adding from external applications 292instantiating 14

greater than operator (>) 255greater than or equal to operator (>=) 255group boundaries 244group sections

creating content for 70creating subreports with 244, 245displaying keys for 108initializing 71

groupingdata 6, 70parameters 344, 392, 437

GUIs 329, 494

532 P r o g r a m m i n g e . R e p o r t s

HHalt command 125hard-coding path names 360HEAD tags 209header files (C/C++) 337header files (search extensions)

creating 466including 469

headersbuilding 74generating content for 72

help xxxii–xxxivbuilding context-sensitive 163–165creating balloon help text for 162–163providing online 160, 162–163, 165

help buttons 163Help command 160, 163Help menu xxxiihelp topics xxxiiHelpText property

not setting 160hexadecimal numbers 265hidden parameters 393, 439hide text attribute 394, 440hierarchy 4, 20home page (Actuate) xxviiHorizontal duplex mode 412Horizontal property 207HP-UX compilers 338HP-UX servers 340HTML forms 202

creating 210, 222HTML reports

See also web pagesdynamically resizing elements in 212

HTML tagsgenerating 205searching for 208

HTTP requests 211hyperlinks 160

activating context menus for 160adding to master reports 243, 245copying 160creating dynamic 358–360event handling for 479

generating reports from 327searching with 14

Hypertext Markup Language (HTML) 202See also HTML

II/O. See input; outputIBM AIX compilers 338IBM AIX servers 340IBM tables

creating stored procedures 168icons in Variables window 126identifiers. See symbolsIDs

associated with names 192getting object 44

If...Then control structure 286If...Then...Else control structure 286image controls 14

adding 214images

accessing from external applications 292display problems with 301displaying 107, 214embedding in reports 106, 295including at runtime 106–107linking 294printing 417scaling 417storing in temporary files 107

Imp operator 255implication 255implicit declarations 260include files. See header filesIncludeHeader function 464, 469incorrect values 117indenting code 257index (online documentation) xxxiiindex numbers (arrays) 263Information Delivery API xxviinformation delivery solutions xxi, xxiiiinformation objects xxvinformational error messages 117Informix tables 8inheritance 20

ambiguous methods calls and 41

I n d e x 533

inherited methodsdebugging 118overriding 56

initializingobjects 68Requester API 351, 355, 406

in Visual Basic forms 362variables 66, 262

in-place editing 299input 503input adapters

accessing multiple 100closing 81filtering 98opening 81referencing 100

input filter classes 80input filters

creating multiple 99instantiating 92, 98

input parameters 177adding to stored procedures 179–182defining 189returning columns with 194sample values for 171testing for 179

input records 81creating data rows for 6filtering data in 91manipulating data in 90

input sources 76accessing data in 79customizing connections for 85data streams with multiple 76opening 80retrieving data from 80

InputParameters function 463, 470Insert Object dialog box 293

adding OLE custom controls 300, 301embedding OLE objects 297, 298linking OLE objects 297opening 296

inspectingclasses 48–49methods 51–52parameters 336

variables 50–51, 125, 127installDir parameter 409installing

ActiveX controls 486installing online documentation xxxiiinstance methods 318instance variables

creating 54described 24monitoring 125scope 55watching 127

INSTANCE_TP type 471instantiating

classes 74–75components 75, 104connections 83data adapters 78, 81data rows 81objects 36reports 66SQL statements 85

instantiation 74abstract classes and 4based on conditions 104concrete classes and 6declaring variables for 24

InStr function 269InStrB function 269int data type

Java objects and 319int type 318INT_TP type 471integer controls

assigning values 272–273instantiating 14

Integer data typeassigning values 272C functions and 313, 316converting to 277declaring 266described 265Java objects and 318returning as current 401, 446returning as default 386, 434specifying parameters as 422, 456

534 P r o g r a m m i n g e . R e p o r t s

integersSee also numbers; integer controlsdividing 254floating-point numbers vs. 254overview 272rounding 253valid ranges for 265

integrated content xxivinterfaces

ActiveX controls and 474Actuate programming 326creating Windows-based 329database-specific 5enabling/disabling user elements 494support for standard 20

internal tools classes 14Internet Explorer

example implementation for 215–222generating output for 211scripting code for 204, 205

BrowserClipping property in 206, 207invalid methods 58invalid symbols 313Is operator 44, 45, 255IsDate function 275iServer

building applications for 351generating reports from 410local reporting and 336making multiple requests 357managing multiple xxvnaming files for 476overview xxiiprogramming interfaces for 326running multiple xxvwith Requester API 335

iServer Systemoverview xxv

IsKindOf method 44issuing requests 342iterators 15, 100

JJava applets 202Java class definitions 317Java Development Kit (JDK) 316Java exceptions 320

Java Native Interface (JNI) 316Java objects xxvii

accessing 316, 317–318creating 317debugging 321invoking methods in 317, 318type conversions for 318–320

Java programsdeveloping for xxvii

Java Runtime Environment (JRE) 316Java Virtual Machine 316JavaScript 202, 222

debugging 208error messages 208

JDK support 316JNI support 316JRE support 316

Kkey fields 70

See also sort key columnskey presses, mouse events and 158Key property 70keys. See sort keyskeywords

C functions and 313operators as 253restrictions 258

Llabel controls 14labels

changing characteristics of 39creating 36, 38DHTML conversions and 203

Landscape orientation 413language extensions 250language symbols 499language. See Actuate Basiclanguage-specific resources 499large reports

report bursting for 239, 240LastPage method 479, 498LAYER tag 205, 222layouts. See page layoutsLCase function 271

I n d e x 535

LCase$ function 271LD_LIBRARY_PATH variable 340leading spaces 270LeadTools DLLs 488leaf classes 6Left function 269LeftB function 269left-to-right orientation 505less than operator (<) 255less than or equal to operator (<=) 255Let statement 43Lib statement 312LIBPATH variable 340libraries 4

ActiveX controls and 487adding scripting controls 210, 215C functions in 310, 312closing 366, 423designing with xxivinitializing 405relative paths and 360scoping conventions in 24selecting for ActiveX API files 488selecting for Requester API files 338–340selecting for UNIX environments 340selecting for Windows environments 339specifying 312

library name argument 312Library Organizer

adding source files 310creating source files 261, 281opening 261selecting source files 261, 281

library path (UNIX) 340libreqstapi.sl 340libreqstapi.so 340libreqstapi_share.a 340licenses 474lifetime. See scopeLike operator 255line continuation character (+) 257line controls 14linked lists 15

comparing controls in 45LinkExp property

overview 243report bursting example 245

linkingimages to reports 294OLE objects 292–299

embedding vs. 294guidelines 296

links (online documentation) xxxiiLinkToExp property

not setting 161lists

accessing contents 15comparing controls in 45getting number of items in 497instantiating page 67

literal dates 273, 274literal strings 268loading language-specific resources 499LoadResource method 498local configurations 336local file names 476local report generation 334, 500local reporting 334, 336, 354local scope 260local variables

declaring 262monitoring 125overview 262retaining values for 262watching 127

locales 499e.reporting solutions for multiple xxii

log files 66logarithms 273logging into report server

C++ example for 352logic errors 117logical operators 255logical paper sizes 412, 416logical values

performing calculations on 255returning 254

logos 106Long data type

assigning values 272C functions and 313, 316converting to 277declaring 266described 265

536 P r o g r a m m i n g e . R e p o r t s

long statements 257long type 318LONG_TP type 471loops 250

adding to programs 285arrays and 263exiting 287incrementing 287local variables and 262nesting 287

LRX (Live Report Extension) xxviiLTrim function 271

Mmail dialog box 499mailing report files 480, 499MailReportInstance method 480, 499maintenance version 404, 449Management Console xxvmanaging clusters xxvmanaging displays 6mantissa 273Manuals directory xxxiiMapAcctTypes function 154mapping functions 154mapping variable types 198–199mapping XML to reports sections 230, 234mark-up tags 226master reports 238

adding hyperlinks 243, 245examples for creating 240

mathematical operationsdate/time values in 274numbers in strings 268operators for 254variants and 268

matrix arrays 264Me keyword 280memory 45

clearing programs from 125local variables and 262managing external 310OLE objects and 306

memory buffers 10memory cleanup function 310memory leaks 368

menus 14adding items 160creating context 159–162creating for web browsers 215, 218displaying context 157external applications and 299

merge filters 101messages

See also error messagesforwarding 475getting status 497resetting status 503

Method Editorcreating methods 59filtering options in 30, 50overriding methods 57starting debugging sessions from 118

Method Filtering dialog box 60, 61debugging in 118

method naming conventions 59methods 18, 251

accessing 39, 310ActiveX alphabetical reference 491ActiveX categorized 477Actuate Basic categorized 30associated with mouse events 157calling 40

resolving ambiguity when 41caution for creating 58caution for overriding 30, 32class protocol for 4component references and 75creating 58–59customizing 250data access 80debugging 118, 128deleting 61derived classes and 20displaying 51, 60, 111, 128dot notation and 39editing 60–61empty 4, 20executing specific tasks with 252extending functionality of 56filtering 52, 60, 61inspecting 51–52

variables in 127

I n d e x 537

methods (continued)invoking Java 317, 318multiple definitions for 32naming 32, 41, 58, 59, 257OLE Automation objects and 305overloading 32overriding 31, 56–57

component references and 75for custom data streams 90for XML documents 229report generation and 66

overview 30–32, 57, 280procedures as 251, 280properties vs. 58redefining 20referencing 39, 40restoring functionality 40scope 280setting breakpoints for 123specifying explicitly 40, 41stepping through 124stored procedures and 188, 193, 194storing values for 29, 52viewing call stack for 128visibility 20with no parameters 318

Methods dialog 111Methods page (Component Editor) 30

adding methods 58deleting methods 61inspecting methods 51overriding methods 57

Microsoft Internet Explorer. See Internet Explorer

Mid function 269MidB function 269MIME type 232minus sign (–) in strings 270mixed capitalization 257Mod operator 254modal dialogs 475modules 49

containing procedure declarations 281, 282

copying external functions to 360user-defined types and 276

modulus 254

monetary values 265, 272monitoring values 125Month function 274mouse cursor 157mouse events 156–159

ActiveX controls 484key presses and 158overview 156parameters listed 157responding to 157

moving OLE components 301moving through reports 478

ActiveX function calls for 498, 499, 502MS SQL connections 8Multi-Application Option xxvimultidimensional arrays 264

C functions and 315Java objects and 319

MultiLine propertybrowser scripting controls and 208

multi-line statements 257multilingual reporting xxiimultiplatform interface 326multiple data adapters 78multiple input filters 80, 98multiple options 378, 427multiplication 254multi-table reports 99, 101

Nname conflicts 23Name property

Me keyword vs. 280names 21

C functions and 312, 313duplicate 41, 59getting class 44getting parameter 344guidelines for 258hard-coding 360IDs associated with 192referencing 22

namingarrays 53classes 40, 257controls 23

538 P r o g r a m m i n g e . R e p o r t s

naming (continued)executable files 352, 355iServer files 476local files 476methods 32, 41, 58, 59, 257procedures 258, 285search extensions 464, 469variables 53, 257

naming conventions 257, 339, 488methods 59

native file systems 476, 479navigating through reports 478

ActiveX function calls for 498, 499, 502navigation methods 478navigational tools 484, 485

Contents window as 485Navigator. See Netscape Navigatornegation 255negative exponents 254negative numbers 108, 270nested classes 21, 23nested declarations 20nesting 67

class data types 266control structures 287controls 23procedures 257statements 257user-defined type declarations 276

Netscape Navigatorcreating reports for 222–223generating output for 211scripting code for 205

BrowserClipping property in 206, 207New keyword 36New Library dialog 261New method 68

overriding 104new pages 73NewConnection method 83NewContent method 67NewPage method 73NewPageList method 67Next buttons 484Next_Click event 484NextPage method 479, 484, 499NLS resource DLL 498

NO_TP type 471NoClipping setting 207, 222NoKeys setting 158nonstandard data sources 90nonstandard names 313non-visual classes 6non-zero return values 407, 451not equal to operator (<>) 255Not operator 255Nothing keyword 43, 44

OLE Automation objects and 306notifications

report completion 66null character 315Null keyword 315null pointers 315null values 315

assigning to objects 43testing for 44

NULL_TP type 472null-terminated strings 315number sign (#)

in dates 273, 274type declaration 267

numbers 37See also numeric controls; integersarithmetic operators and 254computing powers and roots of 254concatenating with strings 256converting

to character values 253to dates 275to strings 270

displaying 108dividing 254getting as current value 401, 402, 445, 446getting as default 385, 386, 434overview 272representing colors 265rounding 253setting as default 421, 422, 456valid ranges for 265variants and 268

numeric constants 253, 258, 267numeric controls

assigning values 272–273instantiating 14

I n d e x 539

numeric data types 273numeric expressions 254

conditional statements and 286numeric variables 273

OObject command (Edit) 294, 295, 300Object command (Insert) 297, 300Object data type 319object files (OLE) 292, 296object IDs 44Object Linking and Embedding. See OLEobject reference variables 18

assigning values 42–43C functions and 316comparing 45, 255declaring 34–36

AnyClass type for 36Java objects and 317monitoring 126OLE Automation and 305, 306overview 37–39passing to procedures 43restrictions for 42setting to Nothing 43testing 44–45tracing 126

object referencesreturning 43testing status 44, 45

Object type 319object-oriented languages 250object-oriented programming 250objects

accessing Java 316, 317–318accessing variables and methods in 39adding from external applications 292, 296altering behavior of 58assigning to variables 42assigning variables to 24base class for 5building 68creating 34–37

for Java applications 317customizing 37defined 34

defining as persistent 37, 46defining attributes 25, 276defining behavior for 18defining structural characteristics of 7executing tasks on 40generating content for 68getting information about 31initializing 68instantiating 36lifetime of 45nesting classes in 23overview 34providing help with 162, 163referencing 37, 38, 39, 280releasing from memory 45returning values for 39scope 45selecting 157, 158specifying actions for 30support for OLE 293temporary 45tracking 66viewing events for 156

ObjectVariable property 111obsolete properties 117OCX controls 292

See also OLE custom controlsODBC databases

connecting to 8, 84ODBC stored procedures 168OLE 292OLE applications 292

closing 306editing 294, 295, 299–300incorporating data from 294

OLE Automation objectsclosing 306compared to OLE objects 304creating 305defined 304

OLE componentsmoving and sizing 301subclassing 302

OLE container componentsadding 296, 297, 298inserting for OLE custom controls 300

OLE containers 14, 292

540 P r o g r a m m i n g e . R e p o r t s

OLE controls 14, 474OLE custom controls

accessing 292adding 300–301overview 293

OLE objectsaccessing 304adding 14, 296–299changing 294, 295, 299–300, 302compared to OLE Automation objects 304defined 292linking and embedding 292–299

guidelines 296resizing 301support for 293

OLE registry 293OLE strings 368OLE_TP type 472OnActuate method

default action for 161executing 160overriding 161

OnContextMenu methodcreating context menus 159default action for 161implementing context-sensitive help 164

OnFollowLink methodcreating context menus 160, 161default action for 161overriding 160

OnHelp method 160, 164OnLButtonClick method 157OnLButtonDblClk method 157OnLButtonDown method 157, 158, 358

overriding 157OnLButtonUp method 157online documentation

accessing xxxiioverview xxviisyntax conventions for xxxvtypographical conventions for xxxv

online help xxxii–xxxivproviding 160, 162–163, 165

OnRButtonClick method 157OnRButtonDblClk method 157OnRButtonDown method

default action for 157, 159

implementing 161, 164overriding 157, 161

OnRButtonUp method 157OnRead method

overriding 90OnRow method

overriding 108, 112Open function 463, 470open server 64open server reports

invoking functions in 480, 493open server technology xxivOpenConnection method 83OpenCursor method 183opening

Component Editor 49Contents window 506executable files 485, 500external applications 305files 470input data adapters 81input data sources 80Library Organizer 261log files 66report files 342, 407, 452reports 477, 485, 500, 501Stack window 129Variables window 126Watch window 128

OpenRecentReportInstance method 479, 500OpenReportExecutable method 480, 485, 500OpenReportInstance method 478, 485, 501operands 253operating environments 329operators

assignment 252precedence 256scope-resolution 22simple types described 253–256variants and 268

optimizing Actuate Basic 267, 272optional parameters 352

testing for 442options 378, 427

iServer System xxviOr operator 255Oracle multiple result sets 194

I n d e x 541

Oracle tablesaccessing stored procedures in 191, 194–

198connecting to 8creating stored procedures 168, 182–188

order of evaluation 256orientation (page) 413output

aligning web browser 207clipping browser 206, 213e.reporting solutions for xxivgenerating dynamically 214generating for web pages 211scaling 212

output files 352, 355output parameters

adding 180declaring as cursor variable 194, 195defining 189, 198testing for 179

Output window 117viewing errors in 117

overloading methods 32overloading procedures 285overriding methods 56–57

caution for 30, 32component references and 75for custom data streams 90for XML documents 229overview 31report generation and 66restoring functionality 40restrictions 31

overriding precedence 256overwriting report flies 378, 427

Ppage breaks 73page layout classes 11page layouts

designing at runtime 104–107determining style 73headers and footers

generating content for 72page creation process and 74

page level security

customizing ACLs for 153–154customizing security IDs 151–152example for implementing 149–151implementing 135–140overview 132–135

Page Level Security Option xxvipage list class 6page list components 73page list styles 73page lists

Factory processes and 72instantiating 67

page numbersgetting current 496setting programmatically 498viewing in secured reports 137

page orientation 413page security 120page structure (Factory) 67page styles 73PageBreakAfter property 73PageBreakBefore property 73PageCount method 479, 501page-creation protocol 72–74page-level security xxviPageNumberType property 137pages 156

See also page layoutsadding report objects to 11building 6, 72counting 501creating content for 6creating report 11defining characteristics of 6printing options for 348tracking number of created 66

paging through reports 478ActiveX function calls for 498, 499, 502

PaintBrush applications 292paper size

by dimensions 414by type 412

paper trays 417parameter dialog 503Parameter option 55Parameter Sample Values command 171

542 P r o g r a m m i n g e . R e p o r t s

parameter values filesActiveX controls and 476closing 376creating 122, 425, 459described 342finding specific values in 346generating reports from 377, 408, 426, 452,

504getting parameter groups in 391, 394, 437,

440getting specific parameter in 392, 395, 438,

441opening 407, 452

parameter variablesadding 52displaying 28, 50overview 25

parameterized queries. See stored proceduresparameter-passing conventions 43

C functions and 311, 312, 315–316parameters 330

See also search parametersadding to image controls 106, 107assigning values 347, 396, 398, 442assigning variables as 25, 28changing 336data filters and 91defining input 189defining output 189, 198determining how retrieved 418displaying 394, 440generating reports and 397, 443getting ad hoc 382, 430getting aliases for 382, 430getting attributes 345getting current values 346, 399, 400, 401,

402, 403, 443, 444, 445, 446, 447, 448getting data types for 396, 398, 442getting default values for 346getting defaults 383, 384, 385, 386, 387,

388, 431, 432, 434, 435, 436getting group names for 391, 394, 437, 440getting names 344

from Visual Basic forms 364from Visual C++ forms 369

getting specific 392, 395, 419, 438, 441grouping 344, 392, 437

inspecting 336manipulating in C++ applications 369,

370, 373manipulating in Visual Basic forms 363methods and no 318mouse events and 157overloaded methods and 32passing arguments to 284procedures and 283prompting for 366saving 122setting as Currency type 420, 454setting as Date type 420, 455setting as Double type 421, 456setting as Integer type 422, 456setting as String type 423, 457setting default values for 96setting for successive debugging runs 116setting programmatically 352, 355, 393stored procedures 171, 177, 179–182storing 342, 352, 355, 425, 459testing default assignment 405, 449testing status 382, 393, 397, 430, 439, 442

Parameters page (stored procedures) 179, 181parentheses in expressions 256parsing 208, 269passing by reference 284

C functions and 312passing by value

C functions and 312passwords 84, 351

in API function calls 343obtaining customer xxviiprompting for 477specifying programmatically 495

patch number 404, 449PATH system variable 341path variables (UNIX) 340paths 260, 312, 349

DLLs and relative 360getting most recent 497hard-coding names in 360specifying for API libraries 340specifying in API function calls 343

pattern matching 177–178pausing program execution 123PDF converter 213

I n d e x 543

PDF filesadding objects from 292displaying controls in 214viewing reports as 213

PeopleSoft databases 168percent (%) character in code 266permissions 477, 501Persistent keyword 37persistent objects 6

creating 37Factory service and 64overview 46

personal views 132physical paper sizes 414, 416placing frames in flows 6platform-independent formats 226pointers 276, 314

passing to C functions 315pop-up menus 14

adding items 160creating 159–162displaying 157web browsers and 215, 218

Portrait orientation 413positive exponents 254positive numbers 108, 270pound sign (#)

in dates 273, 274type declaration 267

powers 254precedence 256

connections 84precision 272predefined classes

See also Actuate Foundation Classespredefined functions 285

See also functions; methodspredefined methods 30, 251

See also methodsPrepare method 85, 86

stored procedures and 194Preserve keyword 264Prev buttons 485Prev_Click event 485PreviousPage method 479, 485, 502Print buttons 485Print method 502

Print_Click event 485printed documentation xxixprinters

changing default 348, 413, 453configuring 348local configurations and 336setting paper size for 412, 414specifying 353, 356, 410, 413, 453specifying paper tray for 417

printing images 417printing options 348, 406, 450, 502, 503printing reports

API functions for 348from Actuate Viewer 214from End User Desktop 336from PDF files 213from report server 336, 353, 356from Requester API 335, 406, 450from Visual Basic forms 363from Visual C++ forms 369, 371locally 336, 348, 407, 451multiple copies 413overview 64with ActiveX controls 480, 502with images 107

PrintReport method 480, 502priorities 418private classes 49private methods 30Private option 55private variables 26privileges 336, 477, 501procedures 250, 280

accessibility of 281accessing variables in 260adding comments to 256C functions as 311, 312calling 281, 284creating 251declaring 282defining arguments for 283defining as global 281exiting 287functions as 282in DLLs 315local variables and 262methods as 30, 251

544 P r o g r a m m i n g e . R e p o r t s

procedures (continued)naming 258, 285nesting 257object reference variables and 37overloading 285returning values 43scope 280stepping through 124types listed 280

product suite xxivproduct updates xxviiprogram files. See report filesprogrammers 250, 256programming interfaces

accessing 337choosing libraries for 338, 488closing sessions for 353, 356error checking for 349–350file naming conventions 339, 488initializing sessions 351, 355overview 326–328programming tasks for 341selection guidelines for 329–331, 337setting up client stations for 340, 341uninstalling class libraries for 423

programming languages xxv, 250, 337programming tools xxv, xxviprogramming. See Actuate Basic; object-

oriented programmingprograms

adding C functions to 310, 311adding source files to 310clearing from memory 125controlling execution of 123creating procedures for 280debugging 116developing 251, 256improving readability of 285resuming execution 124returning incorrect values 117running 123stepping through 123stopping execution 125

Progress database connections 8, 85Progress databases xxvi

creating stored procedures for 168Progress Option xxvi

progress windows 378, 427projects. See programsprompts

creating custom dialogs for 366defining for Requester 383, 431

properties 25, 120browser scripting controls 204, 207, 214changing dynamically 108component references and 74conditionally changing 110–113displaying 51methods vs. 58referencing obsolete 117setting 26–28, 51

at design time 34at runtime 28, 108conditionally 108

user-defined types and 275XML-specific 229, 230

Properties page (Component Editor)adding variables 55setting property values 51viewing properties 51

Property option 55Property setting 25property variables

adding 52inspecting 50, 125overview 25, 26

Public option 55public variables 26publishing data streams 83publishing XML reports 229–236PutRow function 464, 470

Qqtrly.dtd 227qualified names 22, 41queries 79

ad hoc parameters and 382, 430creating 81, 86

for report bursting 242defining cursors for 189executing 86instantiating statements in 85overview 85

I n d e x 545

queries (continued)running ad hoc xxvisetting conditions at runtime 28stored procedures and 168

query classes 9query data sources. See SQL data sourcesQuery Editor

creating queries 81filtering data 91filtering multiple data sources 99

Query Option xxviquery statements. See queries; SQL

statementsQuit method 306quotation marks in strings 272

Rrandom access methods 80random data access 79range of values 265

dates 274searching for specific 505type definitions and 265

real numbers 272real types. See Double data type; Single data

typerecords. See data rowsrectangle controls 14

calculating area of 283ReDim statement

arrays and 264object reference variables and 34

REF_CURSOR type 195REF_TP type 472REFCUR3.GETMGRDATA 184reference 375reference count 45references 20

getting 112returning 43testing status 44, 45

referencingclasses 20, 22components 68, 74, 78global browser code 209input adapters 100

methods 39, 40objects 37, 38, 280

dot notation for 39obsolete properties 117report files 343variables 39

registering ActiveX controls 486, 488registry entries

ActiveX installations 488search parameters 463

regsvr32 DeskOCX command 488relational databases. See databasesrelationship map (components) 66relationships xxvi, 68release notes xxviirelease numbers 404, 449Rem keyword 256remainders 254removing type restrictions 312renaming

stored procedures 170renaming C functions 313repetitive tasks 280, 304, 330report bursting 238

asynchronous reports and 238examples 240

report class 6, 7report component class 6report components

See also componentsabstract base classes for 4creating 68instantiating 6

Report Debug Options dialog 122report designs 251

adding browser scripting 205, 209adding objects from external

applications 292creating at runtime 104–107creating for flat file data sources 94, 97creating with Design Editor 18, 74implementing page level security 135–140,

149multiple data sources and 99, 102stacking controls in 214testing 138, 141

report examples xxviii

546 P r o g r a m m i n g e . R e p o r t s

report executables. See executable filesreport files 342–344

accessing 376, 426bundling 493closing 376generating 342

multiple 238generating reports from 408, 452mailing 480, 499opening 407, 452, 485, 500overwriting 378, 427referencing in API function calls 343server connections and 477specifying local names for 476

report object files 343report object structure classes 7report objects

default scope for 22instantiating 6, 7, 66nesting classes in 23placing on page 11

report parameters. See parametersreport sections

accessing data in 153creating content for 68, 69placing connection components in 83, 85

report serverSee also e.Reporting Serveraccessing report files from 477accessing volumes 335connecting to 334, 351, 495creating parameter values files for 425,

459defined 326generating reports from 365, 377, 418, 426opening report files from 407, 452printing from 353, 356, 406, 450running reports from 500viewing reports on 366, 424, 457

Report Server API xxvioverview 326, 330selecting DLLs for 339, 340

Report Server Security Extension xxvi, 134report statistics 66Report Wizard

generating SQL data sources 94ReportCast xxv

Reporting Engines suite xxivreporting features 329reporting solutions xxi, xxiiiReportQuery technology xxivreports

accessing 496in Encyclopedia volumes 335

adding company names and logos 106as OLE containers 292as OLE servers 292building 4, 64

starting Factory process for 66–67building pages for 6building subreports for large 238, 239, 240canceling generation requests 494closing 477, 484, 495content/page structures for 67controlling access 132, 154converting to DHTML 202counting number of pages in 501creating programmatically 251customizing xxv, 31, 89debugging 139designing xxivdeveloping xxv, xxxivdisplaying xxvii, 155

ActiveX controls and 474, 485API functions for 348as PDF 213–214in Actuate Viewer 214, 341, 411, 453,

466in C++ applications 368in Encyclopedia volumes 477in Visual Basic forms 362, 366in web pages 64, 202locally 336, 349, 356Requester API and 335, 336

generating xxv, 63, 397, 443API functions for 377, 426Factory service and 64, 66, 67from report files 408, 452from Visual Basic forms 362, 365from Visual C++ forms 369, 370Requester API and 334

getting content for 76getting generation status for 408getting values at runtime 28

I n d e x 547

reports (continued)getting version 396implementing secured 131invoking functions in 480, 493launching 379, 428moving through 478, 498, 499, 502multiplatform interface for 326opening 477, 485, 500, 501personal views for 132platform-independent formats 226printing 64, 107

API functions for 348from Actuate Viewer 214from PDF files 213from report server 353, 356from Requester API 406, 450from Visual Basic forms 363from Visual C++ forms 369, 371locally 336, 348, 407, 451multiple copies 413with ActiveX controls 480, 502

providing online help for xxxivpublishing 334publishing as XML 229–236responding to events 156running

API functions for 348based on specified parameters 342C++ sample code for 353, 370default values and 383, 431from ActiveX controls 479, 485, 494,

503, 504from End User Desktop 410, 453from parameter values files 352, 353,

355, 356in batch mode 327, 349, 380, 429locally 336, 349, 354on report server 500Requester API and 335, 336Visual Basic sample code for 356

running on iServer 500saving 480

as XML documents 504scaling 485, 505specifying local file names for 476specifying server files names for 476subclassing 239

support for third-party 64viewing

secured 134reqapivb.txt 337reqbasic.h 337REQCYTYPE struct 384, 399, 432, 444request handle 381, 429Requester

asterisks as text strings in 393customizing 345, 351, 392, 437

Visual Basic example for 366–368defining debugging parameters 122defining prompts for 383, 431displaying variables in 55getting parameter names in 345

Requester API xxv, 357alphabetical function reference 375and iServer 335building applications 350–357client code for 409client-server configuration for 335closing libraries for 366, 423closing session 353, 356customizing 383, 431developing with 334–341dynamic link libraries for 339, 340error codes for function calls 389file naming conventions for 339functions categorized 341–350getting version information for 404, 448implementing ActiveX controls from 489initializing 351, 355, 406

from Visual Basic forms 362local reporting and 336operating environment described 340operating requirements for 336–341overview 326, 330, 334programming examples 337

for Actuate Basic 358–360for C++ 368–374for Visual Basic 360–368

running applications from 338, 339, 340shutting down 423specifying multiple options 378, 427

requestsgetting status 408issuing 342

548 P r o g r a m m i n g e . R e p o r t s

requests (continued)prioritizing 418resubmitting 357submitting 217, 353, 356, 357

required parameters 352, 355search extensions and 465testing for 442

reserved wordsC functions and 313operators as 253restrictions 258

ResetStatus method 503resizing

OLE objects 301resolving ambiguous methods calls 41resources

freeing 423loading language-specific 499

responding to events 156Result Columns page (stored

procedures) 175, 176result sets 168

accessing multiple 197–198defining cursors for 189retrieving 175returning different types 180with duplicate column names 175

retrievingdata 79, 80, 81, 82

from data adapters 6, 78from data streams 76from external data sources 6from flat files 94from multiple sources 98–103from nonstandard sources 90from text files 90

data rowsfrom stored procedures 189with database cursors 85

return values 282, 283C functions and 311, 316checking for errors with 350getting from stored procedures 189, 192,

194printing functions and 407, 451procedures and 43, 284

Right function 269

RightB function 269right-to-left orientation 505Rogue Wave programs 337, 339ROI files. See document files; report object

filesRoiFileName parameter

specifying 352, 355roiimage.rod 107RoiIsTemporary method 238roots 254ROS files. See search definition filesrotp syntax 335, 353, 476rounding 253rounding errors 273routines 408ROV files. See parameter values filesrows. See data rowsROX files. See executable filesRoxFileName parameter 349

specifying 352, 355royalty-free distribution 474RTrim function 271Run buttons 485Run_Click event 485running programs 123

line by line 123running queries 86running reports

API functions for 348based on specified parameters 342batch mode for 327, 349, 380, 429C++ sample code for 353, 370canceling requests for 494default values and 383, 431from ActiveX controls 479, 485, 494, 503,

504from End User Desktop 410, 453from parameter values files 352, 353, 355,

356locally 336, 349

sample application for 354on report server 500Requester API and 335, 336Visual Basic sample code for 356

running stored procedures 189RunReport method 480, 485, 503RunReportWith Parameters method 480

I n d e x 549

RunReportWithParameters method 504run-time errors 117run-time properties 28, 108run-time values 25RWCString class 314

Ssample applications xxviiisample database files

Oracle8 stored procedures 184Sample Parameter Values 179Sample Parameter Values dialog 170sample reports xxviii

report bursting techniques 240sample Windows application 482

running 485SampleValue property 205SaveAsXMLData method 480, 504saving

report parameters 122reports 480

as XML documents 504user-defined methods 59

scalar data type 273scale factor (default) 505scaling factor 212scaling images 417scaling reports 485, 505scheduling reports 274schema

verifying stored procedures 170scope 21–23

changing 24default 22defined 20determining 22methods 280objects 45procedures 280variables 125, 260

setting in Component Editor 55scope-resolution operator 22scripting control. See browser scripting

controlsscroll bars 207Scrollbar setting 207

SDK (Software Development Kit) 337search criteria. See search parameterssearch definition files 463

closing 468creating 465default directories for 463extension-specific parameters in 472retrieving information from 469

Search Extension API xxvsearch extension API

alphabetical function reference for 467data types for 471function calls 465functions categorized 462–464overview 327, 330, 462shutting down 468

search extension applicationscreating header files for 466defining column delimiter for 468developing 464–466including column names 469installing 466naming 464, 469opening files for 470processing search results for 464, 470prompting for input parameters 470running 463

search extension directories 409search extensions 327, 409, 462

default directories for 463Search Extract Option dialog 463, 470search parameters

getting 469implementing 470setting programmatically 463, 472

search paths 312, 349, 360Search window 475, 505SearchDefDir setting 463SearchExtDir setting 463searching 14, 327

for HTML tags 208for specific values 505for stored procedures 177–178third-party applications 462with ActiveX controls 505

SearchWindow method 479, 505section classes 6, 10

550 P r o g r a m m i n g e . R e p o r t s

sectionsaccessing data in 153adding data rows 71building 10creating content for 68, 69, 70determining page styles for 73mapping XML properties to 230, 234page creation process and 72placing connection components in 83, 84,

85secure read privilege 154security 132–135, 336

customizing ACLs for 153–154customizing security IDs 151–152debugging with page 120e.reporting solutions for xxivenabling page-level xxviexample for implementing 149–151implementing 135–140server connections 351

security IDs 133access control lists for 133adding 134customizing 151–152displaying 140getting 134suppressing 153testing 138

security role 133security tools xxviSeekBy method 79SeekTo method 79SeekToEnd method 79select filters 92–93SELECT statements 85

See also SQL statementsselecting

stored procedures 177selection formulas. See parametersselection state toggles 158separation character (:) 257sequential data access 79serial numbers 274server

accessing volumes 351server applications 329

deploying to 334

editing in 299OLE linking for 292

Server Integration Technology xxvserver-based reporting xxivservers

accessing files 376, 426accessing report files from 477connecting to 5, 8, 334, 351, 376, 425, 495disconnecting from 353, 377e.reporting solutions for xxiiigenerating reports 377, 426managing clusters for xxvopening report files 407, 452printing reports 406, 450programming interfaces for 326referencing in API function calls 343

Set statementcompared to Let statement 43New keyword and 36Nothing keyword and 43object reference variables in 42OLE Automation objects 305, 306

SetDataTypeInfo function 464, 471SetParameters function 463, 472SetScaleFactor method 479, 485, 505SetSecurity method 153setting properties 26–28, 51

See also propertiesat design time 34at runtime 28, 108conditionally for controls 108XML documents 229, 230

setting watches 127SetupDataRow method 82SetValue method 82SetWindowLayout method 479, 505shared libraries 310, 312

selecting for API files 340shared tasks 280sharing connections 83sharing data 292, 304shift parameter 158–159ShiftKey Bor AltKey setting 158ShiftKey Bor ControlKey setting 158ShiftKey Bor CtrlKey Bor AltKey setting 158ShiftKey setting 158SHLIB_PATH variable 340

I n d e x 551

short date format 274short type 319Show all methods filter option 111ShowInDHTML property 214ShowInPDF property 214ShowWhenPrinting method 107ShowWhenPrinting property 214ShowWhenViewing method 107ShowWhenViewing property 214Simplex mode 412simplifying programming tasks 280Simulated Page Security Viewing

options 120Single data type

assigning values 272, 273C functions and 313, 316converting to 277declaring 267described 265Java objects and 318

single input filters 80SINGLE_TP type 472single-byte characters 269single-dimension arrays 319single-line statements 257slots (Structure pane) 74SOAP messaging protocol xxviSoftware Development Kit 337Solaris compilers 338sort filters 93–94sort key columns 70

getting at runtime 108sort keys

setting at runtime 108setting programmatically 69sorting on 70

sorting data 70, 93sound files 292source code

See also Actuate Basicaccessing Java objects in 318accessing variables in 26adding breakpoints 123adding comments 256conventions for 256–258debugging 115displaying browser 208

displaying specific methods in 128editing 48editing restrictions 55, 56, 60, 61examples for 258extending functionality 310getting values for 31handling invalid methods in 58implicit declarations and 260indenting 257language elements in 252–256locating errors in 117programming conventions for 251resuming execution of 124running 119setting watches 127startup/cleanup

Factory services 66Requester API 342, 353search extension API 463

stepping through 123, 125stopping execution of 125viewing comments in 49writing custom browser 209, 210

source file window 119source files 251

adding to projects 310C functions and 310creating 281custom browser code in 209debugging 116declarations sections in 261declaring procedures in 280, 281starting debugging sessions for 119tracing through 124

special characters 202, 204Specify Parameter File Name dialog 122specifying multiple options 378, 427spreadsheets

as data sources 80, 292as input sources 76designing xxv, xxviigenerating xxviOLE automation and 304

SQL data sourcesaccessing data 85, 90adding to reports 96connecting to 8, 84

552 P r o g r a m m i n g e . R e p o r t s

SQL data sources (continued)filtering 81filtering multiple 99, 101improving performance for 168instantiating 10overview 85reading columns in 82retrieving data from 10, 79, 80, 94

SQL statementsSee also queriesas stored procedures 168creating 86instantiating 85overview 85running 86

square roots 285SrchDef directory 463SrchExt directory 463stack 497, 503Stack window 128

opening 129stacking controls 214standard data types. See data typesStart method

AcControl 72AcDataAdapter 78AcDataFilter 81AcDataSource 80AcFrame 71AcGroupSection 71AcReportComponent 68AcReportSection 69, 83overriding 66, 90

for flat file access 97for multiple data sources 100

StartFlow event 73starting

Component Editor 49debugging sessions 118Factory services 65, 66

StartNextSet method 189StartPage event 73startup code

API functions for 342Factory services 66search extensions 463

statements 250defining blocks of 286

described 252executing conditionally 286executing series of 283fixing errors in 117incorrectly constructed 116instantiating classes and 18monitoring 123nesting 257programming conventions for 257repeating indefinitely 286

static controls 13static fields 317, 318static methods 318Static statement 260

creating static variables 24declaring local variables 262declaring object reference variables 34

static text 14static variables 25

creating 24, 54declaring 260scope 55visibility 20

statistics 66status codes 408status information 408status messages 497

resetting 503status stack 503status strings 481Step Into command 124Step Into icon 124Step Over command 124Step Over icon 124stepping over code 124stepping through code 123, 125stopping debugging sessions 125stopping program execution 125stored functions 182, 194

example for 184Stored Procedure Browser 170, 174

Oracle tables and 182stored procedure components 168Stored Procedure Data Source Builder 182

accessing 169entering parameters 179, 180narrowing procedure list 177overview 168

I n d e x 553

Stored Procedure DataSource Builder 188, 194

Stored Procedure Name Editor 170stored procedures

accessing 188creating 171–174

for Oracle8 data sources 182–188customizing 188–199defined 168defining parameters for 189, 198entering parameters 171, 177, 179–182extracting return values from 192, 194not returning data 175renaming 170retrieving data 176–177returning multiple result sets 197–198returning status values 189returning unknown values 180searching for specific 177–178selecting 170, 174, 177setting up 174synchronizing 170, 177testing for parameter type 179verifying contents 170, 177

storing values 260global variables for 113methods and 29objects and 39

Str function 270Str$ function 253StrComp function 270stretched images 301string comparison operator (Like) 255string constants 267String data type

C functions and 313, 316converting to 277declaring 267, 268described 265returning as current value 402, 403, 447,

448returning as default 387, 388, 435, 436specifying parameters as 422, 457

string data types 314string expressions 272string functions 269String keyword 268

string variables 213, 268, 269STRING_TP type 472strings 37, 268–272

as BSTRs 337, 368asterisks as 394, 440binary data and 106, 269character limits 265comparing 255, 270concatenating 256converting Java 319converting numbers to 253converting to binary data 107converting to currency 384, 399, 432, 444debugging Java 321declaring 268

as empty 215defining for online help 162delimiting literal 268formatting 270getting as current value 403, 447, 448getting as default 387, 388, 435, 436leading spaces in 270null-terminated 315parsing 269passing to C functions 315PDF conversions and 213quotation marks in 268, 272returning numbers as 270setting as default 423, 457variants and 268

strong cursors (defined) 194Structure pane 74structured content technology xxiistructures 250

See also control structuresdefined 266monitoring 126user-defined types as 275–276

style sheets 207, 222STYLE tag 223Sub statement

C functions in 311creating global procedures 281creating subprocedures 282initializing global variables 262

subclass 20

554 P r o g r a m m i n g e . R e p o r t s

subclasses 4declaring 18object reference variables and 35redefining methods in 20testing for instances of 44

subclassing 20abstract base classes 4inherited properties and 28OLE components 302reports 239stored procedures and 193

submitting requests 217, 353, 356, 357subpages 11subprocedures

See also Sub statementC functions as 311calling 284declaring 282defining as global 281, 282exiting 287functions vs. 283initializing variables in 262

subreports 83HTML documents 239

substringscomparing 270concatenation and 256getting 269

subtraction operator (–) 254successive debugging runs 116SuggestRoiName method 243, 245summary graphs 14SunOS operating systems 340Super keyword 40superclasses

class relationships and 20overriding methods and 57referencing methods in 40restrictions for 21

suspending code execution 123Sybase tables

accessing stored procedures in 189, 193connecting to 8, 85stored procedures and 168, 180

symbols 21, 253C functions and 312

invalid 313Synchronize Stored Procedure command 177Synchronize Stored Procedure With Schema

icon 170synchronizing stored procedures 170, 177synchronous mode 378, 427synchronous report generation 379, 381, 428,

429syntax

See also declarationsC function declarations 311Class statement 18CreateJavaObject function 317Function statement 282local file names 476method calls 40object reference variables 34, 39, 42server names in API function calls 343Set statement 36Sub statement 282Typedef statement 275

syntax conventions (documentation) xxxvsyntax errors 116SysFreeString method 368System Properties dialog 317

TTable of Contents 475

opening 485, 506TableOfContents method 479, 485, 506tables

getting from stored procedures 194tabular reports 4tags 226technical assistance xxviiitelephone numbers 268templates

classes as 18temporary calculations 262temporary files 107, 352, 353, 355, 357

deleting 107temporary objects 45, 304terminating database connections 84terminating server connections 353, 377testing applications 122

I n d e x 555

testing page level security 138examples 141–148

textstring variables as 268

text controlsDHTML conversions and 203instantiating 14

text filesretrieving data from 90

text strings. See stringsTextPlacement property 207third-party applications 327, 462third-party DLLs 487, 488third-party productivity tools xxvthird-party reports 64third-party security tools xxviThis 368time

as literal value 275display formats for 274valid values for 265, 273

time controls 14Toggle Breakpoint command 118, 123totals

calculating cumulative 262tracing 124, 126tracking values 125transactions xxiiitransient objects 45

data adapters as 76Factory service and 64

transparent colors 215Transporter technology. See search extensionstrends xxvitriggering events 156Trim function 271two-sided printing 412type codes 199type definitions (typedefs) 265, 275Type keyword 265Type mismatch errors 268type-declaration characters 253, 266types. See data typestyping errors 267typographic conventions

(documentation) xxxv

UUCase function 271UCase$ function 271Undo command 56, 61undocumented functions 459uninstalling class libraries 423unintended conversions 268union filters 99unique names 23UNIX servers

calling C functions from 310, 312developing applications for 326displaying reports 335printing from 412, 416selecting API files for 340working locally from 336

unknown object types 321UNKNOWN values 180UNKNOWN_TP type 472unloading libraries 310unresolved references 209unsigned long type 265unstructured content xxiiiUPDATE queries 86updates xxviiupdating DLLs 338, 488URLs

getting most recent 497user input 503user interfaces 329, 494user names 84, 351

in API function calls 343prompting for 477specifying programmatically 495

USER_TP type 472user-defined functions

calling 285creating 282exiting 287

user-defined methods 250changing 60creating 58, 251debugging 128deleting 61naming 58, 59OLE Automation example for 306saving 59

556 P r o g r a m m i n g e . R e p o r t s

user-defined types 275–276C functions and 315, 316described 265

user-defined variables 276

VV_CURRENCY type 199V_DATE type 199V_DOUBLE type 199V_INTEGER type 199V_LONG type 199V_SINGLE type 199V_STRING type 199validating connections 351validating user names and passwords 496ValueExp property 82

calculated variables and 91values

assigning to parameters 347, 396, 398, 442assigning to variables 42, 43, 252changing dynamically 108changing variable 284defining at design time 431determining if current 399, 400, 401, 402,

403, 443, 444, 445, 446, 447, 448displaying as hidden text 394, 440generating at runtime 104getting at runtime 28getting current 347getting default 346getting for code elements 31getting incorrect 117getting unknown 180limiting access to 393, 439monitoring 125null 43, 44placing limitations on 265returning 282

from a single row 78, 80, 81from all rows 78from nonstandard sources 90from procedures 283from stored procedures 189, 192, 194object variables and 39subprocedures and 284

searching for specific 462, 505setting as defaults 347

storing 260global variables for 113methods and 29objects and 39run-time 25

testing assignment 44testing for 396, 398, 405, 442, 449valid ranges 265, 274variables and 37, 38

Variable property 26variable type mappings 198–199variable-length arrays 264variable-length strings 268variables 18, 250

See also global variables; local variables; object reference variables

accessibility 125, 260accessing 39arguments as 283assigning data types to 53, 252, 266–267assigning null values 43assigning strings to 268assigning to objects 24, 42assigning to parameters 25, 28assigning to variables 37, 38assigning values 42, 43, 252attaching to classes 35

as any class 36with Component Editor 53

caution for using global 113changing values 284classifying data stored in 264class-specific 24–29, 50constants vs. 267counters as 272creating 53–55, 261data rows and 81, 82declaring 260–263

as global 261as local 262as private 26as public 26as specific type 266as static 24C++ sample code for 351type-declaration characters and 266user-defined types and 276

I n d e x 557

variables (continued)defining for flat file connections 96, 97defining for multiple input filters 100, 102defining output parameters as 194, 195deleting 56derived classes and 20displaying current values 125dot notation and 39editing 55examining values 125filtering 50frequently used 268initializing 66, 262inspecting 50–51, 125, 127instantiating classes and 18naming 53, 257overview 29, 37, 52, 260passing as arguments 284passing to procedures 43referencing 34, 39restoring previous definitions 56retaining values for 262returning from external functions 310scope 260

setting in Component Editor 55strings as 268testing assignment 44variants as 267watching specific 127, 128

Variables Browser command 126Variables command 56Variables page (Component Editor) 25

adding variables 55creating variables 53inspecting variables 50opening 53

Variables windowmonitoring in 125opening 126tracing object reference variables 126

variant datachanging case 271dates and 275numbers as 272, 273overview 267returning 283storage size and range 265

Variant data typeSee also AnyClass typearrays 263assigning 266C functions and 314converting to 277overview 265, 267procedures and 283, 284

Variant variables 267VARIANT_TP type 472VarType function 268VBScript 202Verify Design command 117version information 492version numbers 396, 404, 449Vertical duplex mode 412Vertical property 207View Browser Code command 208, 215View buttons 485view options 424, 458view processes 228–229View_Click event 485Viewer xxvii, 156, 331, 474

client applications and 335displaying browser code in 221displaying reports 341, 411, 453, 466launching local copy of 336printing from 214providing help for reports in 162–163, 165running Requester API from 341setting location for 410, 452setting up client stations for 466

Viewer ActiveX controlsSee also ActiveX controlsaccessing Actuate Basic functions

from 481adding 474methods calls for 491overview 327, 474

Viewer directory 409viewing

classes 49comments 49context menus 157, 161controls 214custom browser code 208, 221DHTML reports xxiii, 202

558 P r o g r a m m i n g e . R e p o r t s

viewing (continued)error messages 117images 107methods 51, 60, 111, 128online documentation xxxiipredefined classes 35properties 51report parameters 394, 440reports xxvii, 155, 424, 457

ActiveX controls and 474, 485API functions for 348in C++ applications 368in Encyclopedia volumes 477in Visual Basic forms 362, 366in web pages 64, 202locally 336, 349, 356Requester API and 335, 336with Actuate Viewer 214, 341, 411, 453,

466with PDF converter 213–214with security restrictions 134

variables 50, 125web pages 212

viewing events 156–157viewing methods 478viewing window (ActiveX)

changing views in 495displaying reports in 476, 479, 503, 504moving to specific page in 498, 499, 502resetting to first page 496scaling reports for 505

views 132visibility. See scopeVisiblePageNumber constant 137Visual Basic 250

accessing Requester API from 360ActiveX controls and 474creating Requester interface in 327customizing Requester interface 366–368,

392, 437developing with ActiveX controls 482generating and printing reports from 361–

366initializing Requester API for 362running End User Desktop from 410, 453sample application 354selecting Actuate API for 337

type codes for 199Visual Basic programs

customizing Requester interface 383, 431Visual C++ 475Visual C++ compiler 466Visual C++ forms 369visual classes 6visual components

instantiating 6visual distortion 208visual objects 156void type 319volumes 326

accessing 335, 351

WWatch command 128Watch window 127

opening 128watches 127weak cursors (defined) 182, 194Web applications 250web browsers

aligning output for 207creating menus for 215, 218displaying online documentation in xxxiidisplaying reports in xxviiexample implementation for Internet

Explorer 215–222fixing visual distortion in 208guidelines for Netscape Navigator 222–

223scripting code for 205, 206unresolved references in 209viewing code for 208

web pagesSee also HTML reports; XML reportsadding scroll bars 207changing scaling factor for 212debugging browser code for 208determining application context 211displaying reports for 64, 202getting URLs for 497navigating through 484, 492, 493specifying clipping for 206viewing 212

I n d e x 559

web sitese.reporting solutions for xxii, xxiiiobtaining Actuate product updates xxviisecuring xxv

Weekday function 274whole numbers 272Windows applications 292, 293, 299

building with ActiveX controls 482calling C functions for 310, 312choosing library files for 339creating reports for 326, 328developing 474displaying reports in 336printing from 416running Requester API 341specifying layouts for 505

Windows compilers 338Windows file systems 476Word documents 292WordPad 299word-processing applications 292, 304WordWrap property 208

XXML data formats 226XML Data property group 230XML data sources xxviiXML development tool xxviXML documents

document type definitions for 226format overview 227publishing Actuate reports as 229–236

XML extensions (AFC classes) 230XML formats

converting to DHTML 228, 230, 234XML functions 232XML properties 229, 230XML reports

generating 504XML tags 226XMLAddContents property 232XMLAttribute setting 230XMLAttributes property 232XMLCharSet property 231XMLCustom setting 230XMLDataProlog method 233XMLDataProlog( ) method

overriding 227XMLDocType property 231XMLFileDescription property 231XMLFileExtension property 231XMLIndent property 232XMLMimeType property 232XMLTag property 230, 232XMLType property 230, 232Xor operator 255

YYear function 274

Zzip codes 268zoom levels (web pages) 212zooming 505

560 P r o g r a m m i n g e . R e p o r t s