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 Corporation
701 Gateway Boulevard
South San Francisco, CA 94080
http://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
 Contents
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xxi
Understanding Actuate 7 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxi
Addressing diverse customer profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxii
Addressing customer requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxii
Supporting international information delivery requirements . . . . . . . . . . . . . . . . . xxii
Providing a scalable, high performance server . . . . . . . . . . . . . . . . . . . . . . . . . xxii
Providing a complete information delivery solution . . . . . . . . . . . . . . . . . . . . . xxiii
Introducing the Actuate 7 and ReportingEngines product suite . . . . . . . . . . . . . . . . xxiv
About Actuate e.Report Designer Professional product . . . . . . . . . . . . . . . . . . . . . xxvii
About Programming e.Reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxix
Online documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxxii
Using online manuals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxxii
Using online help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxxii
Using context-sensitive online help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxxii
Using the Actuate online help system. . . . . . . . . . . . . . . . . . . . . . . . . . . . xxxii
Using report-specific online help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxxiv
Typographical conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxxv
Syntax conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxxv

Part 1
Programming with the Actuate Foundation Classes
Chapter 1
Understanding the Actuate Foundation Classes . . . . . . . . . . . . . . 3
About the Actuate Foundation Class architecture . . . . . . . . . . . . . . . . . . . . . . . . . . 4
About abstract base classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
About concrete classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Understanding the AFC by functional category . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
About report object structure classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
About connection classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
About connection abstract base classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
About connection concrete classes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
About data stream classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
About data stream abstract base classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
About data stream concrete classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10
About report section classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10
About report section abstract base classes . . . . . . . . . . . . . . . . . . . . . . . . . . .10

i
 About report section concrete classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
About page layout classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
About page layout abstract base classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
About page layout concrete classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
About control classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
About control abstract base classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
About control concrete classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
About internal tool classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
About collection classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Chapter 2
Working with a class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
About classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Declaring a class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Understanding class relationships . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
About inheritance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
About scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Understanding class scope naming conventions . . . . . . . . . . . . . . . . . . . . . . . 22
About default class scope in a report design . . . . . . . . . . . . . . . . . . . . . . . . . 22
About the default scope of a class in a library . . . . . . . . . . . . . . . . . . . . . . . . 24
About class variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
About variables in Component Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
About visibility of variables in Component Editor . . . . . . . . . . . . . . . . . . . . . . . 25
Using property variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Using parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Using regular variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
About methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Using methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
About methods you can override . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
About methods you can call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
About private methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Overloading a method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Chapter 3
Working with an object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
About objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Creating an object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Declaring an object reference variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Declaring an object reference variable as a specific class . . . . . . . . . . . . . . . . . . 35
Declaring an object reference variable as AnyClass type . . . . . . . . . . . . . . . . . . 36
Creating an object using New . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Using an object reference variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Working with a simple variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

ii
 Working with an object reference variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . .38
Referencing an object’s variables and methods . . . . . . . . . . . . . . . . . . . . . . . . . .39
Referencing a method of a class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .40
Referencing a method in a superclass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .40
Using a class name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .40
Resolving an ambiguous method call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41
Assigning an object to an object reference variable . . . . . . . . . . . . . . . . . . . . . . . .42
Comparing Set and Let . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43
Setting an object reference variable to Nothing . . . . . . . . . . . . . . . . . . . . . . . .43
Passing an object reference to a procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43
Getting information about an object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .44
Testing an object reference with the Is operator . . . . . . . . . . . . . . . . . . . . . . . . . .44
Testing for Nothing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .44
Comparing object reference variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45
About object lifetime. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45
About transient objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45
About persistent objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .46

Chapter 4
Using Component Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
About Component Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .48
Getting information about a class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .48
Viewing general information about a class . . . . . . . . . . . . . . . . . . . . . . . . . . . .49
Inspecting a variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .50
Viewing and setting property values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .51
Inspecting a method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .51
Working with a class variable. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52
Creating a class variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .53
Editing a variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .55
Deleting a variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .56
Overriding an inherited method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .56
Overriding a method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .56
Working with a user-defined method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .57
Creating a method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .58
Naming a method. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .59
Editing a method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .60
Deleting a method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .61

Chapter 5
Understanding document generation . . . . . . . . . . . . . . . . . . . . . . 63
Overview of the Factory service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .64
Starting the Factory service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .65
Adding startup and cleanup code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .66

iii
 Starting the build process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Creating content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Using the core protocol for content creation . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Using a component reference in content creation . . . . . . . . . . . . . . . . . . . . . . . . 68
Using a report section to implement the content-creation protocol . . . . . . . . . . . . 69
Using a group section to implement the content-creation protocol . . . . . . . . . . . . 70
Using a frame to implement the content-creation protocol . . . . . . . . . . . . . . . . . 71
Using a control to implement the content-creation protocol . . . . . . . . . . . . . . . . 72
Creating a page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Determining the page on which to place a frame . . . . . . . . . . . . . . . . . . . . . . . . 73
Understanding the page list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Instantiating a class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Working with a data stream . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
About data adapters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Combining data adapters to form a data stream . . . . . . . . . . . . . . . . . . . . . . . 76
About the protocol for a data adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Instantiating a data adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Sequential and random access to data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
About data sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
About data filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
About data rows. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Understanding the data row life cycle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Connecting to a database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Placing the connection in a data stream . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Placing a connection in a section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
About connection precedence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
About SQL support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Using statements and cursors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
About connection relationships . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Creating and executing a custom SQL statement . . . . . . . . . . . . . . . . . . . . . . . . 86

Part 2
Customizing report designs
Chapter 6
Customizing a report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Customizing a data stream . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Creating a computed data row variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Filtering out a selected data row. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Creating a select filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Creating a sort filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

iv
 Retrieving data from a flat file. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .94
Working with data from multiple sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . .98
Customizing the report layout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Conditionally creating a component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Dynamically embedding an image control . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Customizing report data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Conditionally setting properties of a control . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Creating a custom control to display a group section key . . . . . . . . . . . . . . . . . . . 108
Changing a control property based on another control’s value . . . . . . . . . . . . . . . . 110
Using GetControlValue( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Using the ObjectVariable property. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
Using FindContentByClass( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Using a global variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

Chapter 7
Debugging a report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
About debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Understanding the types of errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
About compilation errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Run-time errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Logic errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
About the Actuate Output window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Starting a debugging session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Controlling program execution. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
Running to a breakpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
Stepping through code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
Resuming code execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Stopping code execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Examining variable values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Monitoring a variable as its value changes . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Interpreting the icons in the Variables window . . . . . . . . . . . . . . . . . . . . . . . . . 126
Tracing object reference variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Checking the value of a specific variable. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Viewing the stack of method calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

Chapter 8
Designing a report with page-level security . . . . . . . . . . . . . . . . 131
About personal views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
About page-level security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
About the Security ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
About the Access Control List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
About the GrantExp property for a secure report . . . . . . . . . . . . . . . . . . . . . . . . 134
Viewing a report with page-level security . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

v
Designing a report with page-level security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Testing a report design security example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
Understanding the security scenario example . . . . . . . . . . . . . . . . . . . . . . . . . . 141
Examining the report component for the security example . . . . . . . . . . . . . . . . . . 142
Reviewing the query for the security example. . . . . . . . . . . . . . . . . . . . . . . . . . 142
Examining the GrantExp property for the security example . . . . . . . . . . . . . . . . . . 143
Examining the page layout for the security example . . . . . . . . . . . . . . . . . . . . . . 144
Examining the report security example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
Testing a security requirement example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
Examining the report design and GrantExp property . . . . . . . . . . . . . . . . . . . . . 149
Customizing the Security ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
Using GetUserACL( ) to create a Security ID . . . . . . . . . . . . . . . . . . . . . . . . . . 152
Customizing the Access Control List. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
Using the CascadeSecurity property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
Using the GetFullACL( ) method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
Using the SetSecurity( ) method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
About the secure read privilege. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154

Chapter 9
Programming for report viewing events . . . . . . . . . . . . . . . . . . . 155
About report viewing events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
Objects that respond to report viewing events. . . . . . . . . . . . . . . . . . . . . . . . . . 156
Mouse events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
Responding to mouse events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
About the Shift value in mouse event methods . . . . . . . . . . . . . . . . . . . . . . . 158
Using the Shift value. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
Creating a context menu. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
About default context menu items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
About the Default Action context menu item. . . . . . . . . . . . . . . . . . . . . . . . . 160
About the Help context menu item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
About the Copy Link context menu item . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
Customizing context menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
Providing help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
Providing balloon help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
Providing context-sensitive help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163

Chapter 10
Using and customizing a stored procedure . . . . . . . . . . . . . . . . 167
About stored procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
About stored procedure result sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
Using stored procedure tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
Designing a report with stored procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171

vi
Working with stored procedures dialogs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
Working with data from a stored procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
Synchronizing the stored procedure design . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
Narrowing a search and matching patterns in stored procedures. . . . . . . . . . . . . . . 177
Working with sample values for input parameters . . . . . . . . . . . . . . . . . . . . . . . . 179
About input and output parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
About Oracle8 and Oracle9i stored procedures . . . . . . . . . . . . . . . . . . . . . . . . . . 182
About stored functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
Using the Stored Procedure Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
Overriding the OpenCursor method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
Understanding the data retrieval example. . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
About the EMP table in the example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
About the stored function in the example . . . . . . . . . . . . . . . . . . . . . . . . . . 184
About the Stored Procedure Data Source Builder in the example . . . . . . . . . . . . . 186
About parameters in the example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
About the Requester in the example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
About the report in the example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
Customizing a stored procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
Accessing a stored procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
Working with a Sybase stored procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
Working with an Oracle stored procedure . . . . . . . . . . . . . . . . . . . . . . . . . . 191
Working with a stored procedure’s return value. . . . . . . . . . . . . . . . . . . . . . . 192
Working with a stored procedure to return an ID . . . . . . . . . . . . . . . . . . . . . . 192
Accessing Sybase SQL Server multiple result sets . . . . . . . . . . . . . . . . . . . . . . . 193
Accessing Oracle8 and Oracle9i stored procedure multiple result sets . . . . . . . . . . . . 194
Adding support in Actuate Basic methods . . . . . . . . . . . . . . . . . . . . . . . . . . 194
Mapping Actuate variable types and Visual Basic type codes . . . . . . . . . . . . . . . . . 198

Chapter 11
Writing custom browser code . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
About custom browser code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
About the browser scripting control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
Including custom browser code in a report design . . . . . . . . . . . . . . . . . . . . . . . 205
About the context block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
Clipping the output of custom browser code . . . . . . . . . . . . . . . . . . . . . . . . . . 206
Aligning the output of custom browser code . . . . . . . . . . . . . . . . . . . . . . . . . . 207
Debugging custom browser code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
Including global custom browser code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209
Creating an HTML form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
Generating custom browser code dynamically . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
Overriding BrowserCode( ) and GetText( ) . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
Determining the application execution context . . . . . . . . . . . . . . . . . . . . . . . 211
Generating output for different browsers. . . . . . . . . . . . . . . . . . . . . . . . . . . 211

vii
 Adjusting for the current scaling factor . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
Overriding the BuildFromRow( ) and OnRow( ) methods . . . . . . . . . . . . . . . . . . . 212
Printing and viewing a report using the PDF converter . . . . . . . . . . . . . . . . . . . . . . 213
Displaying different controls in DHTML and PDF output . . . . . . . . . . . . . . . . . . . 214
ShowWhenPrinting and ShowWhenViewing . . . . . . . . . . . . . . . . . . . . . . . . . . 214
Printing and viewing a report using the Actuate Viewer . . . . . . . . . . . . . . . . . . . . . 214
Creating an example library for Internet Explorer . . . . . . . . . . . . . . . . . . . . . . . . . 215
Using DHTMLForm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
Working with DHTMLForm variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
Working with DHTMLForm methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
Subclassing DHTMLForm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
Working with DHTMLMenuControl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
Working with DHTMLMenuControl variables . . . . . . . . . . . . . . . . . . . . . . . . 218
Working with DHTMLMenuControl methods . . . . . . . . . . . . . . . . . . . . . . . . 218
Subclassing DHTMLMenuControl. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
Displaying custom browser code in the Viewer . . . . . . . . . . . . . . . . . . . . . . . 221
Displaying custom browser code output in a web browser . . . . . . . . . . . . . . . . . 222
Creating a report for viewing in Netscape. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222

Chapter 12
Designing a report for XML data. . . . . . . . . . . . . . . . . . . . . . . . . . 225
About the XML data format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
About Document Type Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
Examining a simple XML document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
About the View process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
Publishing an Actuate report as XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
Mapping XML to Actuate report sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
About XML properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
About AcReport XML properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
About AcReportComponent XML properties . . . . . . . . . . . . . . . . . . . . . . . . 232
About AFC XML functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232

Chapter 13
Understanding report bursting techniques . . . . . . . . . . . . . . . . . 237
About report bursting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
Understanding report bursting techniques . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
Understanding report bursting tasks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
Examining report bursting examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
Examining a subreport bursting example . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240
Examining the report structure for a subreport bursting example . . . . . . . . . . . . . 241
Examining the detail report’s PageList component for a subreport bursting example. . 241
Examining the detail query for a subreport bursting example . . . . . . . . . . . . . . . 242

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

Part 3
Programming with Actuate Basic
Chapter 14
Introducing Actuate Basic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
About Actuate Basic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
Programming with Actuate Basic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251
Understanding code elements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
About statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
About expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
About operators. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
Using an arithmetic operator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
Using a comparison operator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
Working with logical operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
Using the concatenation operator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
About operator precedence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
Adhering to coding conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
Commenting code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
Breaking up a long statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
Placing short, related statements on a single line . . . . . . . . . . . . . . . . . . . . . . . . 257
Indenting code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
Using a consistent naming and style convention . . . . . . . . . . . . . . . . . . . . . . . . 257
About naming rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
Using the code examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258

Chapter 15
Understanding variables and data types. . . . . . . . . . . . . . . . . . . 259
About variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
Declaring a variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
About global variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
Using a local variable. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
About class variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263

ix
Declaring an array . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
About multi-dimensional arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
About dynamic arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
Changing the size of an array . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
About data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
Using standard data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
Using an AFC data type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
Assigning a data type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
Using the As keyword . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
Using a type-declaration character. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
About constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
Working with variant data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
Working with string data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
Declaring a string . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
Using binary string data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
Manipulating a string. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
Formatting strings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
Comparing strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
Changing capitalization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
Removing spaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
Embedding a quote in a string. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
Working with numeric data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
About numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
About currency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
Using numeric data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
Working with date data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
Using Date display formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
Formatting date and time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
Working with a user-defined data type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
Using an alias . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
Using a structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
Using a class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
Working with a CPointer data type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
Converting a data type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277

Chapter 16
Writing and using a procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
About procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
About scope in procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
About methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
Creating a global procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
Declaring a procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282

x
 Declaring a Sub procedure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
Declaring a Function procedure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
Declaring an argument . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
About argument data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
Passing an argument by reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
Passing an argument by value. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
Calling a procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
Calling a Sub procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
Calling a Function procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
Overloading a procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
Using a control structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
Using If...Then. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
Using If...Then...Else . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
Using Do...Loop. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
Using For...Next . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
Using a nested control structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
Exiting a control structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
Exiting a Sub or Function procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287

Part 4
Programming in the Windows environment
Chapter 17
Using an object from another application. . . . . . . . . . . . . . . . . . 291
Adding an object from another application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
About object linking and embedding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
About supported OLE objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
About OLE custom controls (OCX) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
Understanding linking and embedding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
Working with a linked object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
Working with an embedded object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295
Guidelines for linking and embedding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
Linking and embedding an OLE object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
Editing an OLE object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299
Inserting an OLE custom control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300
Moving and sizing an OLE component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
Subclassing an OLE component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302

xi
Chapter 18
Programming an object from another application . . . . . . . . . . . 303
About programming other applications’ objects . . . . . . . . . . . . . . . . . . . . . . . . . . 304
About OLE Automation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
Differentiating an OLE Automation object from another OLE object . . . . . . . . . . . . . 304
Determining which OLE Automation objects an application supports . . . . . . . . . . . . 304
Creating an OLE Automation object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
Working with an OLE Automation object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
Using an OLE Automation example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306

Chapter 19
Calling an external function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
Calling an external C function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
Using a C function with Actuate Basic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
Declaring a C function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
Declaring the C function as a Sub procedure . . . . . . . . . . . . . . . . . . . . . . . . . . 311
Declaring the C function as a Function procedure . . . . . . . . . . . . . . . . . . . . . . . 311
Understanding C function declaration issues . . . . . . . . . . . . . . . . . . . . . . . . . . 311
Specifying the library of a C function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
Passing an argument by value or reference . . . . . . . . . . . . . . . . . . . . . . . . . . 312
About flexible argument types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
Aliasing a non-standard C function name . . . . . . . . . . . . . . . . . . . . . . . . . . 313
Determining an Actuate Basic argument type . . . . . . . . . . . . . . . . . . . . . . . . . . 313
Calling a C function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
Calling a C function with a specific data type . . . . . . . . . . . . . . . . . . . . . . . . . . 315
Passing a string to a C function. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
Passing an array to a C function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
Passing a null pointer to C function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
Passing a user-defined data type to a C function . . . . . . . . . . . . . . . . . . . . . . . 316
Passing an object reference variable to a C function . . . . . . . . . . . . . . . . . . . . . 316
About return values from C functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
Working with a Java object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
About Java requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
Creating a Java object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
Invoking a method and accessing a field on a Java object . . . . . . . . . . . . . . . . . . . 317
Invoking a static method and accessing a static field . . . . . . . . . . . . . . . . . . . . . . 318
Converting a Java data type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
Converting a Java String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
Converting a Java null . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
Converting an array. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
About Java exception and error handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
Debugging a Java object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321

xii
Part 5
Programming with Actuate’s C++ APIs
Chapter 20
Using Actuate’s application programming interfaces . . . . . . . . 325
About the programming interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
About the Report Server API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
About the Requester API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
About the search extension API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
About the Actuate ActiveX controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
A comparison of API features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328
Choosing the appropriate API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
When to use the Report Server API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
When to use the Requester API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
When to use the search extension API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
When to use Actuate ActiveX controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330

Chapter 21
Requester API user guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
About the Requester API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334
Understanding the Requester API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334
Working in the client-server environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
Working locally . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336
Using the Requester API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336
About the Requester API development environment . . . . . . . . . . . . . . . . . . . . . 337
Identifying the APIs to your application . . . . . . . . . . . . . . . . . . . . . . . . . . . 337
Selecting a compiler and other tools. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337
Choosing API files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338
Choosing a DLL file for the Windows environment . . . . . . . . . . . . . . . . . . . . . 339
Working with UNIX libraries and path variables . . . . . . . . . . . . . . . . . . . . . . 340
About the Requester API operating environment. . . . . . . . . . . . . . . . . . . . . . . . 340
Using the Requester API with the Actuate Viewer . . . . . . . . . . . . . . . . . . . . . 341
Understanding API functions by programming tasks . . . . . . . . . . . . . . . . . . . . . . . 341
Writing startup and cleanup code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342
Working with report files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342
Specifying a local file name—Requester API . . . . . . . . . . . . . . . . . . . . . . . . . 343
Specifying an iServer file name—Requester API. . . . . . . . . . . . . . . . . . . . . . . 343
Getting the parameter and parameter group names . . . . . . . . . . . . . . . . . . . . . . 344
Getting the parameter attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345
Getting the default parameter values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346

xiii
 Getting the current parameter values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346
Setting parameter values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
Configuring a printer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348
Running, viewing, and printing reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348
Running a report locally. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349
Checking for errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349
Functions with direct error checking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
Functions that do not support error checking . . . . . . . . . . . . . . . . . . . . . . . . 350
Writing a Requester API application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
Writing an application that uses iServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351
Initializing an API session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351
Connecting to iServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351
Specifying parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
Running and viewing the report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
Printing the report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
Closing the API session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
Writing an application for local reports. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354
Declaring a Visual Basic method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354
Initializing an API session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355
Specifying parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355
Generating a report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356
Viewing a report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356
Printing a report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356
Closing a session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356
Processing a report request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
Using the Requester API in Actuate Basic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358
Generating a report in Actuate Basic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358
Using the Requester API in Visual Basic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360
Accessing the Requester API from Visual Basic . . . . . . . . . . . . . . . . . . . . . . . . . 360
Specifying the DLL in the Declare statement . . . . . . . . . . . . . . . . . . . . . . . . . 360
Manipulating parameter values, generating and printing a report . . . . . . . . . . . . . . 361
Creating a custom dialog for requesting parameter values. . . . . . . . . . . . . . . . . . . 366
Using the Requester in a C++ application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368
Working with a BSTR in the Windows environment . . . . . . . . . . . . . . . . . . . . . . 368
Working with BSTRs in C++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369

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

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

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

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

Chapter 23
Search extension API user guide. . . . . . . . . . . . . . . . . . . . . . . . . 461
About the search extension API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462
Search extension API functions by programming task . . . . . . . . . . . . . . . . . . . . . . 462
Writing startup and cleanup code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463
Setting search parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463
Processing search results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 464
Developing a search extension . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 464
Writing search extension code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 464
Creating a definition file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465
Creating a header file. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 466
Compiling the code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 466
Installing a custom search extension. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 466

Chapter 24
Search extension API reference. . . . . . . . . . . . . . . . . . . . . . . . . . 467
Close. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 468
GetColumnDelimiter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 468
GetName . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 469
GetParameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 469
IncludeHeader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 469
InputParameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 470
Open. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 470
PutRow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 470
SetDataTypeInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471
SetParameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 472
Chapter 25
Actuate ActiveX controls user guide. . . . . . . . . . . . . . . . . . . . . . 473
About Actuate’s ActiveX controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474
Features of ActiveX controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474
Adding the Actuate ActiveX controls to your application . . . . . . . . . . . . . . . . . . . 474
Adding the Actuate ActiveX controls to Visual Basic. . . . . . . . . . . . . . . . . . . . . . 474

xvii
 Adding the Actuate ActiveX controls to C or C++ . . . . . . . . . . . . . . . . . . . . . . . 475
Using ActiveX controls embedded in dialogs . . . . . . . . . . . . . . . . . . . . . . . . . . 475
About report files and the Actuate ActiveX controls . . . . . . . . . . . . . . . . . . . . . . . . 476
Specifying local file names for Actuate reports . . . . . . . . . . . . . . . . . . . . . . . . . 476
Specifying iServer file names for Actuate reports . . . . . . . . . . . . . . . . . . . . . . . . 476
Actuate ActiveX methods by programming task . . . . . . . . . . . . . . . . . . . . . . . . . . 477
Opening and closing a report instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477
Navigating and viewing the report instance . . . . . . . . . . . . . . . . . . . . . . . . . . . 478
Running a report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 479
Printing, mailing, and saving a report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 480
Invoking functions in an open report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 480
Handling error conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 481
Visual Basic example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 482
Building the sample application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 482
Visual Basic code segment descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484
Running the sample application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 485
Installing Actuate ActiveX controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 486
Choosing API files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 488
API file name conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 488
API file versions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 489

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

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

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

xix
xx
 Intro ductio n

Understanding Actuate 7
Actuate® 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

Introduction xxi
 Addressing diverse customer profiles
Actuate’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 requirements

Customers 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

requirements
To 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 server

Independent 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.

xxii Programming e.Repor ts

Providing a complete information delivery
solution
Actuate’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.

Infrastructure element Function Actuate role

Databases Organize data. Actuate’s design tools
support accessing,
managing, and
updating data.
Content management Manage structured Actuate iServer
systems content. supports publishing
structured content such
as electronic catalogs.
Application servers Deploy online Actuate web
applications. applications, including
Actuate Active Portal
and Management
Console, support
conducting complex
transactions, managing
supply chains, and
interacting with
customers.

Actuate 7 continues to offer core solutions for fundamental enterprise

reporting and information delivery challenges, as described in the following
table.

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.

Introduction xxiii
 Challenge Actuate solution
Meet varied information display Provide:
requirements. ■ Template-based design and
display.
■ Complex formatting capabilities.
■ Spreadsheet reporting.
Meet exploding requirements for Support well over one million hits a
web-based content delivery. day on a single CPU.
Deliver personalized, secure Provide open security directory
information. integration and page-level security.
Reuse existing integrated content. Provide access to content from other
applications using open server
technology.
Maintain data integrity between Provide high-resolution printed copy
online and hard copy. from PostScript and PDF.
Transfer information among Provide XML output to support
applications. access to data across applications.
Meet increasing requirements for Support clustering and failover.
server-based reporting

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.

xxiv Programming e.Repor ts

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:

Introduction xxv
 ■ 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.

xxvi Programming e.Repor ts

 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

Introduction xxvii
 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 Release notes
software and documentation
Overview of Actuate reporting
concepts
How to build your first report Developing
Advanced
How to design reports using the e.Reports
graphical user interface

Conceptual information about how

to program with Actuate Foundation
Classes
Programming
Customizing e.reports e.Reports
Actuate Basic programming
fundamentals
Programming in the Windows
environment
Actuate’s C++ APIs
Accessing, viewing, running,
printing and searching reports
Using
e.Reports

xxviii Programming e.Repor ts

 For information about this topic See the following resource
Formatting report data for multiple
locales
Understanding report encoding Working
with Multiple
Designing reports with right to left Locales
orientation

Actuate Foundation Classes, their

properties, variables, and methods
Actuate
Foundation
Class
Reference

Actuate Basic statements and

functions
Actuate Basic
Language
Reference

Terminology map
Glossary
Actuate 7
Glossary

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.

Introduction xxix
 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.

xxx Programming e.Repor ts

■ 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.

Introduction xxxi
Online documentation
The 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 manuals

The 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 help

Actuate 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 help

Sections 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 system

Use 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.

xxxii Programming e.Reports

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.
Choose Index to view the topics
Type the keyword for which to search the index

Select a topic from the list and

choose Display to view its
contents

Introduction xxxiii
 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.
Choose Search
Type the keyword for which to search

Select a topic from the list and

choose Display to view its
contents

Using report-specific online help

During 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.

Report-specific online help

For detailed information about report-specific online help, see Chapter 3,

“Viewing an e.report,” in Using e.Reports.

xxxiv Programming e.Repor ts

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

Item Convention Example

Code examples Sans serif Dim Text1 As String
File names Initial letter capitalized, Detail.roi
except Formula One
e.Report Designer,
where file names are
case sensitive
Key combination A + sign between keys Ctrl+Shift
means to press both
keys at the same time
Menu items Capitalized, no bold File
Submenu items Separated from the File➛New
main menu item with a
small arrow
User input or user Sans serif M*16*
response
User input in XML and Italics chkjava.exe
Java code cab_name.cab

Syntax conventions
The following table describes the symbols used to present syntax.

Symbol Description Example

[] Optional item [Alias<alias name>]
Array subscript matrix[ ]

<> Argument you must <expression to format>

supply
Delimiter in XML <xsd:sequence>

Introduction xxxv
 Symbol Description Example
{} Groups two or more {While | Until}
mutually exclusive
options or arguments,
when used with a pipe
Defines array contents {0, 1, 2, 3}
Delimiter of code block public ACJDesigner( )
{
}

| Separates mutually Exit {Do | For |

exclusive options or Function | Sub}
arguments in a group
Java OR operator int length |4

xxxvi Programming e.Repor ts

 Part

Programming with the

Part 1

Actuate Foundation Classes

Par t 1 , Programming w ith the Actua te Foun da ti on C lasse s 1

2 Programming e.Repor ts
 Chapter

Understanding the
Chapter 1

Actuate Foundation
Classes
This chapter contains the following topics:
■ About the Actuate Foundation Class architecture
■ Understanding the AFC by functional category

Chapter 1, Understanding the Actuate Foundation Classes 3

About the Actuate Foundation Class architecture
The 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 classes

The 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.

4 Programming e.Repor ts
 AcComponent

AcConnection AcDataRow

AcDataAdapter AcReportComponent

AcDBConnection AcVisualComponent AcSection AcPageList

AcDataSource AcDataFilter AcReport

AcFlow AcBaseFrame AcControl

The following table describes these classes.

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
■ Sybase
For more information about the classes that
support connecting to these databases, see
Actuate Foundation Class Reference.

Chapter 1, Understanding the Actuate Foundation Classes 5

 Base class Description
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.

About concrete classes

A 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.

6 Programming e.Repor ts
Understanding the AFC by functional category
The 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

AcComponent

AcReportComponent

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.

Chapter 1, Understanding the Actuate Foundation Classes 7

 About connection classes
AcReportComponent

AcConnection AcDBStatement AcDBCursor

AcDBConnection

AcDB2Connection

AcInformixConnection

AcMSSQLConnection

AcODBCConnection

AcOracleConnection

AcProgressConnection

AcProgressSQL92Connection

AcSAPConnection
AcSAPConnecti

AcSybaseConnection

AcSybaseDBLibConnection

Classes in this category provide communication links for Actuate reports.

About connection abstract base classes

AcConnection and AcDBConnection are abstract base classes. Do not derive
directly from them.

About connection concrete classes

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

8 Programming e.Repor ts
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

AcReportComponent

AcDataRow

AcDataAdapter

AcDataSource

AcDatabaseSource

AcQuerySource

AcTextQuerySource

AcSQLQuerySource

AcStoredProcedureSource

AcDataFilter

AcSingleInputFilter

AcMemoryBuffer

AcRecordBuffer

AcMemoryDataSorter

AcMultipleInputFilter

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

About data stream abstract base classes

AcDataAdapter 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.

Chapter 1, Understanding the Actuate Foundation Classes 9

 About data stream concrete classes
AcMemoryBuffer, 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

AcReportComponent

AcSection

AcDataSection

AcReportSection

AcGroupSection

AcSequentialSection

AcConditionalSection

AcParallelSection

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 classes

AcSection and AcDataSection are abstract base classes. Typically, you do not
derive from them.

About report section concrete classes

Use AcReportSection, AcGroupSection, AcSequentialSection,
AcConditionalSection, and AcParallelReport to organize data in a report.

10 Programming e.Repor ts
About page layout classes
AcComponent

AcReportComponent

AcVisualComponent

AcBaseFrame

AcBasePage

AcSubPage

AcPage

AcDataFrame

AcFrame

AcFlow

AcLinearFlow

AcTopDownFlow

AcPageList

AcSimplePageList

AcLeftRightPageList

AcTitleBodyPageList

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

About page layout abstract base classes

AcBaseFrame, AcBasePage, AcDataFrame, AcFlow, and AcPageList are
abstract base classes. You typically do not derive from them.

About page layout concrete classes

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

Chapter 1, Understanding the Actuate Foundation Classes 11

 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.

12 Programming e.Repor ts
About control classes
AcVisualComponent

AcCrosstab

AcControl

AcLabelControl

AcTextualControl

AcBrowserScriptingControl

AcDataControl

AcTextControl

AcDynamicTextControl

AcIntegerControl

AcDoubleControl

AcCurrencyControl

AcDateTimeControl

AcImageControl

AcLineControl

AcRectangleControl

AcEllipseControl

AcOLEControl

AcOLEContainerControl

AcChart

AcSummaryChart

AcDetailChart

AcHLCChart

AcPageNumberControl

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

Chapter 1, Understanding the Actuate Foundation Classes 13

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

About control concrete classes

Use 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

AcPopupMenu AcReportController AcReportView AcVisitor

AcXMLDataVisitor

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

AcCollection AcIterator

AcOrderedCollection AcSingleListIterator

AcList

AcSingleList

AcObjectArray

AcBTree

14 Programming e.Repor ts
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.

Chapter 1, Understanding the Actuate Foundation Classes 15

16 Programming e.Repor ts
 Chapter

Working with a class

Chapter2

This chapter contains the following topics:

■ About classes
■ Declaring a class
■ Understanding class relationships
■ About class variables
■ About methods

Chapter 2, Working with a class 17

About classes
This 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 class
Actuate 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:

18 Programming e.Repor ts
■ 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 AcColor
Dim AlternateLines As Integer
Static OriginalColor As AcColor
Static RowNumber As Integer
' Class declarations for nested classes
Class ItemCode Subclass Of AcTextControl
...
End Class
' Methods
Sub SetProperties( )
Super::SetProperties( )
AlternateColor = 15527148
AlternateLines = 2
BackgroundColor = 14408667
Size.Height = 12703
Size.Width = 400
End Sub
Sub OnStart( )
Super::OnStart( )
OriginalColor = BackgroundColor
RowNumber = RowNumber + 1
If RowNumber > AlternateLines * 2 Then
RowNumber = 1
End If
IF RowNumber > AlternateLines Then
BackgroundColor = AlternateColor
End If
End Sub
...
End Class

Chapter 2, Working with a class 19

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

Understanding class relationships

Classes 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:

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.

About inheritance
In 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.

20 Programming e.Repor ts
About scope
Scope 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
...

Chapter 2, Working with a class 21

 End Class
End Class

Understanding class scope naming conventions

Using 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 design

In 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.

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

CustomerReportApp

CustomerSection
CustomerFrame CustomerReportApp
Global scope scope
CustomerNameControl
CustomerPhoneControl
CustomerFrame
scope

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

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

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.

Chapter 2, Working with a class 23

 About the default scope of a class in a library
Because 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 variables

A 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 AcPoint
Dim 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 Integer
Static RowNumber As Integer

About variables in Component Editor

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

24 Programming e.Repor ts
 Component Editor
supports three types of
variables

The following table describes these types of variables by function.

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.

About visibility of variables in Component Editor

Assign 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

Chapter 2, Working with a class 25

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

Visibility type Description

Essential Variable is a property that appears in the Properties page
Property 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.

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 variables

Properties 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.

26 Programming e.Repor ts
 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 = 22
Font.FaceName = "Arial"
...
End Sub

Chapter 2, Working with a class 27

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

Using parameters
Specify 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

28 Programming e.Repor ts
 When the user
runs a report,
Requester
prompts for
parameters

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

Using regular variables

A 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.

Chapter 2, Working with a class 29

About methods
Methods 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 methods
There 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.

30 Programming e.Repor ts
 Methods page displays
methods according to the
filter option you select

Display only overridden and

locally defined methods

Display the most commonly

used local and overridable
methods
Display local and
overridable methods

Display local methods and

methods you can override
and call
Display all methods

About methods you can override

The 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 call

Callable 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.

Chapter 2, Working with a class 31

 About private methods
The 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 method
Overloading 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 Integer
Function Sum( num1 As Double, num2 As Double) As Double
Function 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.

32 Programming e.Repor ts
 Chapter

Working with an object

Chapter3

This chapter contains the following topics:

■ About objects
■ Creating an object
■ Using an object reference variable
■ About object lifetime

Chapter 3, Working with an object 33

About objects
An 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 object
There 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 variable

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

34 Programming e.Repor ts
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 class

You 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.

Chapter 3, Working with an object 35

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

Declaring an object reference variable as AnyClass type

If 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

36 Programming e.Repor ts
 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 variable

Once 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 variable

A 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 Integer
Number1 = 7
Number2 = Number1 'Number2 contains the value 7
Number1 = 77
Print Number1 'Prints 77
Print Number2 'Prints 7
The following illustration shows the result of the preceding code:

7 77

Number1 Number2

Chapter 3, Working with an object 37

 Working with an object reference variable
An 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 variable
Dim LabelControl1 As AcLabelControl
' Create the object
Set LabelControl1 = New AcLabelControl
' Set the Text property of the label
LabelControl1.Text = "Annual Sales Report"
The following illustration shows the result of the preceding code:

.
.
LabelControl1
Text Annual Sales Report
Object reference variable .

Object

The following code assigns another object reference variable, LabelControl2, to

the first object reference variable, LabelControl1:
Dim LabelControl2 As AcLabelControl
Set LabelControl2 = LabelControl1
LabelControl2.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 .
Text Monthly Sales Report
LabelControl2
.
Object reference variables
Object

38 Programming e.Repor ts
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 methods

To 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.

BackgroundColor

BorderStyle

myLabel Start( )

Object reference variable Build( )

...

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.BackgroundColor
MyLabel.Build( )
To change the characteristic of the label, assign a value to one of its variables:
MyLabel.BackgroundColor = Yellow

Chapter 3, Working with an object 39

 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.

Object reference var:

Container CanMoveUp

BackgroundColor Position
myLabel
BorderStyle Build( )

Object reference variable ... ...

ObjectA ObjectB

In this case, you can build the following path:

myLabel.Container.CanMoveUp

Referencing a method of a class

You 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 superclass

To 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 name

You 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

40 Programming e.Repor ts
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 call

Inheritance 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
Beep
End Sub
...
End Class

Class DerivedClass Subclass of BaseClass

'DerivedClass inherits method X and redefines method Y

...
Sub Y
Super::Y

Chapter 3, Working with an object 41

 MsgBox "This operation is invalid"
End Sub

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

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

MyObject.Y 'Refers to Y( ) in DerivedClass

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

Assigning an object to an object reference

variable
Use 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 AcControl
Dim Control2 As AcControl

Set Control1 = New AcControl

Set 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 AcTextControl
Dim Control2 As AcControl

Set Control1 = New AcTextControl

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

42 Programming e.Repor ts
 Dim Control1 As AcTextControl
Dim Control2 As AcControl

SetControl2 = New AcControl

SetControl1 = Control2 'Runtime error—Illegal handle conversion

Comparing Set and Let

You 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 AcLabelControl
Dim y As AcLabelControl

Set x = New AcLabelControl

y=x 'Compile time error—Invalid assignment

Setting an object reference variable to Nothing

When 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 procedure

As 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 'Twips
AnyControl.Size.Height = 1000 'Twips
End Sub
The function in the following example creates a label and returns a reference to
it:
Function NewLabel( ) As MyLabelControl
Set NewLabel = New MyLabelControl
End Function

Chapter 3, Working with an object 43

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

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.

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

Testing an object reference with the Is operator

Use 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 Nothing

Use 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

44 Programming e.Repor ts
 Comparing object reference variables
Use 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 Boolean
Dim element As AcVisualComponent
Dim iter As AcListIterator
Set iter = frame.ContentList.NewIterator( )
Do While iter.HasMore( )
Set element = iter.GetNext( )
If element Is Control Then
IsInFrame = True
Exit Function
End If
Loop
IsInFrame = False
End Function

About object lifetime

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

About transient objects

Some 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.

Chapter 3, Working with an object 45

 About persistent objects
Many 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.

46 Programming e.Repor ts
 Chapter

Using Component Editor

Chapter 4

This 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

Chapter 4, Using Component Editor 47

About Component Editor
Use 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 class

Component 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

48 Programming e.Repor ts
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 class

To 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.

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

Scope of class.
File where component
resides if the component is
in a library.

Private check box. If

checked, the class does not
appear in the library view.

Chapter 4, Using Component Editor 49

 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.

An inherited variable
appears in grey.

A variable declared in the

class appears in black.

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.

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

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

Viewing and setting property values

To 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 method
To 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

Chapter 4, Using Component Editor 51

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

Methods page displays

methods according to the
filter option you select

Display only overridden

and locally defined
methods
Display local and
overridable methods

Display local methods and

methods you can override
and call
Display inherited
methods you can call,
but not override
Display all methods,
including those you
normally do not override
or call

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 variable

You 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.”

52 Programming e.Repor ts
Creating a class variable
To 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.

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

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.

Chapter 4, Using Component Editor 53

 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.

54 Programming e.Repor ts
 The options differ depending on whether you select Instance or Static in
step 7. The following table describes the options.

Visibility option Description Applies to

Essential Variable appears in Properties. Instance variable
Property e.Report Designer Professional
prompts the report developer to
supply a value at design time.
Parameter Variable appears in Requester Static variable
when a user runs the report. The
user can type or select a value to
set additional run-specific filter
conditions.
Private Variable appears in the Variables Instance and
page of the class in which it is static variables
declared.
Property Variable appears in Properties. Instance variable
The report developer can supply
a value at design time.
Public Variable appears in the Variables Instance and
page of the class and its static variables
subclasses.

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 variable
You 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.

Chapter 4, Using Component Editor 55

 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 method

You 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 method
Use 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.

56 Programming e.Repor ts
 ■ 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 Boolean
Start = 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 method

You 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.

Chapter 4, Using Component Editor 57

 Creating a method
There 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.

Specify the method name

Specify the method’s

return type, if needed

4 Type a name for the method.

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

58 Programming e.Repor ts
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 method
e.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.

Chapter 4, Using Component Editor 59

 ■ Use unambiguous descriptive names that reflect the method’s purpose.
For example, a name such as ReadDataRow is more informative than
DoDataRow.

Editing a method
You 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.

60 Programming e.Repor ts
Deleting a method
You 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.

Chapter 4, Using Component Editor 61

62 Programming e.Repor ts
 Chapter

Understanding document
Chapter 5

generation
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

Chapter 5, Understanding document generation 63

Overview of the Factory service
The 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.

Design Generate Compile Factory

code service
Viewer
ROD BAS ROX
or
DOX
ROI
or Printer
ROV DOI
or
DOV

Server
activity Actuate
results in Active Portal
DHTML
output

Browser

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.

64 Programming e.Repor ts
 The following illustration gives a conceptual overview of activities that occur
in the process of generating an Actuate report.
Input Source

Data

1. Delivers a 3. Passes
data row a frame
Data
Section Page list
stream

2. Creates 4. Creates a
contents page as
needed
Frame and Page and
control flow ROI

The following illustration shows the major categories of processing, data

streams, content creation, and page creation.
Input Source

Data

Rows
Data rows Frames
Data Page Pages
Content ROI
stream layout
Events

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 service

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

Chapter 5, Understanding document generation 65

 ■ 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 code

You 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.

Method Called ... Example of use

Start( ) After the Factory service ■ Initialize a global
instantiates the document, variable.
before document generation
■ Verify or adjust
begins
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 ■ Send a completion
generates, before the ROI or notice to a user.
DOI file closes
■ Write statistics to a
log file.

Starting the build process

One 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.

66 Programming e.Repor ts
 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.
Content structure Page structure
Report

Report section Page list

Group section Group section Page Page

Frame Frame Frame Frame Flow Flow Flow Flow

Frame Frame Frame Frame

Frame Frame Frame Frame

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 content
All 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.

Chapter 5, Understanding document generation 67

 Using the core protocol for content creation
AcReportComponent 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.

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 Builds the object’s contents. For example, a report
BuildFromRow( ) 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.

Using a component reference in content creation

A 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.

68 Programming e.Repor ts
Structure Implementation

Report
Build( ) Report Section
New( )
Start( )
Build( ) Frame
Finish( ) New( ) Controls
Start( ) New( )
Start( )
Build( ) Build( )
Finish( ) Finish( )

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.

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.

Chapter 5, Understanding document generation 69

 Method Task
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.

Using a group section to implement the content-creation

protocol
A 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.
Nested group sections in Sort key value in
the structure the Key property
[offices.officeID]

[salesreps.last]

[customers.customName]

[orders.orderID]

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.

70 Programming e.Repor ts
The following table describes how the group section 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.

Using a frame to implement the content-creation protocol

A 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( ) 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.

Chapter 5, Understanding document generation 71

 Using a control to implement the content-creation
protocol
A 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.

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.

Creating a page
The 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.
Passes
a frame
Section Page list
Sends
Creates an event Creates a page
contents as needed

Frame and Page and

control flow

72 Programming e.Repor ts
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 frame

A 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 list

Before 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

Chapter 5, Understanding document generation 73

 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.

Page header for report 1

Section1 page header 2

Section2 page header 3

Section2 page footer 3

Section1 page footer 2

Page footer for report 1

Instantiating a class
When 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.

74 Programming e.Repor ts
 Component references
the report section
supports

Component
reference
properties

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.”

Chapter 5, Understanding document generation 75

Working with a data stream
A 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 adapters

A 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 stream

A 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.
Input source

Data

Data source Report section

Data row 1

Data stream

76 Programming e.Repor ts
 Input source

Data

Data source Data filter Report section

Data row 1 Data row 2

Data stream

Input source

Data

Data source Data filter Data filter Report section

Data row 1 Data row 2 Data row 3

Data stream

Input source Input source

Data Data

Data source
(customers)
Data row 1
Data source Multi-input
(orders) data filter
Data row 2 Data row
Data source
(items)
Data row 3
Data stream

Report section

Chapter 5, Understanding document generation 77

 About the protocol for a data adapter
A 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.

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.

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.

78 Programming e.Repor ts
 Order of instantiation
Data source Data filter1 Data filter2 Report section

Flow of data

Sequential and random access to data

Typically, 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( )

Chapter 5, Understanding document generation 79

 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 sources

A 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.

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.

About data filters

A 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

80 Programming e.Repor ts
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.

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.

About data rows

The 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 cycle

This 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( ).

Chapter 5, Understanding document generation 81

 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.
Input record
Columns

Variables
Data row

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.

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.

82 Programming e.Repor ts
Connecting to a database
A 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 stream

The 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 section

Place 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.

Chapter 5, Understanding document generation 83

 Input Source Class instantiates and owns
another. For example, the data
source owns the data row.
Data
Class uses another class.
For example, the data source
uses the connection.

Data source Report Section

Data Row

Connection

About connection precedence

If 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 support

AcConnection 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

84 Programming e.Repor ts
Data source Connection class
Progress AcProgressConnection
AcProgressSQL92Connection
SAP AcSAPConnection
Sybase AcSybaseConnection
AcSybaseDBLibConnection

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 cursors

To 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.

Chapter 5, Understanding document generation 85

 Report Class instantiates and
section owns another class
Class uses another class
DB
Statement
SQLQuery
Data Connection
Source

DB Cursor

Creating and executing a custom SQL statement

You 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.

86 Programming e.Repor ts
 Part

Customizing report designs

Part 2

Par t 2 , C ustomizing rep or t de signs 87

88 Programming e.Repor ts
 Chapter

Customizing a report
Chapter 6

This chapter contains the following topics:

■ Customizing a data stream
■ Customizing the report layout
■ Customizing report data

Chapter 6, Customizing a report 89

Customizing a data stream
This 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 variable

To 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.

90 Programming e.Repor ts
 Sub OnRead( )
Super::OnRead( )
ExtendedCost = Cost * Quantity
DaysLate = Date( ) - DueDate
If DaysLate < 0 Then
DaysLate = 0
End 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 row

This 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 AcDataRow
Dim row As CustomerRow
Do
Set row = Super::Fetch( )
If row Is Nothing Then
Exit Function
End 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.

Chapter 6, Customizing a report 91

 Creating a select filter
This 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:

92 Programming e.Repor ts
 Function Fetch( ) As AcDataRow
Dim row As CustomerRow

Do
Set row = InputAdapter.Fetch( )
If row Is Nothing Then
Exit Function
End if
Loop until row.State = "CA"
Set Fetch = row
End Function

Creating a sort filter

This 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.

Chapter 6, Customizing a report 93

 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 AcCustomerRow

Dim cust2 As AcCustomerRow

Set cust1 = row1

Set cust2 = row2

' Compare the state. CompareKeys( ) is a predefined method

Compare = CompareKeys( cust1.State, cust2.State )
If Compare <> 0 Then
Exit Function
End If

' Compare the customer id. Compare two integers by subtracting them
Compare = cust1.ID - cust2.ID
End Function

Retrieving data from a flat file

To 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.

94 Programming e.Repor ts
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.

Chapter 6, Customizing a report 95

 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.

96 Programming e.Repor ts
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.

Chapter 6, Customizing a report 97

 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 Boolean
Start = 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 AcDataRow
Dim rowAs DataRow
If EOF (Channel) Then
Exit Function
End If
Set row = New DataRow
Input #Channel, row.First, row.Second, row.Figures
Set Fetch = row
AddRow( 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 sources

To 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.

98 Programming e.Repor ts
■ 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 filter accepts input from two data

sources (input adapters)

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

Chapter 6, Customizing a report 99

 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 adapter

Set UnionIter = InputAdapters.NewIterator
' Initialize CurrentInput to the first input adapter
Set 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 AcDataRow
Do While True
If CurrentInput Is Nothing Then
Exit Function
End If

Set Fetch = CurrentInput.Fetch()

If Not Fetch Is Nothing Then
Exit Function
End 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

100 Programming e.Repor ts

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.

Data from the Orders

table

Data from the Customers

table

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.

Chapter 6, Customizing a report 101

 The following illustration shows the report design.

This filter accepts input from two data

sources (input adapters)
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

The filter creates a new data row that

merges data from the two input
adapters

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 AcDataRow
Dim adapter As AcDataAdapter
' Start the first input adapter
Set adapter = InputAdapters.GetAt(1)

' Retrieve a row from the first input adapter

Dim aOrderDataRow As OrderDataRow
Set aOrderDataRow = adapter.Fetch()

' Start the second input adapter

102 Programming e.Repor ts

 Set adapter = InputAdapters.GetAt(2)

' Retrieve a row from the second input adapter

Dim aCustomerDataRow As CustomerDataRow
Set aCustomerDataRow = adapter.Fetch()

' Create the new data row

Dim aMergedDataRow As MergedDataRow
Set aMergedDataRow = New DataRow( )

' Assign the data from the first row to a variable in the new data row
If Not aOrderDataRow Is Nothing Then
aMergedDataRow.orderID = aOrderDataRow.orders_orderID
Else
aMergedDataRow.orderID = Null
End If

' Assign the data from the second row to a variable in the new data row
If Not aCustomerDataRow Is Nothing Then
aMergedDataRow.customName =
aCustomerDataRow.customers_customName
End If

If aOrderDataRow Is Nothing And aCustomerDataRow Is Nothing Then

Exit Function
End If

Set Fetch=aMergedDataRow
End Function
The following illustration shows the first page of the generated report. Each
row contains data from the Customers and Orders tables.

Chapter 6, Customizing a report 103

Customizing the report layout
e.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 component

By 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

104 Programming e.Repor ts

The following illustration shows the report design.

Generic frame to replace with one of

three city-specific frames when the
report runs

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:

Chapter 6, Customizing a report 105

 Function NewContent( ) As AcReportComponent
Set NewContent = Super::NewContent( )
Dim row As ConditionalExampleDataRow

'Get the current row for the group section

Set 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 Nothing
Exit Function
End If
'Check the value of officeID to create the appropriate frame:
Select Case row.offices_officeID
Case 1
Set NewContent = New Persistent BostonContents
Case 2
Set NewContent = New Persistent NewYorkContents
Case 3
Set NewContent = New Persistent PhiladelphiaContents
End Select
End Function

Dynamically embedding an image control

This 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:

106 Programming e.Repor ts

 ■ 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 here
Dim ImageFile As String
ImageFile = 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 Then
FileName = ConvertStringToBFile( CorpLogo )
GetCleanupViewer.RemoveFileAtTheEnd( FileName )
End If
End 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.

Chapter 6, Customizing a report 107

Customizing report data
Actuate 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 control

This 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 = green
End If
End Sub

Creating a custom control to display a group

section key
This 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.

108 Programming e.Repor ts

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.

Chapter 6, Customizing a report 109

 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.

If the value of PriceCurrencyControl

exceeds $35000, CodeLabelControl
displays Luxury in red

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.

110 Programming e.Repor ts

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 If
End 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 property

A 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.

Chapter 6, Customizing a report 111

 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 If
End 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 Then

lblControlVar.Text = "Luxury"
lblControlVar.Font.Color = Red
End If
End Sub

112 Programming e.Repor ts

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 variable
The 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:
Declare
Global 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.

Chapter 6, Customizing a report 113

114 Programming e.Repor ts
 Chapter

Debugging a report
Chapter 7

This 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

Chapter 7, Debugging a repor t 115

About debugging
Debugging 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 errors

The 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 errors

Compilation 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

116 Programming e.Repor ts

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 errors
Your 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 errors
If 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 window

The 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.

Chapter 7, Debugging a repor t 117

Starting a debugging session
You 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.

118 Programming e.Repor ts

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.

Chapter 7, Debugging a repor t 119

 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.

120 Programming e.Repor ts

 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.

Chapter 7, Debugging a repor t 121

 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.

122 Programming e.Repor ts

Controlling program execution
Using 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 breakpoint
Use 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 code

Setting 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

Chapter 7, Debugging a repor t 123

 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 execution

After 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.

124 Programming e.Repor ts

 Stopping code execution
You 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 values

The 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 changes

To 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.

Chapter 7, Debugging a repor t 125

 Global variables

Local variables

Instance variables

How to open the Variables window

Choose Debug➛Variables Browser.

Interpreting the icons in the Variables window

The 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.

126 Programming e.Repor ts

 Object in current
code context

Control has a variable

that contains a reference
to its container frame

Use and to show

and hide nested levels
of object reference
variables

Checking the value of a specific variable

While 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.

Chapter 7, Debugging a repor t 127

 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 calls

As 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.

128 Programming e.Repor ts

 Last line
executed

Last method called

before code execution
was suspended

Variables associated with

AcODBCConnection

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.

Chapter 7, Debugging a repor t 129

130 Programming e.Repor ts
 Chapter

Designing a report with

Chapter 8

page-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

Chapter 8, Designing a repor t with page-level secur ity 131

About personal views
A 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.

VP VP VP
CTMgr CTMgr CTMgr
Rep1102 Rep1337

1 2 3
VP VP VP
MAMgr MAMgr MAMgr
Rep1002 Rep1076

4 5 6

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 security

Page-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.

132 Programming e.Repor ts

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 ID

A 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 List

The 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.

Chapter 8, Designing a repor t with page-level secur ity 133

 About the GrantExp property for a secure report
The 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.

GrantExp = "VP"

GrantExp = [State] & "Mgr"

GrantExp = "Rep" & CStr( [repID] )

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 security

When 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.

134 Programming e.Repor ts

 Report Encyclopedia Security
data volume data

RSSE

Report User’s
Security
IDs

GrantExp

Access
Control List List of
iServer visible
(one per
page) pages

Designing a report with page-level security

To 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.

Chapter 8, Designing a repor t with page-level secur ity 135

 ■ 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.

136 Programming e.Repor ts

 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.

Chapter 8, Designing a repor t with page-level secur ity 137

 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.

138 Programming e.Repor ts

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( ).

Chapter 8, Designing a repor t with page-level secur ity 139

 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 String
GetUserACL = Super::GetUserACL( acl )

'Get the list of security IDs fo rthe user

CurrentUserACL = 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.

140 Programming e.Repor ts

 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 example

This section examines the security implementation in a report.

Understanding the security scenario example

The 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.

Chapter 8, Designing a repor t with page-level secur ity 141

 Examining the report component for the security
example
The 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 example

The following illustration shows the SQL tab of Query Editor for the example
report.

142 Programming e.Repor ts

Examining the GrantExp property for the security
example
The 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.

Chapter 8, Designing a repor t with page-level secur ity 143

 Examining the page layout for the security
example
The 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.

144 Programming e.Repor ts

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 example

Using 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.

Chapter 8, Designing a repor t with page-level secur ity 145

 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.

146 Programming e.Repor ts

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.

Chapter 8, Designing a repor t with page-level secur ity 147

 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.

148 Programming e.Repor ts

Testing a security requirement example
The 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

property
The 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.

Chapter 8, Designing a repor t with page-level secur ity 149

 GrantExp = [State] & "Mgr"

GrantExp = "Rep" & CStr( [repID] )

GrantExp = "Prod" & [items.itemcode]

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.

150 Programming e.Repor ts

 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 ID

A 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.

Chapter 8, Designing a repor t with page-level secur ity 151

 Using GetUserACL( ) to create a Security ID
You 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 String
Dim tail As String
Dim mgr As String
Dim prod As String
Dim posn As Integer
Dim sid As String
' Loop to get each SID and check whether we want it.
tail = acl
Do While tail <> ""
posn = InStr( tail, "," )
If posn = 0 Then
sid = Trim$( tail )
tail = ""
Else
sid = 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 Then
mgr = sid
ElseIf InStr( sid, "Product Category" ) > 0 Then
prod = sid
End If
Loop
' Build the special ACL, and add it to the list.
If mgr <> "" And prod <> "" Then
acl = acl & ", " & mgr & " " & prod
End If
GetUserACL = acl
End Function

152 Programming e.Repor ts

Customizing the Access Control List
You can customize the Access Control List using the
Security➛CascadeSecurity property, the GetFullACL( ) method, or the
SetSecurity( ) method.

Using the CascadeSecurity property

By 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( ) method

If 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 String
GetFullACL = GetComponentACL( )
End Function

Using the SetSecurity( ) method

Actuate 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 = row
If myRow.AccountType = "Commercial" Then
ACL = "MajorAccts"
ElseIf myRow.AccountType = "Private" Then
ACL = "PrivateBanking"
Else

Chapter 8, Designing a repor t with page-level secur ity 153

 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 String
Dim myRow As MyDataRow
Set myRow = row
If myRow.AccountType = "Commercial" Then
MapAcctTypes = "MajorAccts"
ElseIf myRow.AccountType = "Private" Then
MapAcctTypes = "PrivateBanking"
Else
MapAcctTypes = "Accounting"
End If
End Function

About the secure read privilege

For 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.

154 Programming e.Repor ts

 Chapter

Programming for report

Chapter9

viewing events
This chapter contains the following topics:
■ About report viewing events
■ Creating a context menu
■ Providing help

Chapter 9, Programming for repor t viewing events 155

About report viewing events
Report 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 events

You can manage viewing events for the following objects:
■ Frames
■ Controls
■ Graphs
■ Pages
■ Flows

Mouse events
A 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

156 Programming e.Repor ts

 The following table summarizes the methods associated with mouse events
and the default action the methods execute in response to each event.

Mouse
button Press Release Click Double-click
Left OnLButtonDown( ) OnLButtonUp( ) OnLButtonClick( ) OnLButtonDblClk( )
Default action: Default action: Default action: Default action:
Selects the object Nothing Nothing Nothing
Right OnRButtonDown( ) OnRButtonUp( ) OnRButtonClick( ) OnRButtonDblClk( )
Default action: Default action: Default action: Default action:
Displays a context Nothing Nothing Nothing
menu

For more information about each mouse event method, see Class
AcVisualComponent in Chapter 3, “AFC classes,” in Actuate Foundation Class
Reference.

Responding to mouse events

Actuate 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:

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

Chapter 9, Programming for repor t viewing events 157

 The Shift parameter gives you additional control over mouse events, as
described in the next section.

About the Shift value in mouse event methods

The Shift parameter contains one of the following values:

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

Using the Shift value

Using 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.

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 + Select the object, adding it to the set
press Shift key of previously selected objects, if any
Press left mouse button on object + Toggle the selection state of the
press Ctrl key object
Press left mouse button on object + Toggle the selection state of the
press Shift + Ctrl keys object

The following example shows how AcVisualElement::OnLButtonDown( ) uses

the different Shift values to implement different actions:

158 Programming e.Repor ts

 Function OnLButtonDown( view As AcReportView, Shift As AcShiftKeyState,
x As Integer, y As Integer ) As Boolean
Dim point As AcPoint
point.X = x
point.Y = y

If Not Selectable Then

OnLButtonDown = False
Exit Function
End If

If view.IsSelected( me ) Then
If Shift BAND ControlKey Then
OnLButtonDown = True
view.SelectElement( me, False )
Else
OnLButtonDown = False
End If
Else
OnLButtonDown = True
If Not ( Shift BAND ControlKey Or Shift BAND ShiftKey ) Then
view.DeselectAll
End If
view.SelectElement( me, True )
End If
End Function

Creating a context menu

A 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.

OnRButtonDown( ) OnContextMenu( ) AddMenuCommands( )

Displays context menu Adds menu items to the

context menu

Context menus are only available when the user views the report in the
Actuate Viewer.

Chapter 9, Programming for repor t viewing events 159

 About default context menu items
The context menu displays two items that AddMenuCommands( ) creates as
default values, Default Action and Help.

Default Action OnActuate( )

AddMenuCommand( )
Help OnHelp( )

Context menu

About the Default Action context menu item

When a user chooses Default Action from the context menu, the OnActuate( )
method executes and calls OnFollowLink( ).

Default Action OnActuate( ) OnFollowLink( )

Help

Context menu

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 item

When 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 item

When 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.

160 Programming e.Repor ts

Customizing context menus
If 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.

To... Override
Link one object to another and make this OnFollowLink( ) or set
capability accessible through the Default Action the LinkToExp property
menu item.
Assign a different action to the Default Action OnActuate( )
menu item. For example, a more appropriate
default action for a control that contains a sound
file would be to play the sound.
Add menu items to the default context menu. AddMenuCommands( )
Omit the context menu. If you do not want to OnRButtonDown( )
provide help or let users perform any actions
through the context menu, it would be better to
get rid of the menu altogether.

The following code illustration shows how to create a menu item for the
context menu.
Sub AddMenuCommands( menu As AcPopupMenu)
' Execute the default processing
Super::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 method to execute when
users choose the menu item
The name of the menu item as it
appears in the context menu

Chapter 9, Programming for repor t viewing events 161

 The following illustration shows the context menu the code creates.

Default Action
Help
Evaluate Discount

Providing help
You 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 help

Balloon 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.

162 Programming e.Repor ts

1. In Component Editor, type a string in the
BalloonHelp property of the Status
component

Status
2. Hover the cursor over Status In Evaluation
Closed
Pending

Status of sales

3. The browser displays BalloonHelp

Providing context-sensitive help

You 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.

Chapter 9, Programming for repor t viewing events 163

 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.

OnRButtonDown( ) OnContextMenu( )

Displays context menu

OnHelp( ) AddMenuCommands( )

Displays the string Builds context menu with

specified in HelpText Help as a default menu
item

The following illustration shows how the HelpText string appears when a user
chooses Help.

164 Programming e.Repor ts

1. In Component Editor, enter a string in the
HelpText property of Status
Default Action
Status Help
2. Right-click Status then choose Help In Evaluation
from the Context menu Closed
Pending

Status of sales Closed, Pending, or in Evaluation

3. Help text appears

Chapter 9, Programming for repor t viewing events 165

166 Programming e.Repor ts
 Chapter

Using and customizing a

Chapter10

stored 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

Chapter 10, Using and customizing a stored procedure 167

About stored procedures
A 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 sets

You 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 tools

Actuate e.Report Designer Professional provides a set of tools to work with
stored procedures. These tools include:

168 Programming e.Repor ts

■ 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.

Chapter 10, Using and customizing a stored procedure 169

 ■ 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.

170 Programming e.Repor ts

 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 procedures

A 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.

Chapter 10, Using and customizing a stored procedure 171

 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.

172 Programming e.Repor ts

 The DataSource is deleted from DataStream.

5 Drag Database Source from the Data palette and drop it in DataStream.

Chapter 10, Using and customizing a stored procedure 173

 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 dialogs

After 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.

174 Programming e.Repor ts

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.

Chapter 10, Using and customizing a stored procedure 175

Working with data from a stored procedure
After 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.

176 Programming e.Repor ts

 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 design

Stored 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 procedures
Subgroups 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:

Chapter 10, Using and customizing a stored procedure 177

 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.

178 Programming e.Repor ts

Working with sample values for input parameters
Stored 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.

Chapter 10, Using and customizing a stored procedure 179

 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 parameters

If 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.

180 Programming e.Repor ts

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.

Chapter 10, Using and customizing a stored procedure 181

 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 procedures

The 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 functions

A 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.

182 Programming e.Repor ts

 Stored function

Stored procedure

Overriding the OpenCursor method

Stored 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 (:).

Chapter 10, Using and customizing a stored procedure 183

 For information about processing multiple result sets, see “Customizing a
stored procedure,” earlier in this chapter.

Understanding the data retrieval example

The 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 example

The EMP table contains the following data.

About the stored function in the example

The 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 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;
package body refCur3 as
function GetMgrData(indeptno IN NUMBER,EmpCursor in out empCur,
deptAcct OUT NUMBER )
RETURN mgrCur is

184 Programming e.Repor ts

 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.hiredate
from emp n, emp e
where e.mgr= n.empno and e.deptno= indeptno ;
deptAcct := indeptno + 100;
return MgrCursor;
end;
end;
The report structure is shown below.

Oracle connection
Stored procedure component

Result columns

Chapter 10, Using and customizing a stored procedure 185

 About the Stored Procedure Data Source Builder in the
example
The Stored Procedure Data Source Builder displays the result columns and the
parameters for the stored function REFCUR3.GETMGRDATA.

About parameters in the example

Actuate creates variables on the stored procedure component for the
DEPTACCT and INDEPTNO parameters.

186 Programming e.Repor ts

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 Double

Static 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" )

Chapter 10, Using and customizing a stored procedure 187

 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 example

When 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 example

The report displays the data in the result columns ENAME, MANAGER, and
HIREDATE based on the value of INDEPTNO.

Customizing a stored procedure

Typically, 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 procedure

The following are general steps for calling a stored procedure from an Actuate
application:
1 Connect to the database.

188 Programming e.Repor ts

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

Chapter 10, Using and customizing a stored procedure 189

 /* 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 inproc
Set 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 procedure
statement.DefineProcedureInputParameter("@charin", "v")
' Define the procedure’s output parameters
statement.DefineProcedureOutputParameter( "@charboy", V_STRING )
statement.DefineProcedureOutputParameter( "@int_out", V_INTEGER )

' Open a cursor, which is required when returning rows

Set 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 variables

MsgBox ("binding" )
cursor.BindColumn( 1, "syscolRow", "Id" )
cursor.BindColumn( 2, "syscolRow", "theName" )
MsgBox( "bound" )

' Create the data row

set sRow = New syscolRow( )

' Fetch rows from database

do 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 parameters
rpcParam1 = cursor.GetOutputParameter("@charboy")

190 Programming e.Repor ts

 MsgBox( "Rpc param 1 is " & rpcParam1 )
rpcParam2 = cursor.GetOutputParameter("@int_out")
MsgBox( "Rpc param 2 is " & rpcParam2 )

'Display procedure status value

MsgBox( "Rpc return val is " & cursor.GetProcedureStatus( ) )
set cursor = Nothing

connection.Disconnect( )

Working with an Oracle stored procedure

The 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 Boolean
Dim stmtText As String
Dim stmt As AcDBStatement
Dim Conn As AcDBConnection
Dim 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 Function
End If

arg_in_date = CDate("01/01/2000")
If stmt.DefineProcedureInputParameter("arg_in_date", arg_in_date) = 0
Then
Exit Function
End If

If stmt.DefineProcedureOutputParameter("arg_out_date", V_DATE) = 0 Then

Exit Function
End If

If stmt.Execute() = 0 Then
stmtText = Conn.GetSpecificErrorText()
Exit Function
End If

tempDate = stmt.GetOutputParameter("arg_out_date")

End Function

Chapter 10, Using and customizing a stored procedure 191

 Working with a stored procedure’s return value
The 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 spfunc
CREATE OR REPLACE FUNCTION spfunc ( p_name IN VARCHAR )
-- Declare output parameter
RETURN NUMBER
AS
l_id NUMBER;
-- Declare input parameter
BEGIN
SELECT id INTO l_id FROM sproctable WHERE name = p_name;
RETURN ( l_id );
END spfunc;
/

Working with a stored procedure to return an ID

The 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 AcDBStatement
Dim id As Long
Dim newId As Long
Dim name As Variant

' Prepare the statement

Set 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 procedure
name = "John Smith"
If statement.DefineProcedureInputParameter ( "p_name", name ) = 0 Then

192 Programming e.Repor ts

 PrintString ( "Failed to define input parameter" )
PrintString ( connection.GetSpecificErrorText( ) )
PrintString ( connection.GetGeneralErrorText( ) )
Exit sub
End If

' Define the output parameter

If 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 procedure

If 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 sets

Actuate 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.

Chapter 10, Using and customizing a stored procedure 193

 Accessing Oracle8 and Oracle9i stored procedure
multiple result sets
This 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 methods

Specify 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.

194 Programming e.Repor ts

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.

Chapter 10, Using and customizing a stored procedure 195

 Define the cursors as variables in a subclass of AcDatabaseSource. For
example:
Dim theEmpCursor As AcDBCursor
Dim 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 parameter
create 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:

196 Programming e.Repor ts

 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 String

Dim stmtAs AcDBStatement
Dim id As Integer
Dim deptAcctNoAs Integer
Dim messageAs String
Dim theEmpCursor As AcDBCursor
' Dim theMgrCursor As AcDBCursor
Dim myDataRowAs AcDataRow
stmtText = "BEGIN :mgrCursor := refCur3.GetMgrData (:DEPTNO, :empCursor,
:deptAcct ); END;"

' Prepare the statement

Set stmt = New AcDBStatement( GetDBConnection( ) )
If Not stmt.Prepare( stmtText ) Then
GetDBConnection( ).RaiseError( )
Exit Function
End 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 Function
Else
ShowFactoryStatus( "Stored procedure execution succeeded." )
End if

Chapter 10, Using and customizing a stored procedure 197

 ' Get and print the output parameter values
deptAcctNo = 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 Function
End If
' bind the first result set columns to a data row
Cursor.BindColumn( 1, "StoredProcedureExampleApp::DataRow", "ename" )
Cursor.BindColumn( 2, "StoredProcedureExampleApp::DataRow", "deptno" )
' allocate another AcDBCursor for the other result set
Set theMgrCursor = stmt.AllocateCursor( "mgrCursor" )
If Not theMgrCursor.OpenCursor( ) Then
GetDBConnection( ).RaiseError( )
Set theMgrCursor = Nothing
Exit Function
End If
' bind the second result set columns to the data row
theMgrCursor.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 codes
When 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.

198 Programming e.Repor ts

The following table shows the Actuate variable types and the equivalent
Visual Basic type code.

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

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)

Chapter 10, Using and customizing a stored procedure 199

200 Programming e.Repor ts
 Chapter

Writing custom browser

Chapter 11

code
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

Chapter 11, Writing custom browser code 201

About custom browser code
A 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 control

You 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:
■ <
■ >
■ "

202 Programming e.Repor ts

■ \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.
Label control

<b>MyText</b>

DHTML
converter

&lt;b&gt;MyText&lt;/b&gt;

Web
<b>MyText</b>
browser

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>

Chapter 11, Writing custom browser code 203

 Special characters are not converted. The following illustration shows this
conversion process.
Browser
scripting
control

<b>MyText</b>

DHTML
converter

Context block containing

<b>MyText</b>

Web Output of
browser context block

If the web browser is Internet Explorer, the context block might look like the
following:
<DIV ID="I732" CLASS=C141
STYLE="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.

MyText

204 Programming e.Repor ts

Including custom browser code in a report design
1 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 block

The 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.

Chapter 11, Writing custom browser code 205

 The following example shows a context block in Microsoft Internet Explorer:
<DIV ID="I550" CLASS=C148
onMouseOver="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=109
ID="I578" CLASS=C150
STYLE="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 code

You 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.

206 Programming e.Repor ts

The following table shows how the setting of the BrowserClipping property
maps to the overflow CSS attribute for Internet Explorer.

Setting of
BrowserClipping Setting of overflow Behavior in
property CSS attribute Internet 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.

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.

Setting of
BrowserClipping Setting of clip:rect() Behavior in
property CSS attribute Netscape 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.

Aligning the output of custom browser code

You 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

Chapter 11, Writing custom browser code 207

 ■ 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 code

Because 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.

208 Programming e.Repor ts

Including global custom browser code
You 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.

Chapter 11, Writing custom browser code 209

Creating an HTML form
You 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 dynamically

You 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.

210 Programming e.Repor ts

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 context

You can determine the application execution context using the GetAppContext
and GetReportContext functions, as shown in the following example:
Function GetText( ) As String
Dim rptCtx As Integer
Dim appCtx As Integer
Dim str As String
Dim NL As String
NL = Chr$(10)
appCtx = GetAppContext( )
rptCtx = GetReportContext( )
str = "Application context: " + Str$(appCtx) + NL
str = str + "Report context: " + Str$(rptCtx) + NL + NL
If 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 browsers

To 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 String
Dim str As String
Dim NL As String
NL = Chr$(10)
str = GetUserAgentString( )
If Len(str) = 0 Then

Chapter 11, Writing custom browser code 211

 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 If
End Function

Adjusting for the current scaling factor

When 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 String
Dim dhtmlCode As String
Dim zoom As Double
zoom = GetReportScalingFactor()
dhtmlCode = "<SPACER TYPE=""block"" HEIGHT=" + Str$(150 * zoom)
dhtmlCode = dhtmlCode + " WIDTH=" + Str$(250 * zoom) + ">"
BrowserCode = dhtmlCode
End Function

Overriding the BuildFromRow( ) and OnRow( )

methods
You 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

212 Programming e.Repor ts

 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 variable
Dim dhtmlStr As String
Function BrowserCode( ) As String
BrowserCode = dhtmlStr
End Function
Sub 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.

Chapter 11, Writing custom browser code 213

 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

output
You 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 ShowWhenViewing

If 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.

214 Programming e.Repor ts

 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 Explorer

It 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 DHTMLForm
DHTMLForm defines several new variables and overrides two methods.

Chapter 11, Writing custom browser code 215

 Working with DHTMLForm variables
DHTMLForm 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 methods

DHTMLForm overrides the CustomDHTMLHeader( ) and
CustomDHTMLFooter( ) methods as shown in the following illustrations.
These methods generate a <FORM> element.

216 Programming e.Repor ts

Subclassing DHTMLForm
When 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.

Property Value
FormAction http://radium:8700/acweb/
executereport.do?__requesttype=immediate&__
executableName=%2fSales%20Conferences%2f
SummaryTimeSeries%2erox
FormMethod POST
FormName FormBasedForm

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.

Chapter 11, Writing custom browser code 217

 Working with DHTMLMenuControl
DHTMLMenuControl defines several new variables and overrides several
methods.

Working with DHTMLMenuControl variables

DHTMLMenuControl 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 methods

DHTMLMenuControl overrides the methods shown in the following
illustration.

218 Programming e.Repor ts

Using BuildFromRow( )
Override the BuildFromRow( ) method as shown in the following example:
Function BuildFromRow( row As AcDataRow ) as AcBuildStatus
BuildFromRow = Super::BuildFromRow( row )
'Insert your code here
BuildFromRow = 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 String
Dim TAB as String
Dim i as Integer

Dim text as String

Dim value as String

NL = Chr$(10)
TAB = Chr$(9)
i = 0

text = row.GetValue(OptionText)
value = row.GetValue(OptionValue)

Chapter 11, Writing custom browser code 219

 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 here
FinalMenuCode = "<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 here
BrowserCode = FinalMenuCode
End Function

Subclassing DHTMLMenuControl
By 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.

220 Programming e.Repor ts

Displaying custom browser code in the Viewer
You 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:

Chapter 11, Writing custom browser code 221

 Displaying custom browser code output in a web browser
The 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 Netscape

To 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

222 Programming e.Repor ts

■ 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.

Chapter 11, Writing custom browser code 223

224 Programming e.Repor ts
 Chapter

Designing a report for

Chapter12

XML data
This chapter contains the following topics:
■ About the XML data format
■ About the View process
■ Publishing an Actuate report as XML

Chapter 12, Designing a repor t for XML data 225

About the XML data format
Extensible 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 Definitions

An 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.

226 Programming e.Repor ts

Examining a simple XML document
The 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.

Chapter 12, Designing a repor t for XML data 227

About the View process
The 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.

228 Programming e.Repor ts

 View process

Chart & MS IE IE
ROX image DHTML browser
cache cache
Converter
XML
frameworks

Page Netscape Netscape

viewing DHTML browser

Search
Basic Page
engine security Acrobat
TOC Reader
PDF

XML
data

Custom
Report documents applications

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 XML

This 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.

Chapter 12, Designing a repor t for XML data 229

 Mapping XML to Actuate report sections
The 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 properties

All 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.

230 Programming e.Repor ts

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 properties

The 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.

Chapter 12, Designing a repor t for XML data 231

 Property Description
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.

About AcReportComponent XML properties

The following table describes the XML properties for AcReportComponent.

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.

About AFC XML functions

The following table describes the AFC functions that control generation of
XML from an Actuate report.

232 Programming e.Repor ts

AFC Class Function Description
AcReport Function Returns the value for an element or
Component GetXMLText( ) attribute. The default value for a
As String 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.
AcReport Sub Generate Generates the XML for a custom
Component XML(visitor As component. Actuate calls this
AcXMLData method if the component’s
Visitor) XMLType is XMLCustom. Override
this method to produce custom
XML. By default, this function does
nothing.
AcReport Function Generates an XML file for the report.
GenerateXML
DataFile
(fileName As
String)
As Boolean
AcReport Sub Generates the prolog portion of the
XMLDataProlog XML report then writes the prolog to
(channel As a channel. Override
Integer) 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 Generates XML data for a report.
GenerateXMLData
(filename As
String)

Chapter 12, Designing a repor t for XML data 233

 The following report, the Design Emporium product catalog, illustrates how to
map a report component to an XML element.
<CATALOG> contains the <ADDRESS TYPE=MAILING>
entire report contains the company address

<PRODUCT <PART> <DESCRIPTION> <PRICE>

CATEGORY=value> specifies the contains the item’s contains the
specifies the general part number description item’s list price
product group

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.

234 Programming e.Repor ts

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:

Chapter 12, Designing a repor t for XML data 235

 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>

236 Programming e.Repor ts

 Chapter

Understanding report
Chapter 13

bursting techniques
This chapter contains the following topics:
■ About report bursting
■ Understanding report bursting techniques
■ Understanding report bursting tasks
■ Examining report bursting examples

Chapter 13, Understanding repor t bursting techniques 237

About report bursting
Report 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 techniques

The 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.

238 Programming e.Repor ts

Understanding report bursting tasks
To 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.

Chapter 13, Understanding repor t bursting techniques 239

Examining report bursting examples
The 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 example

Burst1.rod uses subreport bursting. With subreport bursting, you place each
subreport in a different report object instance (.roi) file.

240 Programming e.Repor ts

 Master report

Summary entry
Detail report

Detail query

Reference to
master report’s
PageList
component

Examining the report structure for a subreport bursting

example
Burst1.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 example
The detail report’s PageList component is a reference to the master report’s
PageList component.

Chapter 13, Understanding repor t bursting techniques 241

 Examining the detail query for a subreport bursting
example
The 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 example
The 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 AcBuildStatus
If Not row Is Nothing Then
CustomerQuery::StateParam = row.GetValue( “state” )
End If
BuildFromRow = Super::BuildFromRow( row )
EndFunction

242 Programming e.Repor ts

Examining the SuggestRoiName( ) method for a subreport
bursting example
The 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 String
SuggestRoiName = “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 String
SuggestRoiName = row.GetValue( "state" ) & "/" &
row.GetValue( "county" ) & ".roi"
End Function

Examining the summary entry’s LinkExp property for a

subreport bursting example
The 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.

Chapter 13, Understanding repor t bursting techniques 243

 Examining a group bursting example
Burst2.rod uses group bursting. With group bursting, you burst the report on
group boundaries and place each group in a different ROI file.

Master report

Group section

Summary entry

Detail report
Group section

Reference to
master report’s
PageList
component

Examining the report structure for a group bursting

example
Burst2.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].

244 Programming e.Repor ts

Examining the detail report’s PageList component for a
group bursting example
The detail report’s PageList component is a reference to the master report’s
PageList component.

Examining the SuggestRoiName( ) method for a group

bursting example
The 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 String
SuggestRoiName = “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 String
SuggestRoiName = row.GetValue( "state" ) & "/" &
row.GetValue( "county" ) & ".roi"
End Function

Examining the summary entry’s LinkExp property for a

group bursting example
The 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.

Chapter 13, Understanding repor t bursting techniques 245

246 Programming e.Repor ts
 Part

Programming
Part 3

with Actuate Basic

Par t 3, Pro gra mmi ng w ith Actu ate Basic 247

248 Programming e.Repor ts
 Chapter

Introducing Actuate
Chapter 14

Basic
This chapter contains the following topics:
■ About Actuate Basic
■ Programming with Actuate Basic
■ Understanding code elements
■ Adhering to coding conventions
■ Using the code examples

Chapter 14, Introducing Actuate Basic 249

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 Chapter 15,
type errors at compile “Understanding
time instead of at run variables and data
time. types”
User-defined data types Combining variables of Chapter 15,
different types into a “Understanding
single type. variables and data
types”
OLE automation Exchanging Chapter 18,
support information with other “Programming an
applications that object from another
support OLE application”
automation.

250 Programming e.Repor ts

 Feature Supports ... For information, see
Calls to external Using functions stored Chapter 19, “Calling an
functions in external libraries. For external function”
example, you can create
and access a Java object,
call a C function, and
convert an Actuate
Basic string to a Java
String.
Portability Running a report on an Actuate Basic Language
NT, Windows, or UNIX Reference
server.

Programming with Actuate Basic

Actuate 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.”

Chapter 14, Introducing Actuate Basic 251

Understanding code elements
To 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 statements
A 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.
Procedure
Sub SetLabelBackgroundColor( anyControl As AcLabelControl )
Dim Label As MyLabel
If GetClassName(anyControl) = "MyLabel" Then
Set Label = anyControl Statements
Label.BackgroundColor = Red
End If
End Sub

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 ^ 2
StartTime = StopTime - Now
Net_Worth = Assets - Liabilities
Label.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.

252 Programming e.Repor ts

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 expressions
An 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 operators
An 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

Chapter 14, Introducing Actuate Basic 253

 Using an arithmetic operator
Use 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.

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

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 operator

Use 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.

254 Programming e.Repor ts

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 objectref1 Is objectRef2
comparison

Working with logical operators

Use logical operators to compare two logical expressions and return true or
false. The following table lists logical operators Actuate Basic supports.

Operator Description Syntax

Not Performs a logical negation on an Not expression
expression. Returns false if
expression is true.
And Performs a logical conjunction expression1 And expression2
on two expressions. Returns true
if both expressions are true.
Returns false if either expression
is false.
Or Performs a logical disjunction on expression1 Or expression2
two expressions. Returns true if
one or both expressions are true.
Xor Performs a logical exclusion on expression1 Xor expression2
two expressions. Returns true if
one but not both of the
expressions is true.
Eqv Performs a logical equivalence expression1 Eqv expression2
on two expressions. Returns true
if both expressions evaluate to
the same logical value.
Imp Performs a logical implication on expression1 Imp expression2
two expressions.

Chapter 14, Introducing Actuate Basic 255

 Using the concatenation operator
The 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 precedence

When 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 conventions

You 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 code
Code 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.

256 Programming e.Repor ts

 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 statement

Most 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 line

Sometimes 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 code
Indenting 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 convention

A 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( ).

Chapter 14, Introducing Actuate Basic 257

 About naming rules
When 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 examples

Actuate 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.

258 Programming e.Repor ts

 Chapter

Understanding variables
Chapter15

and 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

Chapter 15, Understanding variables and data types 259

About variables
When 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 variable
Declare a variable using the Dim, Global, or Static statements, as shown in the
following examples:
Dim Total As Integer
Global FileName As String
Static 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.

Declared with Declared in Scope

Global Declarations section of an Global
Actuate Basic source (.bas) file
included with a report design
Dim or Static A procedure or method Local
Dim or Static A class Class

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 variables

A 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.

260 Programming e.Repor ts

The following figure shows an example of an Actuate Basic source (.bas) file
with global variables defined in a declaration section.

Declare
Global XVar As Integer
Global YVar As String
End Declare

Basic source (.bas) file

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.

Chapter 15, Understanding variables and data types 261

 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 variable

A 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 Integer
Static 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:

262 Programming e.Repor ts

 Function CumulativeTotal(ByVal Num As Double) As Double
Static Accumulate As Double
Accumulate = Accumulate + Num
CumulativeTotal = 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 variables

A 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 array
An 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-50
Dim 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.

Chapter 15, Understanding variables and data types 263

 About multi-dimensional arrays
You 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 arrays

Sometimes, 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 array

To 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 types

Actuate 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.

264 Programming e.Repor ts

Using standard data types
Actuate Basic defines standard Visual Basic data types. The following table
lists the names and characteristics of these standard data types.

Data type Storage size Range

Integer 4 bytes -2,147,483,648 to 2,147,483,647
32 bits
Long 4 bytes -2,147,483,648 to 2,147,483,647
32 bits
Single 8 bytes ±2.2250738585072014E-308 to
64 bits ±1.7976931348623158E+308
Double 8 bytes ±2.2250738585072014E-308 to
64 bits ±1.7976931348623158E+308
Currency 12 bytes -39,614,081,257,132,168,796.771975168
96 bits to
39,614,081,257,132,168,796.771975167
Date 8 bytes Dates 1 January 100 to 31 December
64 bits 9999
Times 0:00:00 to 23:59:59
CPointer 4 bytes Same as for Unsigned Long
32 bits
String 1 byte per 0 to approximately 2,147,483,647
character characters or memory limit
Variant As needed Depends on value stored, up to the
range of a Double
User-defined Defined by Range of each element depends on its
(defined with Type) elements fundamental type

Using an AFC data type

An 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.

Chapter 15, Understanding variables and data types 265

 ■ 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:
AcFont
AcSize
For a list of the AFC data types, see Chapter 2, “AFC data types,” in Actuate
Foundation Class Reference.

Assigning a data type

A 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 keyword

To 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 Currency
Dim 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 character

You 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 &

266 Programming e.Repor ts

 Data type Type declaration character
Single (real) !
Double (real) #
Currency @
String $

The following examples show valid variable declarations:

Dim OurAccount@ ' declare Currency variable
Dim CustomerName$ ' declare String variable
Dim QuantitySold% ' declare Integer variable

About constants
For 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.14159265358979
Const 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 data

A 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

Chapter 15, Understanding variables and data types 267

 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 data

A 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 string
You 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.

268 Programming e.Repor ts

Using binary string data
Traditionally 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 string
You 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.

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.

4 Assign the contents of the manipulated binary string back to a byte array.

Chapter 15, Understanding variables and data types 269

 For information about working with a multibyte character string, see Working
with Multiple Locales.

Formatting strings
The 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 strings
The 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.

270 Programming e.Repor ts

The following table shows the return values of a string comparison.

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

Changing capitalization
The following table lists four functions to change the capitalization of a string.

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

Removing spaces
The following table lists the functions to remove leading or trailing spaces
from a string.

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

Chapter 15, Understanding variables and data types 271

 Embedding a quote in a string
Actuate 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 data

Actuate 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 numbers
The 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 currency
The 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

272 Programming e.Repor ts

 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 Currency
DollarAmt= 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 types

If 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 data

Date 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#

Chapter 15, Understanding variables and data types 273

 Using Date display formats
A 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 time

You 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.

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.

You can use date and time literals by enclosing them within number signs (#).
For example:
If Today > #2/25/2003# Then ...

274 Programming e.Repor ts

 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 type

Actuate 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 alias
An 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 structure
You 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.

Chapter 15, Understanding variables and data types 275

 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 SysInfo
ComputerName As String
CPU As String
Memory As Long
DiskDriveType As String
DiskDriveSize As Single
Price As Currency
PurchaseDate 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.95
SystemOne.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 class
A 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 type

A CPointer data type variable holds a pointer to data allocated in a C function
you create.

276 Programming e.Repor ts

Converting a data type
Actuate 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

Chapter 15, Understanding variables and data types 277

278 Programming e.Repor ts
 Chapter

Writing and using a

Chapter 16

procedure
This chapter contains the following topics:
■ About procedures
■ Declaring a procedure
■ Declaring an argument
■ Calling a procedure
■ Overloading a procedure
■ Using a control structure

Chapter 16, Writing and using a procedure 279

About procedures
A 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 procedures

In 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 methods
A 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.”

280 Programming e.Repor ts

Creating a global procedure
A 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 Sub
Function 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.

Chapter 16, Writing and using a procedure 281

 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 procedure
Actuate 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 procedure

The 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 procedure

Actuate 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:

282 Programming e.Repor ts

 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 Single
RectArea = Width * Length
End Function

Declaring an argument
An 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 Integer
Sum = Num1 + Num2
End Function

Function ExtendedCost (Cost As Currency, Quantity As Integer) As Currency

ExtendedCost = Cost * Quantity
End Function

Chapter 16, Writing and using a procedure 283

 About argument data types
A 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 reference

Actuate 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 value

The 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 procedure
The 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 procedure

A 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.

284 Programming e.Repor ts

 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 procedure

Because 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 UpdateTotal
NewTotal = UpdateTotal
If 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 structure

A 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.

Chapter 16, Writing and using a procedure 285

 Using If...Then
Use 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 Then
myDate = Now
Timer.Enabled = True 'Start the timer
End If

Using If...Then...Else
Use 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...Loop
Use 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

286 Programming e.Repor ts

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...Next
If 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 structure

You 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 structure

Using 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 procedure

Using 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.

Chapter 16, Writing and using a procedure 287

288 Programming e.Repor ts
 Part

Programming in the
Part 4

Windows environment

Par t 4 , Programming in the Wi ndows enviro nmen t 289

290 Programming e.Repor ts
 Chapter

Using an object from

Chapter 17

another 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

Chapter 17, Using an object from another application 291

Adding an object from another application
When 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 embedding

OLE 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.

292 Programming e.Repor ts

About supported OLE objects
When 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.

Supported
OLE objects

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.

Chapter 17, Using an object from another application 293

 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 embedding

You 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 object

When 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.

294 Programming e.Repor ts

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.

Linked object
Paintbrush image

Actuate e.Report Designer Professional - [SalesRpt]

Actuate report

Word document

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 object

When 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.

Chapter 17, Using an object from another application 295

 Guidelines for linking and embedding
Use the following guidelines when deciding whether to link or embed an OLE
object in your report.

When to link When to embed

You want the capability to modify You want the capability to modify
the original object file and have those the object and have those changes
changes reflected in all applications reflected only in the report
that have a link to that object. application.
The original object file is likely to be The original object file is unlikely to
modified frequently, or modified be modified, or modified from the
from multiple OLE container report only.
applications.
The original object file will not be The original object file might be
moved or deleted. Links break when moved or deleted.
files move to different locations.
You are unlikely to distribute the You want to distribute the report
report application. application without worrying about
distributing the object files that your
report maintains links to.

Linking and embedding an OLE object

There 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.

296 Programming e.Repor ts

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.

Chapter 17, Using an object from another application 297

 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.

298 Programming e.Repor ts

 3 Choose OK.
The OLE server application appears.
3 Create the contents of the OLE object.

Editing an OLE object

After 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

Chapter 17, Using an object from another application 299

 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 control

The 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.

300 Programming e.Repor ts

 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 component

You 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.

Chapter 17, Using an object from another application 301

Subclassing an OLE component
Like 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.

OLEComponent1 displays
Paintbrush image

OLEComponent2, a subclass of
OLEComponent1, references
Paintbrush image in its superclass

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.

302 Programming e.Repor ts

 Chapter

Programming an object
Chapter 18

from 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

Chapter 18, Programming an object from another application 303

About programming other applications’ objects
The 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 Automation

OLE 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 object
Unlike 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 supports
Because 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.

304 Programming e.Repor ts

Creating an OLE Automation object
Use 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 object

Work 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 bold
excelHandle.Row(1).Font.Bold = True

' Put the value 100 in the first cell

excelHandle.Cells( 1,1 ).Value = 100

' Save the worksheet and close Excel

excelHandle.SaveAs( "MySheet.xls" )
Set excelHandle = Nothing

Chapter 18, Programming an object from another application 305

 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 variables

Dim excelHandle As Object
Dim workbookHandle As Object
Dim cellHandle As Object

Dim orderSection As AcLevelBreakSection

Dim customerSection As AcLevelBreakSection
Dim sectionChild As AcFrame
Dim theItemFrame As ::ItemFrame
Dim customerTitle As ::CustomerTitleFrame
Dim creditRating As String
Dim purchasePattern As String
Dim curSheetRow As Integer

' Create the OLE Automation object and open the appropriate file
Set excelHandle = CreateObject( "Excel.Application" )
Set workbookHandle = excelHandle.WorkBooks
workbookHandle.Open( "\Actuate\demo\discount.xls" )
excelHandle.Visible = True

306 Programming e.Repor ts

 ' Assign values to the variables
Set orderSection = p_Container.p_Containter
Set customerSection = orderSection.p_Container
Set customerTitle = customerSection.GetFirstContent

creditRating = customerTitle.creditRating.DataValue
purchasePattern = customerTitle.purchasePattern.DataValue

' Specify the cells in which to display data

Set cellHandle = excelHandle.Cells( 2, 5 )
cellHandle.Value = DataValue
Set cellHandle = excelHandle.Cells( 2, 6 )
cellHandle.Value = creditRating
Set cellHandle = excelHandle.Cells( 2, 7 )
cellHandle.Value = purchasePattern

Set sectionChild = orderSection.GetFirstContent

curSheetRow = 10

' Loop through all the order items and enter the values into the cells
Do Until sectionChild is Nothing
If IsKindOf( sectionChild, "ItemFrame" ) Then
Set the ItemFrame = excelHandle.Cells(1, curSheetRow)
Set cellHandle = excelHandle.Cells(1, curSheetRow)
cellHandle.Value = theItemFrame.itemCode.DataValue
Set cellHandle = excelHandle.Cells(2, curSheetRow)
cellHandle.Value = theItemFrame.quantity.DataValue
Set cellHandle = excelHandle.Cells (3, curSheetRow)
cellHandle.Value = theItemFrame.priceQuote.DataValue

curSheetRow = curSheetRow + 1
End If
Set sectionChild = orderSection.GetSuccessor( sectionChild )
Loop
End Sub

Chapter 18, Programming an object from another application 307

 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

308 Programming e.Repor ts

 Chapter

Calling an external
Chapter 19

function
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

Chapter 19, Calling an external function 309

Calling an external C function
This 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 Basic

Because 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.

310 Programming e.Repor ts

Declaring a C function
To 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 procedure

If 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 procedure

If 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 issues

To 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.

Chapter 19, Calling an external function 311

 ■ 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 function

On 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 reference

By 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 types

Some 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:

312 Programming e.Repor ts

 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 name

Occasionally, 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 type

To 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
1
AcCurrency *x x As Currency
AcCurrency x ByVal x As Currency
2
RWCString *x, RWCString &x x As String
char *x, LPCSTR x (null terminated ByVal x As String
string)

Chapter 19, Calling an external function 313

 C type Actuate Basic type
union { int, long, double, x As Variant, x As Any
AcCurrency, RWCString } *x
actual data (int, long, double, ByVal x As Variant, ByVal As Any
AcCurrency, char*)
void**x (pointer to any C/C++ x As CPointer
pointer)
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.

Calling a C function
Call 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.

314 Programming e.Repor ts

Calling a C function with a specific data type
Actuate 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 function

Procedures 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 function

You 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 function

In 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 CPointer
Func1(ptr) ' pass CPointer ptr to the C function
Func1(Null) ' pass null pointer to the C function

Declare Sub Func2 Lib "LIBXYZ" (ByVal s As String)

Dim s As String
s = "text"
Func2(s) ' pass null-termintated string to the C function
Func2(Null) ' pass null pointer to the C function

Chapter 19, Calling an external function 315

 Passing a user-defined data type to a C function
You cannot pass a user-defined data type to a C function.

Passing an object reference variable to a C function

You 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 functions

The following table shows how return values convert to Actuate Basic data
types.

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

Working with a Java object

Actuate 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 requirements

You 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.

316 Programming e.Repor ts

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 object

Before 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

object
You 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.

Chapter 19, Calling an external function 317

 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

field
You can invoke a static method and access a static field without instantiating
an object of the class. For example:
Dim theClassObject As Object
Set 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 type

The 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

318 Programming e.Repor ts

Java data type Actuate Basic type
Object Object
short Integer
void No type

Converting a Java String

Actuate 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 null

Actuate 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 array
Actuate 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:

Chapter 19, Calling an external function 319

 Dim basicIntArr( 10 ) As Integer
Dim javaIntArr As Object
Set 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 handling

In 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.

Error name Integer Value Meaning

E_JVMCLASSPATHNOT 97 Could not get
FOUND environment variable
CLASSPATH
E_JVMCREATEJVMFAILED 98 Failed to create Java
Virtual Machine
E_JVMCLASSNOTFOUND 99 Could not find the Java
class
E_JVMCREATEOBJECT 100 Failed to create Java
FAILED object
E_JVMINVALIDJAVA 101 Invalid Java object or
HANDLE class handle
E_JVMMETHODFIELD 102 Failed to access a method
ACCESSFAILED or a field
E_JVMTYPECONVERSION 103 Type conversion failed
FAILED
E_JAVAEXCEPTION 104 Java exception occurred
OCCURRED

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 Object
On Error Goto HandleError
Set javaObj = CreateJavaObject( "JavaClassName" )
javaObj.TryToDoSomething( ) ' assume this causes a Java Exception

320 Programming e.Repor ts

 ' Put code here to handle normal behavior without exception then exit the
method

HandleError:

Dim errorCode As Integer

errorCode = Err

If errorCode = E_JAVAEXCEPTIONOCCURRED Then

' Next statement has the same result as above statement
' If errorCode = 104 Then
Dim exceptionObj As Object
Set exceptionObj = GetJavaException( )
If exceptionObj.toString( ) = "SomeJavaExceptionType" Then
' Do something or resume execution
End If
End If

Debugging a Java object

The 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.

Chapter 19, Calling an external function 321

322 Programming e.Repor ts
 Part

Programming with
Part 5

Actuate’s C++ APIs

Par t 5 , P r ogram m ing w it h A c tu at e’s C++ AP I s 323

324 Programming e.Repor ts
 Chapter

Using Actuate’s Chapter 20

application programming
interfaces
This chapter contains the following topics:
■ About the programming interfaces
■ A comparison of API features
■ Choosing the appropriate API

Cha pt er 20 , U si ng A c tu at e’s app lic at io n pr ogram m ing i nt er fac es 325

About the programming interfaces
This 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 API

The 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 API

The 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:

326 Programming e.Repor ts

■ 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 API

The 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 controls

ActiveX 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.

Cha pt er 20 , U si ng A c tu at e’s app lic at io n pr ogram m ing i nt er fac es 327

 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 features

The following table lists the functional capabilities each Actuate interface
provides.

Report Search
Task server Requester 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 Yes
application
Modify Yes
parameters
Schedule Yes
execution and
printing reports
Distribute results Yes Yes
Security features Yes

328 Programming e.Repor ts

 Report Search
Task server Requester extension ActiveX
Encyclopedia Yes
management
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.

Choosing the appropriate API

This 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 environment
The Requester and Report Server APIs operate on Windows and UNIX
systems. ActiveX and search extension are Windows-specific interfaces.
■ Feature set
All 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 cycle
High-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 interface
Actuate ActiveX controls are the easiest tools to use to create Windows-
based GUI applications to view and generate Actuate reports.
■ Client/server or local model
The 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.

Cha pt er 20 , U si ng A c tu at e’s app lic at io n pr ogram m ing i nt er fac es 329

 When to use the Report Server API
Use 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 API

Use 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 API

Use 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 controls

Use the Actuate ActiveX controls to embed Actuate reporting into a Windows
application. The Actuate ActiveX controls are the easiest to implement.

330 Programming e.Repor ts

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.

Cha pt er 20 , U si ng A c tu at e’s app lic at io n pr ogram m ing i nt er fac es 331

332 Programming e.Repor ts
 Chapter

Requester API user guide

Chapter 21

This 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

Chapter 21, Requester API user guide 333

About the Requester API
The 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 API

The 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.

334 Programming e.Repor ts

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 environment

The 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.
Client LAN Server

Custom
application Actuate
iServer

Viewer Requester
API
Encyclopedia
volume

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>]

Chapter 21, Requester API user guide 335

 ■ 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 locally
Local 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 API

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 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.

336 Programming e.Repor ts

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

environment
Requester 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 application

You identify an API to your application according to the programming
language you plan to use:
■ Actuate Basic
Call the Requester API functions as you would any other Actuate Basic
function.
■ Visual Basic
Declare 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 tools

The 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

Chapter 21, Requester API user guide 337

 Technology. You can obtain other supported development tools, including
Solaris, HP-UX, and AIX C++ compilers, from their manufacturers.

Platform Supported tools

Windows NT and 2000 Actuate Basic
Visual Basic 6.0
Visual C++ 6.0
Rogue Wave SourcePro Core 8.0
Solaris Actuate Basic
Sun C++ 5.0
Sun Forte 6 (C++ 5.1)
Sun Forte 6 Update 1 (C++ 5.2)
Sun Forte 6 Update 2 (C++ 5.3)

HP-UX Actuate Basic

HP aC++ A.03.27 on HP-UX 11.x

IBM AIX Actuate Basic

IBM VisualAge C++ 5.0

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 files

The 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.

338 Programming e.Repor ts

Understanding API file name conventions
The following table summarizes the naming conventions for files the
Requester API uses.

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

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 environment

For the Requester API, refer to the following table for the correct DLL. All file
names in the table have the .dll file extension.

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 acrq5060
Service Pack 1 Patch 1
4.0 to 4.1 acrq4060

Chapter 21, Requester API user guide 339

 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.

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 acrs5060
Service Pack 1
Patch 1
4.0 to 4.1 acrs4060

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 variables

When linking your UNIX application, set the library path to the shared library
for your specific UNIX system.

Operating system Shared library Path variable

SunOS libreqstapi.so LD_LIBRARY_PATH
HP-UX libreqstapi.sl SHLIB_PATH
AIX libreqstapi_share.a LIBPATH

Make sure the environment variable AC_SERVER_HOME is set to the Server

Integration Technology installation directory.

About the Requester API operating environment

A 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

340 Programming e.Repor ts

 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 Viewer

You 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:

Platform Copy DLL to:

Windows NT and System32 directory
Windows 2000
Windows 95/98 System directory

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 tasks

This 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

Chapter 21, Requester API user guide 341

 For a complete description of each function, see Chapter 22, “Requester API
reference.”

Writing startup and cleanup code

The 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.

Programming task API function

Select the client product to use for client-side AcReqSelectClient
viewing, printing, and running reports.
Specify the End User Desktop application to use AcReqSetEUDTPath
to generate a report (.roi). AcWReqSetEUDTPath
Initialize the API. This step is required before the AcReqInitialize
program can call any of the other API functions.
Connect to the server if the program accesses files AcReqConnect
on a server. AcWReqConnect
Disconnect from the server after the program has AcReqDisconnect
finished executing tasks on the server.
Close the library and free resources used by the AcReqUnInitialize
API.

Working with report files

When 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.

342 Programming e.Repor ts

■ 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 API

When 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 API

The 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.

Chapter 21, Requester API user guide 343

 <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.

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

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.

Programming task API function

Open an .rov or .rox file to access AcReqReadFile
information about the parameters. AcWReqReadFile
Get the version number of a generated AcReqGetReportVersion
report.
Create a new .rov file to store parameter AcReqWriteFile
values you set. AcWReqWriteFile
Close an open .rov or .rox file. AcReqCloseFile

Getting the parameter and parameter group

names
At 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.

344 Programming e.Repor ts

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.

Programming task API function

Get the name of the first parameter AcReqGetFirstGroup
group. AcWReqGetFirstGroup
Get the name of the next parameter AcReqGetNextGroup
group. AcWReqGetNextGroup
Get the name of the first parameter. AcReqGetFirstParameter
AcWReqGetFirstParameter
Get the name of the next parameter. AcReqGetNextParameter
AcWReqGetNextParameter
Specify how parameter names are AcReqSetScopedParameterName
retrieved.

Getting the parameter attributes

At 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 a parameter’s alias name. The alias AcReqGetAlias
name appears as a prompt in the AcWReqGetAlias
Requester dialog.
Determine if a parameter is required or AcReqGetRequired
optional. AcWReqGetRequired
Determine if a parameter can only be set AcReqGetHidden
programmatically. AcWReqGetHidden
Determine whether a parameter was AcReqGetHideText
defined to display asterisks or actual AcWReqGetHideText
text as users type the value in the
Requester.
Determine if a parameter is an ad hoc AcReqGetAdhoc
parameter. AcWReqGetAdhoc

Chapter 21, Requester API user guide 345

 Programming task API function
Get the data type of a parameter as a AcReqGetParmType
string. AcWReqGetParmType
Get the data type of a parameter as an AcReqGetType
enumeration. AcWReqGetType

Getting the default parameter values

At 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.

Programming task API function

Get the default value of a parameter of AcReqGetDefaultValueStr
any type as a string. AcWReqGetDefaultValueStr
Get the default value of a parameter of AcReqGetDefaultValueCurrency
type currency as a currency. AcWReqGetDefaultValueCurrency
Get the default value of a parameter of AcReqGetDefaultValueDate
type date as a date. AcWReqGetDefaultValueDate
Get the default value of a parameter of AcReqGetDefaultValueDouble
type double as a double. AcWReqGetDefaultValueDouble
Get the default value of a parameter of AcReqGetDefaultValueInteger
type integer as an integer.
Get the default value of a parameter of AcReqGetDefaultValueString
type string as a string. AcWReqGetDefaultValueString
Determine if a parameter has a default AcReqHasDefaultValue
value assigned. AcWReqHasDefaultValue

Getting the current parameter values

The 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.

346 Programming e.Repor ts

Programming task API function
Get the current value of a parameter of AcReqGetValueCurrency
type currency as a currency. AcWReqGetValueCurrency
Get the current value of a parameter of AcReqGetValueDate
type date as a date. AcWReqGetValueDate
Get the current value of a parameter of AcReqGetValueDouble
type double as a double. AcWReqGetValueDouble
Get the current value of a parameter of AcReqGetValueInteger
type integer as an integer. AcWReqGetValueInteger
Get the current value of a parameter of AcReqGetValueStr
type string as a string. AcWReqGetValueStr
Get the current value of a parameter of AcReqGetValueString
type string as a string. Use AcWReqGetValueString
AcReqGetValueString instead of
AcReqGetValueStr if you need to pass
an argument.

Setting parameter values

The 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

Set the value of a parameter of type AcReqSetValueCurrency
currency. AcWReqSetValueCurrency
Set the value of a parameter of type AcReqSetValueDate
date. AcWReqSetValueDate
Set the value of a parameter of type AcReqSetValueDouble
double. AcWReqSetValueDouble
Set the value of a parameter of type AcReqSetValueInteger
integer. AcWReqSetValueInteger
Set the value of a parameter of type AcReqSetValueString
string. AcWReqSetValueString

Chapter 21, Requester API user guide 347

 Configuring a printer
If 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.

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 AcReqSetPrinterOrientation
or Landscape.
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, AcReqSetPrinterFormName
Legal, and so on) or physical size.2 AcWReqSetPrinterFormName
Specify the paper size with specific AcReqSetPrinterPaperSize
dimensions.
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.

Running, viewing, and printing reports

The following table list the methods you use to run, view, and print reports.

Programming task API function

Specify the priority for reports AcReqSetRequestPriority
generated on iServer.
Generate a report (.roi) based on an AcReqGenerateReport
existing .rov file or an .rov file you AcWReqGenerateReport
created with new parameter values.
Print a report. AcReqPrintReport
AcWReqPrintReport
Display a report. AcReqViewReport
AcWReqViewReport

348 Programming e.Repor ts

You must call AcReqSelectClient or AcReqSetEUDTPath before printing,
viewing, or running a report locally.

Running a report locally

When 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 report
AcReqSetValueString( 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 file
AcReqWriteFile( fileNum, "Myreport.rov" )

'Generate a report based on the .rov file you created

AcReqGenerateReport( "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 errors

The 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

Chapter 21, Requester API user guide 349

 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 checking

You use the return value directly to check on any errors the following
functions encounter:
AcReqConnect
AcReqDisconnect
AcReqInitialize
AcReqReportStatus
AcReqUninitialize
AcWReqConnect

Functions that do not support error checking

You cannot check on any errors the following functions encounter:
AcReqSetDefaultPrinter
AcReqSetEUDTPath
AcReqSetPrinterCollate
AcReqSetPrinterColor
AcReqSetPrinterDuplex
AcReqSetPrinterFormName
AcReqSetPrinterName
AcReqSetPrinterNumberCopies
AcReqSetPrinterOrientation
AcReqSetPrinterPaperSize
AcReqSetPrinterScale
AcReqSetPrinterTray
AcReqSetRequestPriority
AcWReqSetEUDTPath
AcWReqSetPrinterFormName
AcWReqSetPrinterName

Writing a Requester API application

All 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:

350 Programming e.Repor ts

■ 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 iServer

You 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 session

The 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 session
sessionHandle = AcReqInitialize();
}

Connecting to iServer
The 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

Chapter 21, Requester API user guide 351

 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 Server
connectionHandle = 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 parameters
You 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 name
AcReqSetValueString( 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 paramater
AcReqSetValueString( fileNum, "customers_creditrank", "C");
}

352 Programming e.Repor ts

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 report

You 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 Report
long 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 report

To 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 report
AcReqSetPrinterName( "HP LaserJet IIP”);
requestHandle = AcReqPrintReport( "rotp://Kilauea/Western/Detail.roi",0);
}

Closing the API session

The 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:

Chapter 21, Requester API user guide 353

 void CReqReportDlg::OnClose()
{
AcReqCloseFile( fileNum );
AcReqDisconnect(connectionHandle);
AcReqUnInitialize(sessionHandle);
}

Writing an application for local reports

You 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 method

Actuate 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 Long
Declare Function AcReqUnInitialize Lib "Acrq7060.dll" _
(ByVal sessionHandle As Long ) As Boolean
' Other declarations ...
Dim sessionNum As Integer

354 Programming e.Repor ts

Initializing an API session
Initialize 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_Load
sessionNum = AcReqInitialize
AcReqSetEUDTPath (RunViewExe)
End Sub

Specifying parameters
You 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 definitions
fileNum = AcReqReadFile("C:/Example/Detail.rox")
' Set parameter values
AcReqSetValueString fileNum, "RoiFileName", "C:/Example/Mydetail.roi"
AcReqSetValueString fileNum, "RoxFileName", "C:/Example/Detail.rox"
AcReqSetValueString fileNum, "customers_creditrank", "C"
' Write the parameter values to Mydetail.rov
AcReqWriteFile fileNum, "C:/Example/Mydetail.rov"
' Close the file
AcReqClosefile(fileNum)
End Sub

Chapter 21, Requester API user guide 355

 Generating a report
You 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 report
AcReqSetEUDTPath ("C:/Program Files/Actuate7/ErdPro/Bin/Runview.exe")
' Generate the report
ret = AcReqGenerateReport _
("C:/Example/Mydetail.rov", AC_REQ_GENERATE, 0)
End Sub

Viewing a report
To 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 report
To 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 session
Terminate the API session by calling AcReqUnInitialize:
Private Sub Form_UnLoad( Cancel As Integer )
AcReqUnInitialize( sessionNum )
End Sub

356 Programming e.Repor ts

 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 list
while (some_condition_is_true) {
# --- Submit new requests here
while (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 from
add 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 requestID

remove 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

Chapter 21, Requester API user guide 357

 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 Basic

One 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 Integer
Dim viewRpt As Integer ' Views report
Dim printRpt As Integer ' Prints Report
Dim stayopen As Integer ' Keeps the EUDT open
Dim async As Integer ' Runs asynchronously
Dim always As Integer ' Launches EUDT
Dim hide As Integer ' Hides EUDT
Dim opts As Long
Dim DetailRox as String
Dim SmallDetailRoi As String
Dim SmallDetailRov As String

358 Programming e.Repor ts

 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 = False
Exit Function
End If
AcReqCloseFile( fileNum)
' Set the options to view the small report
generateReport= True
viewRpt = True
printRpt)= False
stayopen= True
async = False
always = True
hide = False
opts = 0
If ( generateReport = 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
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

Chapter 21, Requester API user guide 359

 If ( always = True ) Then
opts = opts + AC_REQ_LAUNCH_ALWAYS
End If
If ( hide = True ) Then
opts = opts + AC_REQ_HIDE
End If
ret = AcReqGenerateReport(SmallDetailRov, opts, 0)
If ret > 0 Then
theErrorStr = AcReqGetErrorString(ret)
MsgBox theErrorStr
OnLButtonDown = False
Exit Function
End If

OnLButtonDown = True
End Function

Using the Requester API in Visual Basic

This 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 Basic

To 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 statement

If 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 statement
Declare Function AcReqReadFile Lib "Acrq7060.dll" (ByVal fileName As
String) As Long
' Invalid statement
Declare Function AcReqReadFile Lib "C:\Libraries\Acrq7060.dll" (ByVal
fileName As String) As Long

360 Programming e.Repor ts

Manipulating parameter values, generating and
printing a report
This 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.
When a user clicks one of these
buttons, the procedure executes:
GenerateReport_Click( )

PrintReport_Click( )

AllTypes_Click( )

FindParms_Click( )

GenerateServerReport_Click( )

ViewServerReport_Click( )

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"

Chapter 21, Requester API user guide 361

 Dim genReport As Boolean
Dim viewRpt As Boolean
Dim printRpt As Boolean
Dim stayopen As Boolean
Dim async As Boolean
Dim always As Boolean
Dim hideEUDT As Boolean
Dim sessionHandle As Long

Initializing the Requester API

Private Sub Form_Load()
sessionHandle = AcReqInitialize
AcReqSetEUDTPath (RunViewExe)
End Sub

Generating and viewing a report locally

Private 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

362 Programming e.Repor ts

 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 fileNum
End Sub

Printing the report locally

Private 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

Chapter 21, Requester API user guide 363

 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 fileNumber
End 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 <> "")

364 Programming e.Repor ts

 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

Chapter 21, Requester API user guide 365

 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 values
This 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.

366 Programming e.Repor ts

 Object name: form

Object name: valueField

Object name: btnClose

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 Long
Private Declare Function AcReqUnInitialize Lib "Acrq7060.dll" _
(ByVal sessionHandle As Long) As Long
Private Declare Function AcReqReadFile Lib "Acrq7060.dll" _
(ByVal fileName As String) As Long
Private 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 String
Private 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 variables

Dim fileName As String
Dim 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 definitions
fileNum = AcReqReadFile( fileName )

' Specify the parameter whose value to get

valueField.Text = AcReqGetValueString(fileNum, "orders_orderID")
End Sub

Chapter 21, Requester API user guide 367

 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
End
End Sub

Closing the Requester API

Private Sub Form_Unload(Cancel As Integer)
AcReqWriteFile fileNum, fileName
AcReqCloseFile fileNum
AcReqUnInitialize
End Sub

Using the Requester in a C++ application

This 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 environment

Unlike 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:

368 Programming e.Repor ts

 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.
When a user clicks one of these
buttons, the procedure executes:
OnGenerate( )
OnPrint( )
OnView( )
OnTypes( )

This example demonstrates using the following Requester methods.

Task Key classes & functions

Submit a request after setting three AcReqSetValueString
parameters. AcReqGenerateReport
AcReqSetEUDTPath
Print a report locally. AcReqSetPrinterName
AcReqPrintReport

Chapter 21, Requester API user guide 369

 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 Desktop
static 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 successful
fileNumber = AcReqReadFile( szDetailRox );
if ( AcReqGetError(fileNumber) )
AfxMessageBox ( (char*)AcReqGetErrorStr(fileNumber) );
// Set the output .roi name to myDetail.roi
AcReqSetValueString( fileNumber, szRoiFile, szMyDetailRoi );
// Set the parameter specifying the .rox file for report generation to
// detail.rox
AcReqSetValueString( fileNumber, szRoxFile, szDetailRox );
// Set the customers_creditrank input parameter to C
AcReqSetValueString( fileNumber, "customers_creditrank", "C" );
// Set a pointer to the End User Desktop
AcReqSetEUDTPath ( 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 report
BOOL viewRpt = TRUE; // Views report
BOOL print = FALSE; // Prints Report
BOOL stayopen = TRUE; // Keep the EUDT open

370 Programming e.Repor ts

 BOOL async = FALSE; // Runs asynchronously
BOOL always = TRUE; // Launches EUDT
BOOL hide = FALSE; // Hide EUDT
long 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 report
long requestHandle = AcReqGenerateReport(szDetailRox, opts,
fileNumber);
// Close the file
AcReqCloseFile( 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 Desktop
AcReqSetEUDTPath ( szEUDT );
// Set a pointer to the default printer
AcReqSetDefaultPrinter( );
// 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;

Chapter 21, Requester API user guide 371

 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 report
CurrentGroup = AcReqGetFirstGroup(fileNumber);
while (*(((char*)CurrentGroup)+1))
{
// Get the first parameter the parameter group contains
CurrentParameter = AcReqGetFirstParameter(fileNumber, (char*)
CurrentGroup);
while (*(((char*)CurrentParameter)+1))
{
// Find the alias the devleoper set for that parameter
Alias = ReqGetAlias(fileNumber, (char*) CurrentParameter);
// Find if the parameter is required
Required = AcReqGetRequired(fileNumber, (char*) CurrentParameter);
// Find if the parameter is marked as hidden
Hidden = AcReqGetHidden(fileNumber, (char*) CurrentParameter);
// Find if the parameter has been marked with HideText
HideText = AcReqGetHideText(fileNumber, (char*) CurrentParameter);
// Find if the parameter is ad hoc
Adhoc = AcReqGetAdhoc(fileNumber, (char*) CurrentParameter);
// Get the parameter type
ParmType = AcReqGetParmType(fileNumber, (char*) CurrentParameter);

// Free the BSTRs

SysFreeString(Alias);
SysFreeString(ParmType);
SysFreeString(CurrentParameter);
// Get the next parameter in the group.
CurrentParameter = AcReqGetNextParameter(fileNumber, (char*)
CurrentGroup);

}
// Free the BSTRs
SysFreeString(CurrentGroup);
// Get the next parameter group for the report
CurrentGroup = AcReqGetNextGroup(fileNumber);
}
// Close the file
AcReqCloseFile (fileNumber);
}

372 Programming e.Repor ts

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

Chapter 21, Requester API user guide 373

 oleDate = outDate;

// Set the currency parameter to the value of the inCurrency Variable

AcReqSetValueCurrency( fileNumber, "aCurrency", inCurrency.int64 );
// Set the date parameter to the value of the inDate variable
AcReqSetValueDate( fileNumber, "aDate", inDate );
// Set the double parameter to the value of the inDouble variable
AcReqSetValueDouble( fileNumber, "aDouble", inDouble );
// Set the integer parameter to the value of the inInteger variable
AcReqSetValueInteger( fileNumber, "aInteger", inInteger );
// Set the string parameter to the value of the inString variable
AcReqSetValueString( 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 errors
fileNumber = 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 Date
oleCurrency = outCurrency;
oleDate = outDate;

// Close the file

AcReqCloseFile( fileNumber );
}

374 Programming e.Repor ts

 Chapter

Requester API reference

Chapter22

This reference alphabetically lists the functions in the Requester API. For a
conceptual discussion of the Requester API, see Chapter 21, “Requester API
user guide.”

C ha pter 22, R equ es ter A P I re fe re nc e 375

AcReqCloseFile

AcReqCloseFile
Closes 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 fileNumber
The 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

AcReqConnect
Connects 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 server
The name of the iServer to which to connect.

username
The user name to use to log in to iServer.

password
The 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.

376 Programming e.Reports

 AcReqDisconnect

See also AcReqDisconnect

AcReqDisconnect
Disconnects from the specified server.
Syntax Basic: Sub AcReqDisconnect( connectionHandle As Long )
C/C++: VBBOOL AcReqDisconnect( long connectionHandle )
Parameter connectionHandle
The 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

AcReqGenerateReport
Generates 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 filename
The 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>]

C ha pter 22, R equ es ter A P I re fe re nc e 377

AcReqGenerateReport

options
A 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.

378 Programming e.Reports

 AcReqGenerateReport

Scope of options
The following table shows which options apply to reports generated locally or
on iServer and launched from either local or server applications.

Local report Server report Server report

Options Local launch Local launch Server launch
AC_REQ_LAUNCH_ALWAYS Yes Yes, if report No
viewing needed
AC_REQ_LOCAL Yes, if using Actuate No No
Basic
AC_REQ_VIEW Yes Yes No
AC_REQ_PRINT Yes Yes Yes
AC_REQ_ASYNC Yes Yes Yes
AC_REQ_HIDE Yes, if report Yes, if report No
viewing not needed viewing not needed
AC_REQ_RETURN_HANDLE Yes Yes Yes
AC_REQ_STAY_OPEN Yes Yes, if report No
viewing needed
AC_REQ_REPLACE No Yes Yes

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.

fileNumber
If 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 )

C ha pter 22, R equ es ter A P I re fe re nc e 379

AcReqGenerateReport

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.

380 Programming e.Reports

 AcReqGenerateReport

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.

Report
Return value generation mode Indication
0 Report generated Report executed successfully on a
asynchronously local client.
1 to 1023 Report generated Report execution failed.
asynchronously 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 Report executed successfully on
asynchronously 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 Report executed successfully on
synchronously iServer.
greater than 0 Report generated Report execution failed. To get an
synchronously 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.

See also AcReqGetError

AcReqGetErrorString
AcReqGetReportVersion
AcReqSetEUDTPath
AcReqSetRequestPriority
AcWReqGetErrorString

C ha pter 22, R equ es ter A P I re fe re nc e 381

AcReqGetAdhoc

AcReqGetAdhoc
Returns 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 fileNumber
The file number of the .rov or .rox file you opened with AcReqReadFile.

parmName
The 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 AcReqGetFirstParameter

AcReqGetNextParameter
AcReqSetScopedParameterName

AcReqGetAlias
Returns 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 fileNumber
The file number of the .rov or .rox file you opened with AcReqReadFile.

parmName
The 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.

382 Programming e.Reports

 AcReqGetDefaultValueCurrency

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 AcReqGetFirstParameter

AcReqGetNextParameter
AcReqSetScopedParameterName

AcReqGetDefaultValueCurrency
Returns 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 fileNumber
The file number of the .rov or .rox file you opened with AcReqReadFile.

parmName
The 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.

C ha pter 22, R equ es ter A P I re fe re nc e 383

AcReqGetDefaultValueDate

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 AcReqGetDefaultValueStr

AcReqGetFirstParameter
AcReqGetNextParameter
AcReqGetParmType
AcReqSetScopedParameterName

AcReqGetDefaultValueDate
Returns 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 fileNumber
The file number of the .rov or .rox file you opened with AcReqReadFile.

parmName
The 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.

384 Programming e.Reports

 AcReqGetDefaultValueDouble

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 AcReqGetDefaultValueStr

AcReqGetFirstParameter
AcReqGetNextParameter
AcReqGetParmType
AcReqSetScopedParameterName

AcReqGetDefaultValueDouble
Returns 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 fileNumber
The file number of the .rov or .rox file you opened with AcReqReadFile.

parmName
The 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

C ha pter 22, R equ es ter A P I re fe re nc e 385

AcReqGetDefaultValueInteger

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 AcReqGetDefaultValueStr

AcReqGetFirstParameter
AcReqGetNextParameter
AcReqGetParmType
AcReqSetScopedParameterName

AcReqGetDefaultValueInteger
Returns 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 fileNumber
The file number of the .rov or .rox file you opened with AcReqReadFile.

parmName
The 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.

386 Programming e.Reports

 AcReqGetDefaultValueStr

See also AcReqGetDefaultValueStr

AcReqGetFirstParameter
AcReqGetNextParameter
AcReqGetParmType
AcReqSetScopedParameterName

AcReqGetDefaultValueStr
Returns 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 fileNumber
The file number of the .rov or .rox file you opened with AcReqReadFile.

parmName
The 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 AcReqGetDefaultValueCurrency

AcReqGetDefaultValueDate
AcReqGetDefaultValueDouble
AcReqGetDefaultValueInteger
AcReqGetDefaultValueString
AcReqGetFirstParameter
AcReqGetNextParameter
AcReqGetParmType

C ha pter 22, R equ es ter A P I re fe re nc e 387

AcReqGetDefaultValueString

AcReqGetDefaultValueString
Returns 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 fileNumber
The file number of the .rov or .rox file you opened with AcReqReadFile.

parmName
The 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 AcReqGetDefaultValueStr

AcReqGetFirstParameter
AcReqGetNextParameter
AcReqGetParmType
AcReqSetScopedParameterName

388 Programming e.Reports

 AcReqGetError

AcReqGetError
Returns 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 returnValue
The return value from the AcReqGenerateReport function call.

fileNumber
The 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.

C ha pter 22, R equ es ter A P I re fe re nc e 389

AcReqGetError

Error number Error string

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.

390 Programming e.Reports

 AcReqGetErrorString

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

AcReqGetErrorString
Returns 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 fileNumber
The 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

AcReqGetFirstGroup
Returns 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 fileNumber
The 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

C ha pter 22, R equ es ter A P I re fe re nc e 391

AcReqGetFirstParameter

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 AcReqGetFirstParameter

AcReqGetNextGroup
AcReqGetNextParameter

AcReqGetFirstParameter
Returns 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 fileNumber
The file number of the .rov or .rox file you opened with AcReqReadFile.

parmGroup
The 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.

392 Programming e.Reports

 AcReqGetHidden

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 AcReqGetFirstGroup

AcReqGetNextGroup
AcReqGetNextParameter

AcReqGetHidden
Returns 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 fileNumber
The file number of the .rov or .rox file you opened with AcReqReadFile.

parmName
The 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 AcReqGetFirstParameter

AcReqGetNextParameter
AcReqSetScopedParameterName

AcReqGetHideText
Returns 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 )

C ha pter 22, R equ es ter A P I re fe re nc e 393

AcReqGetNextGroup

Parameter fileNumber
The file number of the .rov or .rox file you opened with AcReqReadFile.

parmName
The 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 AcReqGetFirstParameter

AcReqGetNextParameter
AcReqSetScopedParameterName

AcReqGetNextGroup
Returns 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 fileNumber
The 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.

394 Programming e.Reports

 AcReqGetNextParameter

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 AcReqGetFirstGroup

AcReqGetFirstParameter
AcReqGetNextParameter

AcReqGetNextParameter
Returns 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 fileNumber
The file number of the .rov or .rox file you opened with AcReqReadFile.

parmGroup
The 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 AcReqGetFirstGroup

AcReqGetFirstParameter
AcReqGetNextGroup

C ha pter 22, R equ es ter A P I re fe re nc e 395

AcReqGetParmType

AcReqGetParmType
Returns 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 fileNumber
The file number of the .rov or .rox file you opened with AcReqReadFile.

parmName
The 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 AcReqGetFirstParameter

AcReqGetNextParameter
AcReqGetType
AcReqSetScopedParameterName

AcReqGetReportVersion
Returns the version of the report AcReqGenerateReport generated.
Syntax Basic: Function AcReqGetReportVersion( requestHandle As Long ) As Long
C/C++: long AcReqGetReportVersion( long requestHandle )
Parameter requestHandle
AcReqGenerateReport returns the request handle in its return value. This
value is greater than or equal to 1024.

396 Programming e.Reports

 AcReqGetRequired

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

AcReqGetRequired
Returns 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 fileNumber
The file number of the .rov or .rox file you opened with AcReqReadFile.

parmName
The 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 AcReqGetFirstParameter

AcReqGetNextParameter
AcReqSetScopedParameterName

C ha pter 22, R equ es ter A P I re fe re nc e 397

AcReqGetType

AcReqGetType
Returns 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 fileNumber
The file number of the .rov or .rox file you opened with AcReqReadFile.

parmName
The 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.

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

See also AcReqGetFirstParameter

AcReqGetNextParameter
AcReqGetParmType
AcReqSetScopedParameterName

398 Programming e.Reports

 AcReqGetValueCurrency

AcReqGetValueCurrency
Returns 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 fileNumber
The file number of the .rov or .rox file you opened with AcReqReadFile.

parmName
The 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 AcReqGetFirstParameter

AcReqGetNextParameter
AcReqGetParmType
AcReqGetValueStr
AcReqSetScopedParameterName

C ha pter 22, R equ es ter A P I re fe re nc e 399

AcReqGetValueDate

AcReqGetValueDate
Returns 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 fileNumber
The file number of the .rov or .rox file you opened with AcReqReadFile.

parmName
The 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 AcReqGetFirstParameter

AcReqGetNextParameter
AcReqGetParmType
AcReqGetValueStr
AcReqSetScopedParameterName

400 Programming e.Reports

 AcReqGetValueDouble

AcReqGetValueDouble
Returns 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 fileNumber
The file number of the .rov or .rox file you opened with AcReqReadFile.

parmName
The 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 AcReqGetFirstParameter

AcReqGetNextParameter
AcReqGetParmType
AcReqGetValueStr
AcReqSetScopedParameterName

AcReqGetValueInteger
Returns 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 )

C ha pter 22, R equ es ter A P I re fe re nc e 401

AcReqGetValueStr

Parameter fileNumber
The file number of the .rov or .rox file you opened with AcReqReadFile.

parmName
The 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 AcReqGetFirstParameter

AcReqGetNextParameter
AcReqGetParmType
AcReqGetValueStr
AcReqSetScopedParameterName

AcReqGetValueStr
Returns 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 fileNumber
The file number of the .rov or .rox file you opened with AcReqReadFile.

parmName
The 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.

402 Programming e.Reports

 AcReqGetValueString

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 AcReqGetFirstParameter

AcReqGetNextParameter
AcReqGetParmType
AcReqGetValueCurrency
AcReqGetValueDate
AcReqGetValueDouble
AcReqGetValueInteger
AcReqGetValueString
AcReqSetScopedParameterName

AcReqGetValueString
Returns 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 fileNumber
The file number of the .rov or .rox file you opened with AcReqReadFile.

parmName
The 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.

C ha pter 22, R equ es ter A P I re fe re nc e 403

AcReqGetVersionNumber

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 AcReqGetFirstParameter

AcReqGetNextParameter
AcReqGetParmType
AcReqGetDefaultValueStr
AcReqSetScopedParameterName

AcReqGetVersionNumber
Returns 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.

Number Description
r Release number
v Version number
m Maintenance version
p Patch number
nnnn Build number

For example, when used with Actuate 7, AcReqGetVersionNumber returns the

following string:
7.0.0.0 - 2172

404 Programming e.Reports

 AcReqHasDefaultValue

AcReqHasDefaultValue
Returns 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 fileNumber
The file number of the .rov or .rox file you opened with AcReqReadFile.

parmName
The 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 AcReqGetDefaultValueCurrency

AcReqGetDefaultValueDate
AcReqGetDefaultValueDouble
AcReqGetDefaultValueInteger
AcReqGetDefaultValueString
AcReqGetFirstParameter
AcReqGetNextParameter
AcReqGetParmType
AcReqSetScopedParameterName

AcReqInitialize
Initializes the DLLs. This must be the first function you call.
Syntax Basic: Function AcReqInitialize( ) As Long
C/C++: long AcReqInitialize( )

C ha pter 22, R equ es ter A P I re fe re nc e 405

AcReqPrintReport

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

AcReqPrintReport
Prints 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 filename
The 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>]

options
A 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.

406 Programming e.Reports

 AcReqReadFile

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 AcReqSetPrinterCollate

AcReqSetPrinterColor
AcReqSetPrinterDuplex
AcReqSetPrinterFormName
AcReqSetPrinterName
AcReqSetPrinterNumberCopies
AcReqSetPrinterOrientation
AcReqSetPrinterPaperSize
AcReqSetPrinterScale

AcReqReadFile
Opens 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 filename
The 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>]

C ha pter 22, R equ es ter A P I re fe re nc e 407

AcReqReportStatus

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.

AcReqReportStatus
Returns 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 RequestHandle
The 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.

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.

See also AcReqGetError

AcReqGetErrorString

408 Programming e.Reports

 AcReqSelectClient

AcReqSelectClient
Select 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 clientCode
The client code as the following table shows.

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

installDir
The 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.

Product Standard Actuate search extension directory

e.Report Designer Erd
e.Report Designer ErdPro
Professional
End User Desktop Eudt
Report Viewer Viewer

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.

C ha pter 22, R equ es ter A P I re fe re nc e 409

AcReqSetDefaultPrinter

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

AcReqSetDefaultPrinter
Reverts 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 AcReqPrintReport

AcReqSetPrinterName

AcReqSetEUDTPath
Specifies 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 pathName
The 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.

410 Programming e.Reports

 AcReqSetPrinterCollate

■ 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 AcReqGenerateReport

AcReqViewReport
AcReqSelectClient

AcReqSetPrinterCollate
Specifies 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 collate
True 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

AcReqSetPrinterColor
Specifies if the report is printed in color.
Syntax Basic: Sub AcReqSetPrinterColor( color As Boolean )
C/C++: void AcReqSetPrinterColor( VBBOOL color )
Parameter color
True 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

Chapter 22, Requester API reference 411

AcReqSetPrinterDuplex

AcReqSetPrinterDuplex
Specifies 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 duplex
The duplex mode. Specify one of the following integer values.

Value Duplex mode

1 Simplex mode (no duplex)
2 Horizontal duplex mode
3 Vertical duplex mode

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

AcReqSetPrinterFormName
Specifies 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 formName
The 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

412 Programming e.Reports

 AcReqSetPrinterName

AcReqSetPrinterName
Specifies the printer to use.
Syntax Basic: Sub AcReqSetPrinterName( printerName As String )
C/C++: void AcReqSetPrinterName( LPCSTR printerName )
Parameter printerName
The 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 AcReqPrintReport

AcReqSetDefaultPrinter

AcReqSetPrinterNumberCopies
Specifies the number of copies to print.
Syntax Basic: Sub AcReqSetPrinterNumberCopies( numCopies As Integer )
C/C++: void AcReqSetPrinterNumberCopies( short numCopies )
Parameter numCopies
The 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 AcReqSetPrinterCollate

AcReqPrintReport

AcReqSetPrinterOrientation
Sets the printer’s page orientation to portrait or landscape.
Syntax Basic: Sub AcReqSetPrinterOrientation( orientation As Integer )
C/C++: void AcReqSetPrinterOrientation( short orientation )

C ha pter 22, R equ es ter A P I re fe re nc e 413

AcReqSetPrinterPaperSize

Parameter orientation
1 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

AcReqSetPrinterPaperSize
Specifies 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 size
An 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

414 Programming e.Reports

 AcReqSetPrinterPaperSize

Enum value Paper size

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

C ha pter 22, R equ es ter A P I re fe re nc e 415

AcReqSetPrinterPaperSize

Enum value Paper size

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

length, width
The 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

416 Programming e.Reports

 AcReqSetPrinterScale

AcReqSetPrinterScale
Specifies the size of the image to print.
Syntax Basic: Sub AcReqSetPrinterScale( scale As Integer )
C/C++: void AcReqSetPrinterScale( short scale )
Parameter scale
The 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

AcReqSetPrinterTray
Specifies the printer tray for the paper source.
Syntax Basic: Sub AcReqSetPrinterTray( tray as Short)
C/C++: void AcReqSetPrinterTray( short tray)
Parameter tray
An 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.

C ha pter 22, R equ es ter A P I re fe re nc e 417

AcReqSetRequestPriority

Enum value Description

10 Use paper from the large paper bin.
11 Use paper from the large capacity feeder.
14 Use paper from the attached cassette cartridge.

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

AcReqSetRequestPriority
Specifies the priority for report generation on iServer.
Syntax Basic: Sub AcReqSetRequestPriority( priority as Long)
C/C++: void AcReqSetRequestPriority( long priority )
Parameter priority
The 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

AcReqSetScopedParameterName
Specifies how parameter names are retrieved.
Syntax Basic: Sub AcReqSetScopedParameterName( fileNumber As Long,
scopedParam As Boolean )
C/C++: void AcReqSetScopedParameterName( Long fileNumber, VBBOOL
scopedParam )
Parameter fileNumber
The file number of the .rov or .rox file you opened with AcReqReadFile.

418 Programming e.Reports

 AcReqSetValueCurrency

scopedParam
Determines 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 AcReqGetFirstParameter

AcReqGetNextParameter

AcReqSetValueCurrency
Sets 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 fileNumber
The file number of the .rov or .rox file you opened with AcReqReadFile.

parmName
The 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.

C ha pter 22, R equ es ter A P I re fe re nc e 419

AcReqSetValueDate

value
The 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 AcReqGetFirstParameter

AcReqGetNextParameter
AcReqGetParmType
AcReqSetScopedParameterName

AcReqSetValueDate
Sets 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 fileNumber
The file number of the .rov or .rox file you opened with AcReqReadFile.

parmName
The 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.

value
The 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

420 Programming e.Reports

 AcReqSetValueDouble

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 s
inDate = oleDate;
fileNumber = AcReqReadFile( szSourceRox );
outDate = AcReqGetDefaultValueDate(fileNumber, "aDate");
oleDate = outDate;
AcReqSetValueDate( fileNumber, "aDate", inDate );
AcReqCloseFile( fileNumber );

See also AcReqGetFirstParameter

AcReqGetNextParameter
AcReqGetParmType
AcReqSetScopedParameterName

AcReqSetValueDouble
Sets 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 fileNumber
The file number of the .rov or .rox file you opened with AcReqReadFile.

parmName
The 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.

value
The 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.

C ha pter 22, R equ es ter A P I re fe re nc e 421

AcReqSetValueInteger

See also AcReqGetFirstParameter

AcReqGetNextParameter
AcReqGetParmType
AcReqSetScopedParameterName

AcReqSetValueInteger
Sets 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 fileNumber
The file number of the .rov or .rox file you opened with AcReqReadFile.

parmName
The 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.

value
The 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 AcReqGetFirstParameter

AcReqGetNextParameter
AcReqGetParmType
AcReqSetScopedParameterName

AcReqSetValueString
Sets the value of the specified parameter as a string.
Syntax Basic: Sub AcReqSetValueString( fileNumber As Long, parmName As String,
value As String )

422 Programming e.Reports

 AcReqUnInitialize

C/C++: void AcReqSetValueString( long fileNumber, LPCSTR parmName,

LPCSTR value )
Parameter fileNumber
The file number of the .rov or .rox file you opened with AcReqReadFile.

parmName
The 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.

value
The 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 AcReqGetFirstParameter

AcReqGetNextParameter
AcReqGetParmType
AcReqSetScopedParameterName

AcReqUnInitialize
Closes the Requester API library and frees resources.
Syntax Basic: Function AcReqUninitialize( sessionHandle ) As Boolean
C/C++: VBBOOL AcReqUnInitialize( long sessionHandle )
Parameter sessionHandle
The 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

C ha pter 22, R equ es ter A P I re fe re nc e 423

AcReqViewReport

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 filename
The 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>]

options
A 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 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.

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

424 Programming e.Reports

 AcReqWriteFile

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

AcReqWriteFile
Creates a parameter value (.rov) file.
Syntax Basic: Sub AcReqWriteFile( fileNumber As Long, filename As String )
C/C++: void AcReqWriteFile( long fileNumber, LPCSTR filename )
Parameter fileNumber
The file number of the .rov or .rox file you opened with AcReqReadFile.

filename
The 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

AcWReqConnect
Connects to the specified server.

C ha pter 22, R equ es ter A P I re fe re nc e 425

AcWReqGenerateReport

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 server
The name of iServer to which to connect.

user
The user name to use to log into iServer.

password
The 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

AcWReqGenerateReport
Generates 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 aFileName
The 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.”

426 Programming e.Reports

 AcWReqGenerateReport

options
A 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.

C ha pter 22, R equ es ter A P I re fe re nc e 427

AcWReqGenerateReport

Scope of options
The following table shows which options apply to reports generated locally or
on iServer and launched from either local or server applications.

Local report Server report Server report

Options Local launch Local launch Server launch
AC_REQ_LAUNCH_ALWAYS Yes Yes, if report No
viewing needed
AC_REQ_LOCAL Yes, if using Actuate No No
Basic
AC_REQ_VIEW Yes Yes No
AC_REQ_PRINT Yes Yes Yes
AC_REQ_ASYNC Yes Yes Yes
AC_REQ_HIDE Yes, if report Yes, if report No
viewing not needed viewing not needed
AC_REQ_RETURN_HANDLE Yes Yes Yes
AC_REQ_STAY_OPEN Yes Yes, if report No
viewing needed
AC_REQ_REPLACE No Yes Yes

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.

fileHandle
The 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,

428 Programming e.Reports

 AcWReqGenerateReport

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.

Report
Return value generation mode Indication
0 Report generated Report executed successfully on a
asynchronously local client.
1 to 1023 Report generated Report execution failed.
asynchronously 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 Report executed successfully on
asynchronously 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 Report executed successfully on
synchronously iServer.
greater than 0 Report generated Report execution failed.
synchronously

C ha pter 22, R equ es ter A P I re fe re nc e 429

AcWReqGetAdhoc

See also AcReqGetReportVersion

AcReqSetRequestPriority
AcWReqSetEUDTPath

AcWReqGetAdhoc
Returns 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 fileHandle
The handle to the file you opened with AcReqReadFile or AcWReqReadFile.

aParmName
The 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 AcReqSetScopedParameterName

AcWReqGetFirstParameter
AcWReqGetNextParameter

AcWReqGetAlias
Returns 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 fileHandle
The handle to the file you opened with AcReqReadFile or AcWReqReadFile.

430 Programming e.Reports

 AcWReqGetDefaultValueCurrency

aParmName
The 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 AcReqSetScopedParameterName

AcWReqGetFirstParameter
AcWReqGetNextParameter

AcWReqGetDefaultValueCurrency
Returns 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 fileHandle
The handle to the file you opened with AcReqReadFile or AcWReqReadFile.

aParmName
The 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.

C ha pter 22, R equ es ter A P I re fe re nc e 431

AcWReqGetDefaultValueDate

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 AcReqSetScopedParameterName

AcWReqGetDefaultValueStr
AcWReqGetFirstParameter
AcWReqGetNextParameter
AcWReqGetParmType

AcWReqGetDefaultValueDate
Returns 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 fileHandle
The handle to the file you opened with AcReqReadFile or AcWReqReadFile.

aParmName
The 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.

432 Programming e.Reports

 AcWReqGetDefaultValueDouble

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 AcReqSetScopedParameterName

AcWReqGetDefaultValueStr
AcWReqGetFirstParameter
AcWReqGetNextParameter
AcWReqGetParmType

AcWReqGetDefaultValueDouble
Returns 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 fileHandle
The handle to the file you opened with AcReqReadFile or AcWReqReadFile.

aParmName
The 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.

C ha pter 22, R equ es ter A P I re fe re nc e 433

AcWReqGetDefaultValueInteger

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 AcReqSetScopedParameterName

AcWReqGetDefaultValueStr
AcWReqGetFirstParameter
AcWReqGetNextParameter
AcWReqGetParmType

AcWReqGetDefaultValueInteger
Returns 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 fileHandle
The handle to the file you opened with AcReqReadFile or AcWReqReadFile.

aParmName
The 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.

434 Programming e.Reports

 AcWReqGetDefaultValueStr

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 AcReqSetScopedParameterName

AcWReqGetDefaultValueStr
AcWReqGetFirstParameter
AcWReqGetNextParameter
AcWReqGetParmType

AcWReqGetDefaultValueStr
Returns 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 fileHandle
The handle to the file you opened with AcReqReadFile or AcWReqReadFile.

aParmName
The 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.

C ha pter 22, R equ es ter A P I re fe re nc e 435

AcWReqGetDefaultValueString

See also AcWReqGetDefaultValueCurrency

AcWReqGetDefaultValueDate
AcWReqGetDefaultValueDouble
AcWReqGetDefaultValueInteger
AcWReqGetDefaultValueString
AcWReqGetFirstParameter
AcWReqGetNextParameter
AcWReqGetParmType

AcWReqGetDefaultValueString
Returns 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 fileHandle
The handle to the file you opened with AcReqReadFile or AcWReqReadFile.

aParmName
The 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 AcReqSetScopedParameterName

AcWReqGetDefaultValueStr
AcWReqGetFirstParameter
AcWReqGetNextParameter
AcWReqGetParmType

436 Programming e.Reports

 AcWReqGetErrorString

AcWReqGetErrorString
Returns 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 fileHandle
The 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.

AcWReqGetFirstGroup
Returns 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 fileHandle
The 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.

C ha pter 22, R equ es ter A P I re fe re nc e 437

AcWReqGetFirstParameter

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 AcWReqGetFirstParameter

AcWReqGetNextGroup
AcWReqGetNextParameter

AcWReqGetFirstParameter
Returns 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 fileHandle
The handle to the file you opened with AcReqReadFile or AcWReqReadFile.

aGroupName
The 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 AcWReqGetFirstGroup

AcWReqGetNextGroup
AcWReqGetNextParameter

438 Programming e.Reports

 AcWReqGetHidden

AcWReqGetHidden
Returns 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 fileHandle
The handle to the file you opened with AcReqReadFile or AcWReqReadFile.

aParmName
The 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 AcReqSetScopedParameterName

AcWReqGetFirstParameter
AcWReqGetNextParameter

AcWReqGetHideText
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.
Syntax Basic: Function AcWReqGetHideText( fileNumber As Long, parmName As
String ) As Boolean
C/C++: VBBOOL AcWReqGetHideText( long fileHandle, LPCTSTR
aParmName )
Parameter fileHandle
The handle to the file you opened with AcReqReadFile or AcWReqReadFile.

C ha pter 22, R equ es ter A P I re fe re nc e 439

AcWReqGetNextGroup

aParmName
The 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 AcReqSetScopedParameterName

AcWReqGetFirstParameter
AcWReqGetNextParameter

AcWReqGetNextGroup
Returns 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 fileHandle
The 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.

440 Programming e.Reports

 AcWReqGetNextParameter

An empty string if there are no more groups or if an error occurred.

See also AcWReqGetFirstGroup

AcWReqGetFirstParameter
AcWReqGetNextParameter

AcWReqGetNextParameter
Returns 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 fileHandle
The handle to the file you opened with AcReqReadFile or AcWReqReadFile.

aGroupName
The 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 AcWReqGetFirstGroup

AcWReqGetFirstParameter
AcWReqGetNextGroup
AcWReqGetNextParameter

C ha pter 22, R equ es ter A P I re fe re nc e 441

AcWReqGetParmType

AcWReqGetParmType
Returns 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 fileHandle
The handle to the file you opened with AcReqReadFile or AcWReqReadFile.

aParmName
The 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 AcReqGetType

AcReqSetScopedParameterName
AcWReqGetFirstParameter
AcWReqGetNextParameter

AcWReqGetRequired
Returns 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 )

442 Programming e.Reports

 AcWReqGetValueCurrency

Parameter fileHandle
The handle to the file you opened with AcReqReadFile or AcWReqReadFile.

aParmName
The 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 AcReqSetScopedParameterName

AcWReqGetFirstParameter
AcWReqGetNextParameter

AcWReqGetValueCurrency
Returns 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 fileHandle
The handle to the file you opened with AcReqReadFile or AcWReqReadFile.

aParmName
The 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

C ha pter 22, R equ es ter A P I re fe re nc e 443

AcWReqGetValueDate

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 AcReqSetScopedParameterName

AcWReqGetFirstParameter
AcWReqGetNextParameter
AcWReqGetParmType
AcWReqGetValueStr

AcWReqGetValueDate
Returns 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 fileHandle
The handle to the file you opened with AcReqReadFile or AcWReqReadFile.

aParmName
The 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.

444 Programming e.Reports

 AcWReqGetValueDouble

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 AcReqSetScopedParameterName

AcWReqGetFirstParameter
AcWReqGetNextParameter
AcWReqGetParmType
AcWReqGetValueStr

AcWReqGetValueDouble
Returns 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 fileHandle
The handle to the file you opened with AcReqReadFile or AcWReqReadFile.

aParmName
The 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.

C ha pter 22, R equ es ter A P I re fe re nc e 445

AcWReqGetValueInteger

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 AcReqSetScopedParameterName

AcWReqGetFirstParameter
AcWReqGetNextParameter
AcWReqGetParmType
AcWReqGetValueStr

AcWReqGetValueInteger
Returns 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 fileHandle
The handle to the file you opened with AcReqReadFile or AcWReqReadFile.

aParmName
The 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.

446 Programming e.Reports

 AcWReqGetValueStr

See also AcReqSetScopedParameterName

AcWReqGetFirstParameter
AcWReqGetNextParameter
AcWReqGetParmType
AcWReqGetValueStr

AcWReqGetValueStr
Returns 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 fileHandle
The handle to the file you opened with AcReqReadFile or AcWReqReadFile.

aParmName
The 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 AcReqSetScopedParameterName

AcWReqGetFirstParameter
AcWReqGetNextParameter
AcWReqGetParmType
AcWReqGetValueCurrency
AcWReqGetValueDate
AcWReqGetValueDouble
AcWReqGetValueInteger
AcWReqGetValueString

C ha pter 22, R equ es ter A P I re fe re nc e 447

AcWReqGetValueString

AcWReqGetValueString
Returns 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 fileHandle
The handle to the file you opened with AcReqReadFile or AcWReqReadFile.

aParmName
The 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 AcReqSetScopedParameterName

AcWReqGetFirstParameter
AcWReqGetNextParameter
AcWReqGetParmType
AcWReqGetDefaultValueStr

AcWReqGetVersionNumber
Returns Actuate requester API version information as a string.
Syntax Basic: Function AcWReqGetVersionNumber( ) As String
C/C++: BSTR AcWReqGetVersionNumber( )

448 Programming e.Reports

 AcWReqHasDefaultValue

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.

Number Description
r Release number
v Version number
m Maintenance version
p Patch number
nnnn Build number

For example, when used with Actuate 7, AcReqGetVersionNumber returns the

following string:
7.0.0.0 - 2172

AcWReqHasDefaultValue
Returns 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 fileNumber
The file number of the file you opened with AcReqReadFile or
AcWReqReadFile.

aParmName
The 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.

C ha pter 22, R equ es ter A P I re fe re nc e 449

AcWReqPrintReport

Returns True if a default value was assigned, False otherwise.

See also AcReqSetScopedParameterName

AcWReqGetDefaultValueCurrency
AcWReqGetDefaultValueDate
AcWReqGetDefaultValueDouble
AcWReqGetDefaultValueInteger
AcWReqGetDefaultValueString
AcWReqGetFirstParameter
AcWReqGetNextParameter
AcWReqGetParmType

AcWReqPrintReport
Prints the specified report.
Syntax Basic: Function AcWReqPrintReport( filename As String, options As Long ) As
Long
C/C++: long AcWReqPrintReport( LPCTSTR aFileName, long options )
Parameter aFileName
The 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.”

options
A 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.

450 Programming e.Reports

 AcWReqPrintReport

Constant Description
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.

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 AcReqSetPrinterCollate

AcReqSetPrinterColor
AcReqSetPrinterDuplex
AcReqSetPrinterNumberCopies
AcReqSetPrinterOrientation
AcReqSetPrinterPaperSize
AcReqSetPrinterScale
AcReqSetPrinterFormName
AcWReqSetPrinterName

C ha pter 22, R equ es ter A P I re fe re nc e 451

AcWReqReadFile

AcWReqReadFile
Opens 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 aFileName
The 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.

AcWReqSetEUDTPath
Specifies 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 aPath
The 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" )

452 Programming e.Reports

 AcWReqSetPrinterName

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 AcWReqGenerateReport

AcWReqViewReport
AcReqSelectClient

AcWReqSetPrinterName
Specifies the printer to use.
Syntax Basic: Sub AcWReqSetPrinterName( printerName As String )
C/C++: void AcWReqSetPrinterName( LPCTSTR printerName )
Parameter printerName
The 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 AcReqSetDefaultPrinter

AcWReqPrintReport

AcWReqSetValueCurrency
Sets 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 )

C ha pter 22, R equ es ter A P I re fe re nc e 453

AcWReqSetValueDate

Parameter fileHandle
The handle to the file you opened with AcReqReadFile or AcWReqReadFile.

aParmName
The 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.

value
The 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 AcReqSetScopedParameterName

AcWReqGetFirstParameter
AcWReqGetNextParameter
AcWReqGetParmType

AcWReqSetValueDate
Sets 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 fileHandle
The handle to the file you opened with AcReqReadFile or AcWReqReadFile.

aParmName
The 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.

454 Programming e.Reports

 AcWReqSetValueDouble

value
The 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 s
inDate = oleDate;
fileNumber = AcWReqReadFile( szSourceRox );
outDate = AcWReqGetDefaultValueDate(fileNumber, "aDate");
oleDate = outDate;
AcWReqSetValueDate( fileNumber, "aDate", inDate );
AcReqCloseFile( fileNumber );

See also AcReqSetScopedParameterName

AcWReqGetFirstParameter
AcWReqGetNextParameter
AcWReqGetParmType

AcWReqSetValueDouble
Sets 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 fileHandle
The handle to the file you opened with AcReqReadFile or AcWReqReadFile.

aParmName
the names of the parameters, use AcWReqGetFirstParameter and
AcWReqGetNextParameter to get the parameter names.

C ha pter 22, R equ es ter A P I re fe re nc e 455

AcWReqSetValueInteger

value
The 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 AcReqSetScopedParameterName

AcWReqGetFirstParameter
AcWReqGetNextParameter
AcWReqGetParmType

AcWReqSetValueInteger
Sets 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 fileHandle
The handle to the file you opened with AcReqReadFile or AcWReqReadFile.

aParmName
The 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.

value
The 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 AcReqSetScopedParameterName

AcWReqGetFirstParameter
AcWReqGetNextParameter
AcWReqGetParmType

456 Programming e.Reports

 AcWReqSetValueString

AcWReqSetValueString
Sets 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 fileHandle
The handle to the file you opened with AcReqReadFile or AcWReqReadFile.

AParmName
The 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.

value
The 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 AcReqSetScopedParameterName

AcWReqGetFirstParameter
AcWReqGetNextParameter
AcWReqGetParmType

AcWReqViewReport
Displays 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 aFileName
The 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>]

C ha pter 22, R equ es ter A P I re fe re nc e 457

AcWReqViewReport

For information about specifying server file names, see Chapter 2, “Specifying
an iServer file name—Requester API.”

options
A 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 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.

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

458 Programming e.Reports

 AcWReqWriteFile

AcWReqWriteFile
Creates a parameter value (.rov) file.
Syntax Basic: Sub AcWReqWriteFile( fileNumber As Long, filename As String )
C/C++: void AcWReqWriteFile( long fileHandle, LPCTSTR aFileName )
Parameter fileHandle
The handle to the file you opened with AcReqReadFile or AcWReqReadFile.

aFileName
The 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 functions
The 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.
AcReqAddToCache
AcReqDropFromCache
AcReqGetCacheFile
AcReqGetPrinterCapabilities
AcReqInfo

C ha pter 22, R equ es ter A P I re fe re nc e 459

AcWReqWriteFile

460 Programming e.Reports

 Chapter

Search extension API

Chapter 23

user 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

Chapter 23, Search extension API user guide 461

About the search extension API
Actuate 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.”

462 Programming e.Repor ts

Writing startup and cleanup code
The following table lists the functions for starting and ending a search session.

Programming task API function

Close files or APIs and perform other cleanup Close
operations. This function is required.
Specify a user friendly name for the search GetName
extension. This function is required.
Open files or APIs used in the search process. Open
This function is required.

GetName and Open are startup operations called at the beginning of the
search process. Close is called when the search is complete.

Setting search parameters

The following table lists the functions for working with search parameters.

Programming task API function

Specify the extension-specific parameters for the GetParameters
search operation. This function is optional.
Collect extension-specific parameters from the InputParameters
user. This function is optional.
Pass extension-specific search definition SetParameters
parameters to the search extension DLL. This
function is optional.

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

Chapter 23, Search extension API user guide 463

 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 results

The following table lists the functions for processing search results in Actuate
7.

Programming task API function

Specify the delimiter character that separates GetColumnDelimiter
columns of search data. This function is
required.
Specify whether or not the search data should IncludeHeader
include a header. This function is optional.
Transfer each row as it is created during the PutRow
search process. This function is required.
Retrieve the data type of each column in a row. SetDataTypeInfo

GetColumnDelimiter and IncludeHeader define data format and are called

before the search. PutRow transfers the search results to the extension.

Developing a search extension

The 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 code

Write 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.

464 Programming e.Repor ts

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 file

The 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:
EXPORTS
GetName =ExcelGetName
GetParameters =ExcelGetParameters
SetParameters =ExcelSetParameters
InputParameters =ExcelInputParameters
GetColumnDelimiter =ExcelGetDelimiter
IncludeHeader =ExcelIncludeHeader
Open =ExcelOpen
Close =ExcelClose
PutRow =ExcelPutRow

Chapter 23, Search extension API user guide 465

 Creating a header file
The 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 code

Compile the Actuate 7 search extension with Visual C++ 6.0.

Installing a custom search extension

A 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.

466 Programming e.Repor ts

 Chapter

Search extension API

Chapter 24

reference
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.

Chapter 24, Search ex tension API reference 467

Close

Close
Closes files or APIs and performs other cleanup operations. This function is
required.
Syntax BOOL Close(long event)
Parameter event
The reason for closing the search extension:
0 - the search completed normally
1 - the search was stopped by the user
2 - the search was stopped due to the application closing
3 - 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

GetColumnDelimiter
Specifies 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

468 Programming e.Repor ts

 GetName

GetName
Specifies 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.

GetParameters
Specifies 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 InputParameters

SetParameters

IncludeHeader
Specifies 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.

Chapter 24, Search ex tension API reference 469

InputParameters

Returns True to include headers or False to exclude headers.

The default value is True if the function is not implemented.

See also PutRow

InputParameters
Collects 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 GetParameters

SetParameters

Open
Opens 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

PutRow
Transfers each row as it is created during the search process. This function is
required.
Syntax BOOL PutRow( long rowIdx, const char* row )

470 Programming e.Repor ts

 SetDataTypeInfo

Parameter rowIdx
A number indicating the row index for the search.

char
A 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 IncludeHeader

GetColumnDelimiter

SetDataTypeInfo
Provides the data types for all columns of a row.
Syntax void SetDataTypeInfo( long numCols, long *dataTypes )
Parameter numCols
The number of columns in a row.

*dataTypes
An 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

Chapter 24, Search ex tension API reference 471

SetParameters

■ 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.

SetParameters
Passes extension-specific search definition parameters to the search extension
DLL.
Syntax void SetParameters( const char* parms )
Parameter params
A 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 GetParameters

InputParameters

472 Programming e.Repor ts

 Chapter

Actuate ActiveX controls

Chapter 25

user 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

Chapter 25, Actuate ActiveX controls user guide 473

About Actuate’s ActiveX controls
ActiveX 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 controls

Actuate 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

application
You 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

Basic
Visual 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.

474 Programming e.Repor ts

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 dialogs

Use 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 support
virtual BOOL PreTranslateMessage(MSG* pMsg);
//}}AFX_VIRTUAL
>
>
>
}
BOOL AcViewerDialog::PreTranslateMessage(MSG* pMsg)
{
if ( m_viewer.CheckMessage( (long*)pMsg ) )
return TRUE;

return CDialog::PreTranslateMessage(pMsg);
}

Chapter 25, Actuate ActiveX controls user guide 475

About report files and the Actuate ActiveX controls
When 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 reports

The 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 reports

Specify 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.

476 Programming e.Repor ts

 <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.

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

Actuate ActiveX methods by programming task

This 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 instance

The 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.

Chapter 25, Actuate ActiveX controls user guide 477

 The following methods implement server connections and report access.

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.

Navigating and viewing the report instance

Client 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
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

478 Programming e.Repor ts

Method Description
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

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

Running a report
The 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.

Chapter 25, Actuate ActiveX controls user guide 479

 The following table summarizes the methods for running reports.

Method Description
OpenReportExecutable Opens a report executable (.rox) file. Use in
(Desktop ActiveX Control conjunction with RunReport to generate a new
only) report.
RunReport (Desktop Opens the standard parameter screen, runs
ActiveX Control only) the open report executable file, and displays
the generated report.
RunReportWithParameters Runs the open report executable file using a
(Desktop ActiveX Control parameter file and displays the generated
only) report.
CanRunReport (Desktop Indicates whether or not a report executable
ActiveX Control only) file is open and can run.
CancelReport (Desktop Cancels a currently executing request to run a
ActiveX Control only) report.
CloseReportExecutable Closes the current report instance, if there is
(Desktop ActiveX Control one, and the report executable file.
only)

Printing, mailing, and saving a report

The following table summarizes the methods for printing, mailing, and saving
reports.

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.

Invoking functions in an open report

Actuate 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.

480 Programming e.Repor ts

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 conditions

Most 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 Integer
DIM statusString1 as String
DIM statusString2 as String

' Clear any existing statuses

ResetStatus()

' 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 exist
statusString1 = GetStatusCount( 0 );
statusString2 = GetStatusCount( 1 );
}

' Clear the statuses again

ResetStatus()

' Continue with other ActiveX calls

Chapter 25, Actuate ActiveX controls user guide 481

Visual Basic example
This 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 application

Build the sample application as follows:
■ Add the Desktop control to the toolbox.

482 Programming e.Repor ts

■ 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.

Button tool

Desktop ActiveX control

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.

Chapter 25, Actuate ActiveX controls user guide 483

 The following Visual Basic window shows the completed code for each
event.

Visual Basic code segment descriptions

When 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_Click
The Exit button closes the report with CloseReportInstance(). Closing the
report makes it available to other applications.

Next_Click
The 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.

484 Programming e.Repor ts

Prev_Click
The Prev button uses PreviousPage() to back up one page in the report. This
navigation tool supports paging backward through the document.

Print_Click
The 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_Click
The Run button invokes two Desktop control methods. First, it opens the
report executable file with OpenReportExecutable(), then it runs the report
with RunReport().

Contents_Click
The 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_Click
The 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 application

The 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.

Chapter 25, Actuate ActiveX controls user guide 485

 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 controls

If 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.

ActiveX afc
bin
etc

486 Programming e.Repor ts

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

Chapter 25, Actuate ActiveX controls user guide 487

 ■ 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 files

The 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 conventions

The following table summarizes the file naming conventions for Actuate 7

488 Programming e.Repor ts

.

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

API file versions

When 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.”

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

Chapter 25, Actuate ActiveX controls user guide 489

 Actuate ActiveX controls release VC++ 6.0
5.0 acrq5060.dll
4.0 to 4.1 acrq4060.dll

490 Programming e.Repor ts

 Chapter

Actuate ActiveX controls

Chapter 26

reference
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.

Cha pter 26 , A c tuate A c tiveX co ntr ols re fe re nc e 491

AboutBox

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.

Back
Opens 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.

BackDisable
Occurs 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.

BackEnable
Occurs when an external hyperlink has been followed.
Syntax BackEnable()

492 Programming e.Reports

 BundleReportInstance

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 fileName
The 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.

CallBasicFunction
Calls 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 methodName
String 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.

Cha pter 26 , A c tuate A c tiveX co ntr ols re fe re nc e 493

CancelReport

Returns The value the Actuate Basic function returns, unless an error occurs. If an error
occurs, CallBasicFunction returns one of the following error codes.

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

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 RunReport

RunReportWithParameters

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 OpenReportExecutable

RunReport

494 Programming e.Reports

 CloseReportExecutable

CloseReportExecutable
Desktop 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

CloseReportInstance
Closes 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 OpenReportInstance

OpenReportExecutable

ConnectToServer
Establishes an iServer connection.
Syntax BOOL ConnectToServer(LPCTSTR hostName, LPCTSTR userName,
LPCTSTR password)
Parameter hostName
The name of the host computer where iServer is running. iServer has the same
name as the host computer.

userName
The name of a valid user on the administration server.

password
The password associated with the userName.

Cha pter 26 , A c tuate A c tiveX co ntr ols re fe re nc e 495

CurrentPage

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.

CurrentPage
Returns 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.

FirstPage
Resets 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.

GetLastError
Returns 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.

496 Programming e.Reports

 GetMostRecentListCount

Returns A CString describing the error condition.

An empty string if no errors occurred.

GetMostRecentListCount
Returns 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.

GetMostRecentListItemAt
Returns the URL or path of the specified report from the recently opened
reports list.
Syntax BSTR GetMostRecentListItemAt(long index)
Parameter index
The 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.

GetStatusCount
Returns 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.

Cha pter 26 , A c tuate A c tiveX co ntr ols re fe re nc e 497

GetStatusMessageAt

GetStatusMessageAt
Returns the status message string from the specified point in the status stack.
Syntax BSTR GetStatusMessageAt(long index)
Parameter index
The 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.

GoToPage
Changes the view to a specific page number of the report.
Syntax BOOL GoToPage(long Page)
Parameter Page
The 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.

LastPage
Advances 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.

LoadResource
Loads the NLS resource DLL.
Syntax BOOL LoadResource(LPCTSTR localeName)

498 Programming e.Reports

 MailReportInstance

Parameter localeName
Three-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 for
Nls\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.

MailReportInstance
Displays 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.

NextPage
Advances 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.

Cha pter 26 , A c tuate A c tiveX co ntr ols re fe re nc e 499

OpenRecentReportInstance

OpenRecentReportInstance
Opens the specified report from the recently opened reports list.
Syntax short OpenRecentReportInstance(long index)
Parameter index
The 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.

OpenReportExecutable
Desktop ActiveX Control only. Opens a report executable file.
Syntax BOOL OpenReportExecutable (LPCTSTR reportName)
Parameter reportName
The 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 RunReport

CloseReportInstance
CloseReportExecutable

500 Programming e.Reports

 OpenReportInstance

OpenReportInstance
Opens a report in the Encyclopedia volume or the client file system.
Syntax short OpenReportInstance (LPCTSTR reportName)
Parameter reportName
The 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 CloseReportInstance

ConnectToServer

PageCount
Returns 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.

Cha pter 26 , A c tuate A c tiveX co ntr ols re fe re nc e 501

PreviousPage

PreviousPage
Moves 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.

Print
Opens the standard Windows print dialog for report printing. Use in C++
applications only.
Syntax void Print(BOOL showDialog)
Parameter showDialog
True 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

PrintReport
Opens the standard Windows print dialog for report printing. This method
supersedes Print.
Syntax void PrintReport(BOOL showDialog)
Parameter showDialog
True opens the standard Windows print dialog. False prints with default print
parameters.

502 Programming e.Reports

 ResetStatus

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

ResetStatus
Clears 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 OpenReportExecutable

CancelReport

Cha pter 26 , A c tuate A c tiveX co ntr ols re fe re nc e 503

RunReportWithParameters

RunReportWithParameters
Desktop ActiveX Control only. Runs the open report executable file to generate
a new report instance.
Syntax BOOL RunReportWithParameters(LPCTSTR parameterFile)
Parameter parameterFile
The 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 OpenReportExecutable

CancelReport

SaveAsXMLData
Saves the open report in XML format.
Syntax BOOL SaveAsXmlData(LPCTSTR filename)
Parameter filename
The 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.

504 Programming e.Reports

 SearchWindow

SearchWindow
Opens 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.

SetScaleFactor
Sets the scale factor for the view.
Syntax BOOL SetScaleFactor(long factor)
Parameter factor
The 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.

SetWindowLayout
Sets the Windows layout to right to left or left to right.
Syntax BOOL SetWindowLayout(int orientation)
Parameter orientation
The 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.

Cha pter 26 , A c tuate A c tiveX co ntr ols re fe re nc e 505

TableOfContents

TableOfContents
Opens 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.

506 Programming e.Reports

 Index
Symbols A
! (exclamation point) in code 267 About dialog box 492
" (double quotation mark) in strings 268 AboutBox method 478, 492
" (quotation mark) in strings 272 abstract base classes 4, 21
# (number sign) Actuate-specific 4
in dates 273, 274 AC_DWB constant 409
type declaration 267 AC_ERD constant 409
$ (dollar sign) character in code 267, 273 AC_EUDT constant 409
% (percent) character in code 266 AC_REQ_ASYNC constant 378, 379, 406,
& (ampersand) character in code 266 424, 427, 428, 451, 458
& operator 256 AC_REQ_CURRENCY type 398
( ) characters in expressions 256 AC_REQ_DATETIME type 398
* (asterisk) as text string 394, 440 AC_REQ_DOUBLE type 398
* operator 254 AC_REQ_GENERATE constant 353, 356, 378,
+ (plus) characters 427
line continuation 257 AC_REQ_HIDE constant 378, 379, 406, 427,
multiple options in API function calls 378, 428, 451
427 AC_REQ_INTEGER type 398
+ operator 254 AC_REQ_LAUNCH_ALWAYS constant 378,
. (dot) operator 39, 40, 276 379, 406, 424, 427, 428, 450, 458
/ operator 254 AC_REQ_LOCAL constant 378, 379, 411, 424,
: (colon) as separation character 257 427, 428, 453, 458
:: operator 22 AC_REQ_PRINT constant 356, 378, 379, 406,
< operator 255 427, 428, 450
<= operator 255 AC_REQ_REPLACE constant 378, 379, 427,
<> operator 255 428
= operator AC_REQ_RETURN_HANDLE constant 378,
assignment 252 379, 427, 428
comparisons 254, 255 AC_REQ_ROX constant 349
> operator 255 AC_REQ_SHOW_PROG_WND
>= operator 255 constant 378, 427
@ (at-sign) character in code 253, 267 AC_REQ_STAY_OPEN constant 378, 379,
\ operator 254 406, 427, 428, 451
^ operator 254 AC_REQ_STRING type 398
– (minus sign) in strings 270 AC_REQ_UNKNOWN type 398
– operator 254 AC_REQ_USE_HANDLE constant 378, 427
’ (apostrophe) in code 256 AC_REQ_VIEW constant 353, 378, 379, 424,
427, 428, 458
Numerics AC_VIEWER constant 409
32-bit applications 293 AcBaseFrame class 6, 11
AcBasePage class 11
acbrio.dll 487

Index 507
AcBTree class 14 AcDataSource class
Access Control Lists 133 overview 6, 9
customizing 153–154 subclassing for custom data streams 94
displaying 139 AcDateTimeControl class 14
suppressing security IDs in 153 AcDBConnection class 5, 8
access control lists (ACLs) AcDBCursor class 9, 85
debugging 120 AcDBStatement class 9, 85
access restrictions 132, 154 AcDetailGraph class 14
accessing AcDoubleControl class 14
data xxiii AcEllipseControl class 14
report sections 153 acfile.dll 487
Java objects xxvii AcFlow class 6, 11
online documentation xxxii AcFrame class 12
accessing Actuate APIs 337 AcGraph class 14
accessing data AcGroupSection class 10
from external applications 81, 292, 304 AcHLCGraph class 14
from multiple sources 98–103 AcImageControl class 14
in flat files 94–98 AcInformixConnection class 8
in input data sources 79 AcIntegerControl class 14
in OLE objects 294, 295 AcIterator class 14
in SQL tables 85 AcLabelControl class 14
in text files 90 AcLeftRightPageList class 11, 73
methods specific to 31 AcLineControl class 14
accessing Java objects 316, 317–318 AcList class 14
accessing online help xxxii AcMemoryBuffer class 10, 80
accessing report files 376, 426 AcMemoryDataSorter class 10
accessing reports AcMSSQLConnection class 8
ActiveX method calls for 496 AcMultipleInputFilter class 10, 80, 98
in Encyclopedia volumes 335 AcObjectArray class 14
AcCleanup function 310 AcODBCConnection class 8
AcCollection class 14 AcOleContainerControl class 14
AcComponent class 5, 7 AcOleControl class 14
AcConditionalSection class 10 AcOracleConnection class 8
AcConnection class AcOrderedCollection class 14
overview 5, 8 AcPage class 11
subclassing 85 AcPageList class 6, 11, 73
AcControl class 6, 14 AcParallelReport class 10
accorvu.dll 487 AcPopupMenu class 14
AcCurrency class 314 AcProgressConnection class 8
AcCurrencyControl class 14 AcProgressSQL92Connection class 8
AcDataAdapter class 6, 9, 78 AcRecordBuffer class 80
AcDatabaseSource class 9 AcRectangleControl class 14
AcDataControl class 14 AcReport class
AcDataFilter class 6, 9 instantiating 66
AcDataFrame class 11 overview 6, 7
AcDataRow class 6 subclassing 239
AcDataSection class 10 XML-specific properties 231

508 Programming e.Repor ts

AcReportComponent class 6, 7, 68 AcReqHasDefaultValue function 346, 405
XML-specific properties 232 AcReqInfo function 459
AcReportController class 14 AcReqInitialize function 342, 351, 355, 405
AcReportSection class 10, 69 error checking with 350
AcReqAddToCache function 459 AcReqPrintReport function 348, 353, 356, 406
AcReqCloseFile function 344, 354, 376 AcReqReadFile function 344, 407
AcReqConnect function 342, 376 AcReqReportStatus function 350, 408
error checking with 350 error checking with 350
AcReqDisconnect function 342, 354, 377 AcReqSelectClient function 342, 409
error checking with 350 AcReqSetDefaultPrinter function 348, 410
AcReqDropFromCache function 459 error checking with 350
AcReqGenerateReport function 348, 349, 353, AcReqSetEUDTPath function 342, 355, 410
356, 377 AcReqSelectClient and 409
AcReqGetAdhoc function 345, 382 error checking with 350
AcReqGetAlias function 345, 382 AcReqSetPrinterCollate function 348, 411
AcReqGetCacheFile function 459 error checking with 350
AcReqGetDefaultValueCurrency AcReqSetPrinterColor function 348, 411
function 346, 383 error checking with 350
AcReqGetDefaultValueDate function 346, AcReqSetPrinterDuplex function 348, 350,
384 412
AcReqGetDefaultValueDouble function 346, AcReqSetPrinterFormName function 348,
385 350, 412
AcReqGetDefaultValueInteger function 346, AcReqSetPrinterName function 348, 353, 413
386 error checking with 350
AcReqGetDefaultValueStr function 346, 387 AcReqSetPrinterNumberCopies
AcReqGetDefaultValueString function 346, function 348, 350, 413
388 AcReqSetPrinterOrientation function 348,
AcReqGetError function 389 350, 413
AcReqGetErrorString function 391 AcReqSetPrinterPaperSize function 348, 414
AcReqGetFirstGroup function 345, 391 error checking with 350
AcReqGetFirstParameter function 345, 392 AcReqSetPrinterScale function 348, 417
AcReqGetHidden function 345, 393 error checking with 350
AcReqGetHideText function 345, 393 AcReqSetPrinterTray function 348, 417
AcReqGetNextGroup function 345, 394 error checking with 350
AcReqGetNextParameter function 345, 395 AcReqSetRequestPriority function 348, 418
AcReqGetParmType function 346, 396 error checking with 350
AcReqGetPrinterCapabilities function 459 AcReqSetScopedParameterName
AcReqGetReportVersion function 344, 396 function 345, 418
AcReqGetRequired function 345, 397 AcReqSetValueCurrency function 347, 419
AcReqGetType function 346, 398 AcReqSetValueDate function 347, 420
AcReqGetValueCurrency function 347, 399 AcReqSetValueDouble function 347, 421
AcReqGetValueDate function 347, 400 AcReqSetValueInteger function 347, 422
AcReqGetValueDouble function 347, 401 AcReqSetValueString function 347, 349, 422
AcReqGetValueInteger function 347, 401 AcReqUnInitialize function 342, 354, 356, 423
AcReqGetValueStr function 347, 402 error checking with 350
AcReqGetValueString function 347, 403 AcReqViewReport function 348, 356, 424
AcReqGetVersionNumber function 404 valid arguments for 344

Index 509
AcReqWriteFile function 344, 425 calling functions from ActiveX
acrq3041.dll 341 controls 481, 493
acrq4060.dll 339 class data types for 265
acrq5060.dll 339 cleanup code for 66, 463
acrs4060.dll 340 code elements 252–256
acrs5060.dll 340 code examples for 258, 358
AcSection class 6, 10 compared to Visual Basic 250
AcSequentialSection class 10 control structures 285
AcSimplePageList class 11, 73 creating source files for 281
AcSingleInputFilter class 10, 80 debugging code 116, 118
AcSingleList class 14 defining stored procedures with 192
AcSingleListIterator class 14 editing restrictions 55, 56, 60, 61
AcSQLQuerySource class 10, 80 editor for 48
AcSubPage class 11 extending functionality 280, 310
AcSummaryGraph class 14 instantiating classes with 18
AcSybaseConnection class 8 Java type conversions for 318, 319
AcSybaseDBLibConnection class 8 multiple method definitions in 32
AcTextControl class 14 naming conventions 257
AcTitleBodyPageList class 11, 73 optimizing code 267, 272
active connection 352 overview 250–251
Active Portal xxv private and public variables in 26
do_executereport.jsp JavaServer Page 217 programming conventions 251, 256–258
ActiveX API reference 491 selecting API for 337
ActiveX controls xxv simplifying programming tasks 280
adding 474, 483 standard data types for 265
developing applications with 482 startup code for 66, 463
embedding in dialogs 475 stopping debugging sessions for 125
error handling 481 support for OLE automation 304
files associated with 476 tracking methods calls for 128
implementing with Requester API 489 variable type mappings 198–199
installing 486 Actuate Desktop controls 483
overview 292, 327 Actuate Foundation Class Library xxv
programming tasks for 477 Actuate Foundation Class library
selection guidelines for 330 overview 4
ActiveX methods scoping conventions in 24
alphabetical reference 491 Actuate Foundation Classes
categorized 477 See also classes; specific class
ActiveX viewing window base classes described 5
changing views in 495 categorized 7
displaying reports in 476, 479, 503, 504 class-specific types 265–266
moving to specific page in 498, 499, 502 deriving classes from 20
resetting to first page 496 getting information about 48
scaling reports for 505 instantiating 4, 6, 24, 74
AcTopDownFlow class 11 overview 4
ActualPageNumber constant 137 predefined methods in 30
Actuate Basic xxv, xxix programming language for 18
breakpoints and 123 XML extensions 230
calling C functions 310, 313, 314 Actuate home page xxvii

510 Programming e.Repor ts

Actuate product suite xxiv AcWReqSetPrinterFormName function 348
Actuate product updates xxvii error checking with 350
Actuate SDK 337 AcWReqSetPrinterName function 453
Actuate technology xxi error checking with 350
Actuate Viewer. See Viewer AcWReqSetValueCurrency function 347, 453
AcVisualComponent class 6 AcWReqSetValueDate function 347, 454
AcWReqConnect function 342, 425 AcWReqSetValueDouble function 347, 455
error checking with 350 AcWReqSetValueInteger function 347, 456
AcWReqGenerateReport function 348, 426 AcWReqSetValueString function 347, 457
AcWReqGetAdhoc function 345 AcWReqViewReport function 348, 457
AcWReqGetAlias function 345, 430 AcWReqWriteFile function 344, 459
AcWReqGetDefaultValueCurrency acxcel.dll 487
function 346, 431 ad hoc parameters 106
AcWReqGetDefaultValueDate function 346, testing for 382, 430
432 ad hoc queries xxvi
AcWReqGetDefaultValueDouble adapters. See data adapters
function 346, 433 Add 197
AcWReqGetDefaultValueInteger Add Method dialog box 58
function 434 AddFrame method 73
AcWReqGetDefaultValueStr function 346, adding
435 balloon help 162–163
AcWReqGetDefaultValueString company names and logos 106
function 346, 436 components
AcWReqGetErrorString function 350, 381, in Design Editor 22
437 to report designs 251
AcWReqGetFirstGroup function 345, 437 context menus 159–162
AcWReqGetFirstParameter function 345, 438 context-sensitive help 163–165
AcWReqGetHidden function 345, 439 controls
AcWReqGetHideText function 345, 439 for stored procedures 176
AcWReqGetNextGroup function 345, 440 objects 36
AcWReqGetNextParameter function 345, 441 for Java applications 317
AcWReqGetParmType function 346, 442 for OLE containers 14
AcWReqGetRequired Function 442 from external applications 292, 296
AcWReqGetRequired function 345 OLE objects 296–299
AcWReqGetType function 346 page number controls 137
AcWReqGetValueCurrency function 347, 443 security IDs 134
AcWReqGetValueDate function 444 adding balloon help 165
AcWReqGetValueDouble function 347, 445 adding context menus 160, 161
AcWReqGetValueInteger function 347, 446 adding context-sensitive help 163
AcWReqGetValueStr function 347, 447 addition operator (+) 254
AcWReqGetValueString function 347, 448 AddMenuCommands method
AcWReqGetVersionNumber function 448 creating context menus 159, 160, 161
AcWReqHasDefaultValue function 346, 449 default action for 161
AcWReqPrintReport function 348, 450 implementing context-sensitive help 164
AcWReqReadFile function 344, 452 administrators 326
AcWReqSetEUDTPath function 342, 452 afc directory 487
error checking with 350 AFC. See Actuate Foundation Classes

Index 511
aggregate controls selection guidelines for 329–331, 337
retrieving content for 72 setting up client stations for 340, 341
AIX C++ compilers 338 uninstalling class libraries for 423
AIX servers 340 application servers xxiii
Alias keyword 313 applications
aliases 265 See also programs
getting parameter 382, 430 accessing external 292, 304
nonstandard names 313 adding ActiveX controls to 474, 483
user-defined types as 275 building
aligning with Requester API 350–357
browser code output 207 calling stored procedures from 188
AllocateCursor method 85, 189 closing 353
allocating database cursors 85, 189 customizing xxv, 327
alternate names. See aliases debugging tools for 116
AlternateText property deploying on Web 250
Actuate Viewer and 214 deploying to client/server 334
browser scripting controls and 205, 208 determining web context for 211
displaying 208 developing 251, 256
dynamically generating values for 210 with Actuate APIs 326, 329, 334, 464
PDF formats and 213 developing with ActiveX controls 482
setting in Factory 212 distributing 474
AltKey setting 158 e.reporting solutions for xxii, xxiii
ambiguous methods calls 41 embedding prebuilt functionality 474
ampersand (&) character in code 266 generating reports from 380, 428
analysis tools xxv, 327, 462 hanging 475
analyzing data xxvi including ActiveX controls with 486
ancestor classes. See super classes running Requester API 338, 339, 340
And operator 255 sample xxviii
ANSI character codes 269 search extensions for 327
ANSI strings 269 selecting clients 409
ANY_TP type 471 standard interfaces and 20
AnyClass type 36 support for third-party 462
assigning 34 testing 122
ANYCLASS_TP type 471 archive driver xxvi
apostrophe (’) in code 256 archiving tools xxvi
applets 202 arguments 283
application programming interfaces (APIs) See also parameters
See also specific Actuate API C functions and 311, 312, 313, 314
accessing 337 executable file as 352, 353, 358
choosing libraries for 338, 488 file names as 343
closing sessions for 353, 356 getting names 345
developing with xxvi passing variables as 284
error checking for 349–350 procedures and 283, 285
file naming conventions 339, 488 type restrictions for 312
initializing sessions 351, 355 arithmetic operators 254
overview 326–328 variants and 268
programming tasks for 341

512 Programming e.Repor ts

array types 263 B
ARRAY_TP type 471
arrays Back buttons 492, 493
adding multiple dimensions 264 Back method 478, 492
binary data and 269 back stack (web pages) 492, 493
converting Java 319 BackDisable event 479
debugging Java 321 BackDisable method 492
declaring 263–264 BackEnable event 479, 492
monitoring 126 background colors
naming 53 DHTML converter and 204
passing to C functions 315 BalloonHelp method 162
populating with different data types 263 BalloonHelp property 162
As Any keyword 312 BAnd operator 254
As keyword 266, 283 .BAS files. See source files
As Object keyword 317 base classes 4, 21
Asc function 269 Actuate-specific 4
ASCII characters 258 Basic string 368
assigning Basic. See Actuate Basic
data types to variables 53, 252, 266–267 batch mode 327, 349, 380, 429
methods to classes 58–59 bin directory 487
null values 43 binary data 269
objects to variables 42 binary files 106
strings to variables 268 binary string 368
values to parameters 347, 396, 398, 442 binary strings 269
values to variables 42, 43, 252 comparing 270
variables to classes 35 returning bytes in 269
as any class 36 BindColumn method 189
variables to objects 24 BindParameter method 86
variables to parameters 25, 28 bitwise And operator 254
variables to variables 37, 38 bitwise Or operator 254
assignment operator (=) 252 BLINK tag 223
assignment statements 252 boolean type 318
testing 449 Boolean values
asterisk (*) as text string 394, 440 Java objects and 318
asynchronous report generation 378, 381, performing calculations on 255
397, 427, 429 returning 254
at-sign (@) character in code 253, 267 BOr operator 254
attaching to databases. See connections borders
attributes 345 DHTML converter and 204
See also properties Netscape Navigator and 222
automating repetitive tasks 280, 304, 330 bounding rectangle 212, 222
AutoScrollbar setting 207 bounds (arrays) 263
Available Libraries option 261 Breakpoint icon 123
Axdesk.dll 487 breakpoints
Axview.dll 487 running to 123
setting 118, 119, 123

Index 513
BrioQuery 327, 462 building ActiveX sample application 482
browser code building context-sensitive help 163
adjusting scaling factor 212 building data streams 6, 76–82
aligning output for 207 building reports 4, 64
clipping output for 206–207, 213 report bursting techniques for 238, 239,
converting to PDF formats 213 240
creating output dynamically 214 starting Factory process for 66–67
debugging 208 with stored procedures 171, 176
determining execution context 211 built-in classes
displaying 208, 221 See also Actuate Foundation Classes
generating dynamically 210–213 built-in functions 250, 285
including in report designs 205, 209 See also functions; methods
supported formats 202 built-in methods 30, 251
browser code functions 202, 211 See also methods
browser scripting controls BundleReportInstance method 480, 493
adding 205, 209, 210, 214 bundling report files 493
to libraries 210, 215 Burst1.rod 240, 241
adjusting size 212 Burst2.rod 240, 244
creating HTML forms with 210 bursting 238
hiding 215 examples 240
nesting in designs 214, 215 button controls 483
overview 202 byte arrays 269
referencing global browser code in 209 byte type 318
browser source viewer 208 BYTE_TP type 471
BrowserClipping property 206, 207, 222 bytes 269
BrowserCode method ByVal keyword
overriding 210, 211, 212 arrays and 315
setting in Factory 212 C functions and 312, 315
BrowserCode property
checking values of 208 C
setting 205 C functions
BSTR strings 337, 368 aliasing names for 313
BSTR, defined 368 argument types for 312, 313
buffers 10 calling 310, 314
Build and Run command 65, 119 declaring 311–314
Build method including in programs 310, 311
AcReport 67 overview 310
AcReportComponent 68 passing conventions for 312, 315–316
AcReportSection 69 pointers to 276
build number 404, 449 renaming 313
BuildFromRow method return values for 311
AcControl 72 reversing array dimensions 315
AcFrame 71 type conversions 313–314, 316
AcGroupSection 71 C++ compilers 338
AcReportComponent 68 C++ function calls 326, 327
example for report bursting 242 C++ sample application 351
overriding 210, 212, 213

514 Programming e.Repor ts

C/C++ programs default printers 348
adding ActiveX controls 475 OLE objects 294, 295, 299–300, 302
creating Requester interface in 327 printers 413, 453
displaying parameters in 371 properties 110–113
generating and displaying reports 368– report designs at runtime 104
374 report parameters 336
selecting Actuate API for 337 search extension default directories 463
cache 409 values 284
calculated fields variables 55
getting values for 90–91 web page scaling factor 212
calculations 260 Channel variable 95
cumulative totals 262 char type 318
powers and roots in 254 character arrays 269
procedures performing 252, 283 character codes 269
temporary 262 character conversions 253
calendar 273, 294 character strings 269
Call keyword 285 See also strings
call stack 128 characters in names 258, 313
Call Stack command 129 charts. See graphs
callable methods 31 CheckMessage interface 475
CallBasicFunction method 481, 493 Chr function 269
calling CInt function 277
functions 202, 283, 285 class data types 265–266
from ActiveX controls 480, 493 class IDs 44
from DLLs 310, 314 class libraries
restrictions for 459 See also Actuate Foundation Class library
search extension API and 465 closing 366, 423
methods 40, 41 uninstalling 423
procedures 281, 284 class names
cancel buttons 503, 504 in method calls 40
canceling report generation 494 returning 44
CancelReport method 480, 494 scoping considerations and 22
CanRunReport method 480, 494 viewing 49
CanSeek method 79 Class page (Component Editor) 49
capitalization in code 257 class protocol 4
CascadeSecurity property 153 class scope 260, 280
case default 22
code elements 257 Class statement 18
case sensitivity 257 Class Variable dialog box 53
catalogs xxiii Class Variable page 140
CCur function 277 class variables 24–29
CDate function 275, 277 declaring 263
CDbl function 277 types supported 24
changes, undoing in Component Editor 56 classes
changing See also Actuate Foundation Classes
CLASSPATH variable 317 assigning methods to 58–59
data at runtime 108–113 assigning variables to 35, 53, 260

Index 515
classes (continued) deploying to 334
checking object status within 44 developing 335, 336
customizing 35 displaying reports for 501, 502, 503, 504
declaring 18–20 installing ActiveX controls for 488
scope and 21 installing custom search extensions
variables private to 26 for 466
defined 18 moving through reports 478
defining characteristics of 6 running from Requester API 340, 341
defining for Java 317 running on different platforms 330
defining structure of 6 running reports for 353
deriving new 4, 20 selecting clients for 409
determining scope 22 setting up accounts for 352
displaying list of 35 client code 409
displaying variables in 50 Client Integration Technology xxv
extending functionality of 4, 6, 30 client-side reporting 409
getting information about 48, 49 Clip property 207
inspecting 48–49 clipping
instantiating 74–75 browser output 206, 213
making private 49 frames on report pages 73
methods declared in 30 ClipToControlSize setting 207
naming 40, 257 CLng function 277
nesting 21, 23 clock 273
overriding methods and 57 Close function 463, 468
overview 4, 17, 18 Close method 306
referencing 20, 22 CloseReportExecutable method 480, 495
relationships described 20 CloseReportInstance method 478, 484, 495
scope-resolution operator for 22 closing
subprocedures in 282 API sessions 353, 356
testing status 44 class libraries 366, 423
types described 4, 6 connections 68, 70, 353
user-defined types as 276 data adapters 78, 81
viewing properties 51 data streams 68, 70
visibility 20 external applications 306
classifying data 264 input data sources 80
CLASSPATH variable 317 OLE Automation objects 306
cleanup code report files 376
API functions for 342, 353 reports 477, 484, 495
Factory services 66 search definition files 468
search extensions 463 clusters xxv
cleanup functions 310 code
clearing See also Actuate Basic
breakpoints 123 accessing Java objects in 318
programs from memory 125 accessing variables in 26
status stack 503 adding breakpoints 123
client applications 329 adding comments 256
closing 353 conventions for 256–258
creating 351, 354 debugging 115

516 Programming e.Repor ts

code (continued) adding to source code 256
displaying browser 208 viewing 49
displaying specific methods in 128 commonly-used commands 159
editing 48 company names and logos 106
editing restrictions 55, 56, 60, 61 Compare method 93
examples for 258 comparison operators
extending functionality 310 overview 254
getting values for 31 precedence for 256
handling invalid methods in 58 comparisons
implicit declarations and 260 conditions as 286
indenting 257 expressions 254
language elements in 252–256 object reference variables 45, 255
locating errors in 117 strings 255, 270
programming conventions for 251 compilation errors 116
resuming execution of 124 compiled libraries 488, 489
running 119 compilers 32, 337
setting watches 127 compiling search extensions 466
startup/cleanup completion notices 66
Factory services 66 component class 5
Requester API 342, 353 Component Editor 34
search extension API 463 accessing control values 110, 111
stepping through 123, 125 adding company names and logos 107
stopping execution of 125 adding variables 24, 25
viewing comments in 49 connecting to flat files 95
writing custom browser 209, 210 creating computed variables 90
COleDateTime function 421, 455 creating methods 58–59
collating 411 creating variables 53–55
collection classes 14 debugging with 118
collections 15 deleting methods 61
colon (:) as separation character 257 deleting variables 56
color printing 411 displaying methods 60
colors dynamically embedding images 106
DHTML converter and 204 editing methods 60
numbers representing 265 editing variables 55
setting as transparent 215 filtering methods 52, 61
column delimiters (search extensions) 468 filtering variables 50
column names implementing browser scripting 205, 209
duplicate in stored procedures 175 inspecting classes 48–49
in search extensions 469 inspecting methods 51–52
columns 81 inspecting variables 50–51
binding to data rows 189 interface described 48
generating values at runtime 104 overriding methods 56–57
getting from stored procedures 194 overview 47
reading values 82 properties in 74
setting search extension data types for 472 running 49
specifying for stored procedures 176 setting properties 26
comments xxxiv undoing changes 56

Index 517
Component Gallery (Visual C++) 475 customizing 83, 85
Component Properties command 49 establishing report server 334, 351
component references (defined) 68 failing 84
component relationship map 66 flat files 95
components generic 5
adding handling multiple 84
in Design Editor 22 implementing programmatically 478
to report designs 251 implementing through API functions 376,
appearing in structure pane 5 425, 495
creating 68 input data sources and 80
at runtime 104–106 instantiating 8, 69, 83
customizing 4 local reporting and 354
instantiating 75, 104 multiple requests and 357
referencing 68, 74, 78 precedence 84
returning references for 112 relationships for 85
Components command 483 sharing 83
compressed images 301 SQL databases and 84
computed columns ConnectToServer method 478, 495
getting values for 90–91 Const statement 267
concatenation operator (&) 256 constants 253, 258
concrete classes 6 declaring 267
conditional expressions 382, 430 default values as 383
conditional filters 91, 92 enumerations and 265
conditional statements type definitions and 265
control structures as 286 constructs 257
setting at runtime 28 container applications
conditionally instantiating components 75 See also OLE applications
conditions accessing data in 294
applying to properties 108, 110 accessing OLE objects in 304
control structures and 286 defined 292
instantiating components with 104 container objects
configurations 326 adding 296, 297, 298
data streams 76 creating content for 68
local 336 embedding objects in 5
printers 348 instantiating contents 75
Requester API and client-server 335 monitoring contents 126
conjunction 255 containers
connection classes 5, 8 frames as 12
connection components reports as 7
adding 85 content management systems xxiii
placing in data streams 83, 84 content structure (Factory) 67
placing in sections 83, 84 content-creation protocol (Factory) 67–72
connection handles 376, 426 Contents buttons 485
connections 83–86 Contents window 475
API applications and 334 opening 485, 506
as transient objects 45 Contents_Click event 485
closing 68, 70, 353 context block (scripting control) 203, 205

518 Programming e.Repor ts

context menus 14 strings to currency 384, 399, 432, 444
adding items 160 unintended 268
creating 159–162 variants to dates 275
customizing 161 XML to DHTML formats 228, 230, 234
displaying 157, 161 ConvertBFileToString method 106
context-sensitive help xxxii, 163–165 ConvertStringToBFile method 107
Continue command 124 Copy Link command 160
Continue icon 124 copying
control buttons 483 dynamic link libraries 340
control classes 6, 13, 14 executable files 341
control structures 250 functions 360
exiting 287 hyperlinks 160
overview 285 strings from Java strings 319
control window. See ActiveX viewing copyright information 492
window CorVu modules 327, 462
ControlKey setting 158 counter variables 272
controlling program execution 123 counters 24, 45, 287
controls 156 CPointer data type 314, 316
accessing values 110, 110–113 assigning values 276
adding declaring 265
for stored procedures 176 stored procedures and 194, 195
adding to frames 111 CPOINTER_TP type 471
changing properties for 110 CreateJavaObject function 317
changing values 108 creating
customizing 14, 108 applications 350, 354
default scope for 22 balloon help 162–163
displaying 214 browser-specific menus 215, 218
instantiating 6, 14 components 68
naming 23 at runtime 104–106
nesting 23 context menus 159–162
overview 327 context-sensitive help 163–165
providing help with 162 data rows 6, 81–82
retrieving content for 71, 72 data sources 80, 81, 188
setting conditional properties for 108 dynamic hyperlinks 358–360
stacking 214 HTML forms 202, 210, 222
conversions 267 Java objects 317
binary to strings 106 labels 36, 38
C data types 313–314 methods 58–59
C functions 316 multi-table reports 99, 101
data types 253, 277 objects 34–37
inches to millimeters 416 parameter values files 425, 459
Java arrays 319 queries 81, 86
Java strings 319 reports 251
Java types 318–320 report-specific online help xxxiv
numbers to characters 253 source files 281
numbers to dates 275 user-defined methods 251
numbers to strings 270 variables 53–55, 261
strings to binary 107 creating balloon help 165

Index 519
creating context menus 160, 161 opening 80
creating context-sensitive help 163 custom browser code
creating queries adjusting scaling factor 212
for report bursting 242 aligning output for 207
creating reports clipping output for 206–207, 213
report bursting techniques for 238, 239, converting to PDF formats 213
240 creating output dynamically 214
with stored procedures 171 debugging 208
creating stored procedures 171–174 determining execution context 211
for Oracle8 data sources 182–188 displaying 208, 221
criteria. See parameters generating dynamically 210–213
cross-platform reporting xxiv including in report designs 205, 209
crosstabs 4 supported formats 202
CSng function 277 Custom Browser Code Editor 209, 210
CSS attributes 207, 222 custom classes 35
CStr function 277 custom data sources
CtrlKey Bor AltKey setting 158 creating 80, 81
cumulative totals 262 flat files as 94, 95, 96
currency generating computed columns from 90
converting strings to 384, 399, 432, 444 custom data streams 90–103
getting as current value 399, 443 applying filters to 91–94
getting as default 383, 431 creating 90
setting as default 420, 454 custom methods. See user-defined methods
currency controls 14, 272 custom Requester interface 383, 431
Currency data type custom search extensions 466
assigning values 272, 273 CustomDHTMLFooter method
C functions and 313 overriding 216
converting to 277 CustomDHTMLFooter property
declaring 267 restrictions for 222
described 265 setting 210
returning as current 399, 443 CustomDHTMLHeader method
returning as default 383, 431 overriding 216
specifying parameters as 419, 453 CustomDHTMLHeader property
currency variables 272 restrictions for 222
CURRENCY_TP type 471 setting 210
current date 274 customer profiles xxii
current release xxi Customer Support xxviii
current scaling factor 212 customizing
current value applications xxv, 327
defined 399, 443 components 4
getting 347 connections 83, 84
testing for 396, 398, 442 controls 14, 108
CurrentPage method 478, 496 data filters 81, 92
cursor variables 194, 195 objects 37
cursors (SQL) reports xxv, 31, 89
allocating 85, 189 Requester 366–368, 392, 437
instantiating 9, 85 CVar function 277

520 Programming e.Repor ts

D retrieving data from 6
sorting with 93
data data controls 13
accessing xxiii data extraction 462, 478
from external applications 81, 292, 304 data filter classes 6, 80
in input data sources 79 data filters 80–81
in OLE objects 294, 295 applying to custom data streams 91–94
in SQL tables 85 base class for 9
methods specific to 31 connecting to data streams with 76, 78
analyzing xxvi creating select 92–93
binary strings as 269 creating sort 93–94
changing at runtime 108–113 customizing 81, 92
classifying 264 defined 76
collecting 6 instantiating 6, 10
filtering 80, 91, 98 nonstandard 90
formatting for XML reports 226 parameters as 28
getting values at runtime 28 processing rows in any order 80
grouping 6, 70 specifying multiple data sources for 98–
maintaining in multiple sources 295 103
managing in data streams 10 data integrity xxiv
processing 6, 9 data row class 6
retrieving 79, 80, 81, 82 data rows 9
from data adapters 6, 78 adding to group sections 71
from data streams 76 binding columns to 189
from external data sources 6 creating 6, 81–82
from flat files 94 defining characteristics of 6
from multiple sources 98–103 filtering out selected 91–93
from nonstandard sources 90 getting from flat files 96
from text files 90 instantiating 6, 81
retrieving from stored procedures 176–177 processing in any order 80
sharing 292, 304 retrieving 6, 78, 80, 81
sorting 70, 93 from data streams 69
storing values 39 from nonstandard data sources 90
methods and 29 from stored procedures 189
variables and 113 with database cursors 85
tracking in multiple sources 295 with filters 91
user-defined values as 275 returning search extension 470
variants as 267 sorting 70, 93
data adapters 79 tracking position 85
base class for 9 data sets 188
closing 78, 81 data sorter 10
connections in 83 data source class 6
filtering with 92 data sources
forming data streams with 78 accessing data in 79
implementing 80 base class for 9
instantiating 78, 81 building data streams with 76, 78
opening 78, 81 creating 80, 81, 188

Index 521
data sources (continued) mixing in expressions 253
customizing 80, 81 monitoring 126
defined 76 passing multiple 312
external applications as 292, 304 program-specific 265
filtering multiple 98–103 returning 253
flat files as 94 setting as default 347
implementing data adapters for 80 setting search extension 471
instantiating external 6 stored procedures and 179, 198
maintaining data in multiple 295 variants and 267
nonstandard 90 database connection classes 5
overview 80 database cursors
placing connections in 85 allocating 85, 189
retrieving data from 81 instantiating 9, 85
tracking data in multiple 295 database example file
data stream classes 9 for Oracle databases 184
data stream configurations 76 database schema
data streams verifying stored procedures 170
as transient objects 45 databases
building 6, 76–82 accessing
closing 68, 70 for stored procedures 173
connecting to 69, 83 as input sources 76
connection precedence in 84 base class for 9
customizing 90–103 calling stored procedures in 188
getting data rows from 69 connecting to 5, 83–86
instantiating 69 e.reporting solutions for xxii, xxiii
managing data in 10 flat files as 80, 94
placing connection components in 83, 84 frequent operations in 280
reusing 83 improving performance 168
with multiple data adapters 78 interfaces for 5
data type mappings 199 SQL support for 84
data types 264–265 DataInputFile variable 95
See also specific type dataTypes array 472
assigning to parameters 347 DataValue variable 108
assigning to variables 53, 252, 266–267 date controls 14
C functions and 312, 315–316 Date data type
type conversions for 313–314 assigning values 273
class specific 265–267 C functions and 316
constants and 267 converting to 277
conversion functions for 277 described 265
converting Java 318–320 returning as current 400, 444
converting to common type 253 returning as default 384, 432
creating user-defined 275–276 specifying parameters as 420, 454
declaring in procedures 283, 284 date expressions 254
getting as parameter defaults 346 Date function 274
getting report parameter 396, 398, 442 date functions 274
getting specified as current 347 date variables 273
mismatched 268 date/time literals 273, 274

522 Programming e.Repor ts

dates global variables 261
arithmetic operators and 254 instance variables 24
assigning values 273 local variables 262
expressed as C++ doubles 385, 400, 421, nesting 20
433, 445, 455 object reference variables 34–36
formatting 274–275 private variables 26
getting as current value 400, 444 procedures 282
getting as default 384, 432 public variables 26
getting current 274 static variables 24
setting as default 420, 455 strings 268
setting from C++ 368 subprocedures 282
valid 265, 274 type restrictions 312
DateSerial function 274 user-defined types 275
Day function 274 variables 260–263
DB2 database connections 84 as specific type 266
debug options 122 C++ sample code for 351
debugging type-declaration characters and 266
access control lists 120 user-defined types and 276
browser code 208 declarations section (source code) 261
Java objects 321 Declare statement
methods 118, 128 Alias keyword 313
overview 116 As Any keyword 312
reports with page security 120 ByVal keyword 312, 315
with page level security 139 C functions in 311, 312, 313
debugging sessions Null keyword 315
adding breakpoints 123 specifying DLLs in 360
adding watches 127 DEF files. See search definition files
controlling program execution in 123 Default Action command 160, 161
monitoring values 125 default mouse actions 157
saving parameters for 122 default paths 260
starting 118 default printers 353
stepping through code 123, 125 changing 348, 413, 453
stopping 125 specifying 410
tracing object reference variables 126 default scope 22, 23, 24
viewing stack 128 default values
debugging tools 116 Currency data type as 383, 431
debugging window 117 Date data type as 384, 432
DebugOption property 208 defined 431
decimals 272 Double data type as 385, 433
declarations getting 346
arrays 263–264 Integer data type as 386, 434
C functions 311–314 setting 347
class 18–20 setting report parameter 96
constants 267 String data type as 387, 388, 435, 436
functions 282 testing for 396, 398, 405, 442, 449
in Visual Basic forms 361 defaults 37
global procedures 281 DefineProcedureInputParameter method 189

Index 523
DefineProcedureOutputParameter creating with Design Editor 18, 74
method 189, 198 multiple data sources and 99, 102
DELETE queries 86 stacking controls in 214
deleting Desktop ActiveX controls
methods 61 See also ActiveX controls
references to obsolete properties 117 accessing Actuate Basic functions
temporary files 107 from 481
variables 56 adding 474
delimiters (search extensions) 468 canceling report generation from 494
deployment xxiii, xxvii, 250 closing report executables from 495
supported environments for 338 methods calls for 491
derived classes opening report executables 500
creating 20 overview 327, 474
restrictions for 4 running reports from 479, 494, 503, 504
testing for 44 Visual Basic example for 482
descendant classes. See subclasses Desktop control window 484, 485
Design Editor 104 Desktop controls 483
adding components with 22 detail graphs 14
creating multiple input filters 99 detail reports 238
creating reports 251 associating with master reports 243, 245
creating select filters 92 creating from group sections 244, 245
creating sort filters 93 examples for 240, 241, 242, 243
designing reports with 18, 74 naming 243
displaying group section keys 109 Developer Workbench
editing OLE objects 299, 300 setting XML properties 230
getting data from flat files 94 developers 250, 256, 326
inserting OLE custom controls 301 developing applications
inserting OLE objects 297, 298 for Windows operating systems 474
specifying data in 108 with ActiveX controls 477, 482
subclassing reports 239 with Requester API 350–357
Design Emporium product catalog 234 with search extension API 464–466
Design Properties command 120 developing reports xxv, xxxiv
Design Properties dialog development cycles 329
setting debug options 122 development languages xxv
simulating page security viewing 120 development tools xxv, xxvi, 338
design tools xxiv, 251 DHTML converter
designing e.Spreadsheet reports xxv, xxvii generating HTML code 205
designing reports xxiv processing scripting controls 202, 209
testing design 138, 141 properties ignored by 207
with page level security 135–140, 149 scaling controls 212
with stored procedures 171, 176 DHTML forms
designs 251 creating 215
adding browser scripting 205, 209 submitting requests for 217
adding objects from external DHTML reports
applications 292 See also web pages
creating at runtime 104–107 converting to PDF formats 213
creating for flat file data sources 94, 97 debugging browser code for 208

524 Programming e.Repor ts

DHTML reports (continued) predefined classes 35
displaying xxiii properties 51
displaying controls in 214 report parameters 394, 440
generating 64, 209, 228 reports xxvii, 155, 424, 457
special characters in 202, 204 ActiveX controls and 474, 485
viewing 202 API functions for 348
DHTMLForm scripting control 215–217 in C++ applications 368
subclassing 217 in Encyclopedia volumes 477
DHTMLMenuControl scripting control 215, in Visual Basic forms 362, 366
218–222 in web pages 64, 202
subclassing 220 locally 336, 349, 356
dialog boxes Requester API and 335, 336
embedding ActiveX controls in 475 with Actuate Viewer 214, 341, 411, 453,
prompting for parameters in 366 466
setting language for 499 with PDF converter 213–214
Dim statement 260 with security restrictions 134
creating OLE Automation objects 305 variables 50, 125
creating text strings 268 web pages 212
defining instance variables 24 displays 6, 265
defining local variables 262 distributing applications 474
defining object reference variables 34, 317 DIV tags 205, 222
dynamic arrays and 264 division 254
procedures and 262 DLLs
specifying data types 266 ActiveX controls and 487
dimensions. See arrays calling C functions from 310, 314
directories 409 copying 340
ActiveX installations and 486 initializing 405
default for search extensions 463 Java requirements and 316
directory names 409 procedures in 315
See also paths relative paths and 360
disconnecting from databases 84 search extension 466
disconnecting from reporting servers 353, selecting for ActiveX API files 488
377 selecting for Requester API files 338–340
disjunction 255 selecting for Windows environments 339
display layouts 505 specifying 312, 360
Display Sample Data option 205 updating 338, 488
displaying Do...Loop control structure 286
classes 49 do_executereport.jsp
comments 49 Active Portal JavaServer Page 217
context menus 157, 161 document files
controls 214 ActiveX controls and 476
custom browser code 208, 221 bundling with report executables 493
DHTML reports xxiii, 202 described 343
error messages 117 printing from Requester API 406, 450
images 107 viewing 424, 457
methods 51, 60, 111, 128 document type definitions (DTDs) 226
online documentation xxxii

Index 525
documentation xxix debugging tools for 116
accessing xxxii defaults 37
overview xxvii developing for 334
syntax conventions for xxxv editing variables 55
typographical conventions for xxxv extending functionality of 250
dollar sign ($) character in code 267, 273 launching local copy of 336
dot notation 39, 40, 276 local reporting and 336, 355
Double data type programming with 18
assigning values 272, 273 Requester programming examples for 337
C functions and 313, 316 resolving ambiguous method calls 41
converting to 277 selecting client products for 409
declaring 267 transient objects and 45
described 265 e.Report Engine xxvii
Java objects and 318 e.Report Option xxvi
returning as current 401, 445 e.reporting solutions xxi, xxiii
returning as default 385, 433 e.reports 250
specifying parameters as 421, 455 See also reports
double quotation marks in strings 268 e.Spreadsheet Designer xxv, xxvi
double type 318 e.Spreadsheet Engine xxvii
DOUBLE_TP type 471 e.Spreadsheet Option xxvi
double-precision floating-point numbers. See e.Spreadsheet reports
Double data type designing xxv, xxvii
drawing tools 14 generating xxvi
Drawing/Graphics palette 202 E_JAVAEXCEPTIONOCCURRED error 320
DROP TABLE queries 86 E_JVMCLASSNOTFOUND error 320
drop-down menus. See menus E_JVMCLASSPATHNOTFOUND error 320
DT_TIME_TP type 471 E_JVMCREATEJVMFAILED error 320
duplex modes 412 E_JVMCREATEOBJECTFAILED error 320
duplexing 412 E_JVMINVALIDJAVAHANDLE error 320
duplicate names 41, 59 E_JVMMETHODFIELDACCESSFAILED
dynamic arrays 264 error 320
dynamic content delivery 251 E_JVMTYPECONVERSIONFAILED
Dynamic HTML. See DHTML error 320
dynamic hyperlinks editing
creating 358–360 data in OLE objects 294, 295, 299–300
dynamic-link libraries. See DLLs methods 60–61
source code 48
E undoing changes 56
e.Analysis Option xxvi variables 55
e.Business applications xxiii Editor. See Component Editor
e.Report Designer xxiv electronic catalogs xxiii
developing for 334 elements. See arrays
launching local copy of 336 ellipse control 14
local reporting and 336, 355 Ellipsis property 207
selecting client products for 409 Else keyword 286
e.Report Designer Professional xxv ElseIf keyword 286
custom browser code in 202 embedded quotation marks 268, 272

526 Programming e.Repor ts

embedding displaying 117
image controls 106–107, 295 getting 391, 437, 496
OLE objects 292–299 JavaScript 208
guidelines 296 setting language for 499
linking vs. 294 error-handling routines 408
empty methods 4, 20 errors
empty strings 392, 437, 497 ActiveX controls 481
empty variables 44 checking for 349–350, 389, 391, 437
EMPTY_TP type 471 in browser scripting controls 208
Encyclopedia fixing 116
See also volumes Java objects and 317, 320
managing volumes 326 locating in code 117
Encyclopedia volume printing 407, 451
accessing items 335, 351 types described 117
viewing reports in 477 escape characters 202, 204
Encyclopedia volume. See Encyclopedia; Essential Property option 55
volumes Essential Property setting 26
Encyclopedia volumes Eudt directory 409
generating documents for xxv events 31
End User Desktop xxiv, 331, 474 ActiveX controls 479, 484
canceling report generation from 494 default mouse actions 157
displaying reports from 411, 453 mouse 156, 157
printing from 336, 406, 450 report viewing 156
running 378, 427 report-viewing 156–157
running remotely 410, 453 search extensions 468
selecting client products for 409 examining variables 125
setting location of 410, 452 example database files
viewing reports 424, 458 Oracle8 stored procedures 184
enhancements 338, 488 Example folder xxviii
enterprise reporting xxii, xxiii example reports
enumerations (enums) 265 report bursting techniques 240
returning data types as 398 examples 258
envelopes 415, 417 accessing stored procedures 193, 195
environment variables creating browser-specific libraries 215
Requester API and 341 creating computed columns 90
UNIX platforms 340 creating menu items 161
equal to operator (=) 254, 255 embedding ActiveX controls in
equivalence 255 dialogs 475
Eqv operator 255 filtering in custom data streams 91
Erd directory 409 filtering nonstandard data sources 92
Erdpro directory 409 mouse event actions 158
Err() function 320 Requester API and Actuate Basic 358–360
erroneous values 117 Requester API and C++ 368–374
error codes Requester API and Visual Basic 360–368
getting 349, 389 Requester API programming 337
report generation 381, 429 setting executable file names 349
error messages sorting data 94
API function calls 389, 494

Index 527
Excel applications 299, 304, 462 on report server 500
changing 305 Requester API and 335, 336
creating objects for 305 Visual Basic sample code for 356
searching 327 executing stored procedures 189
support for 292 Exit buttons 484
Excel spreadsheets Exit Do statement 287
developing for xxv, xxvii Exit For statement 287
generating xxvi Exit Function statement 287
exceptions 320 Exit Sub statement 287
exclamation point (!) in code 267 Exit_Click event 484
exclusion 255 explicit declarations 260
executable files 488, 489 exponentiation 254, 273
ActiveX controls and 476 expressions
as report generation argument 352, 353, arithmetic operators and 254
358 assignment statements and 252
bundling with report documents 493 calling procedures from 284, 285
closing 376, 495 comparing 254
copying to client stations 341 conditional statements and 286
described 343 data type functions in 277
generating reports from 377, 408, 426, 452, embedding quotation marks in 272
503, 504 literal strings in 268
getting parameter groups in 391, 394, 437, logical operators and 255
440 operator precedence in 256
getting parameter values in 346 overview 253
getting specific parameter in 392, 395, 438, external applications xxiv
441 accessing data in 294
naming 352, 355 accessing objects in 292, 304
opening 407, 452, 485, 500 closing 306
running 64, 349 opening 305
Execute method external data sources 6, 81
SQL statements 86 external functions
stored procedures 189 calling 310, 314
executing programs 123 copying 360
line by line 123 external hyperlinks
executing queries 86 event handling for 479
executing reports external objects 321
API functions for 348 external security information 134
based on specified parameters 342 external source code files 202
batch mode for 327, 349, 380, 429 Externally Defined Data Type option 54
C++ sample code for 353, 370 extracting data 462, 478
default values and 383, 431 extracting days from dates 274
from ActiveX controls 479, 485, 503, 504 extracting report executables 500
from End User Desktop 410, 453
from parameter values files 352, 353, 355, F
356 F1 key xxxii
locally 336, 349 Factory method 65
sample application for 354

528 Programming e.Repor ts

Factory service overwriting generated report 378, 427
building data streams 76–82 referencing in API function calls 343
building reports 66–67 report described 342
content creation protocol for 67–72 running executable 64, 349
data row processing for 81 server connections and 477
defined 64 specifying local names for 476
establishing database connections 83–86 specifying output 352, 355
instantiating classes 74–75 storing images in temporary 107
overview 64–65 fill patterns 207
page-creation process 72–74 FillPattern property 207
processing report content and creation 65 filter options (Method Filtering) 52, 60, 61
starting 65, 66 filter options (Variables Filtering) 50
failures 496 filtering data 80, 91, 98
fanfold paper settings 415 filters 80–81
Fetch method applying to custom data streams 91–94
AcDataAdapter 78 applying to methods 52, 61
AcDataFilter 81 applying to variables 50
AcDataSource 80 connecting to data streams with 76, 78
overriding creating merge 101
for data filters 91, 92 creating multiple input 99
for dynamically embedded images 106 creating select data 92–93
for flat file access 97 creating sort data 93–94
for multiple data sources 99, 100, 102 creating union 99
for stored procedures 189, 196 customizing 92
to populate data rows 90 data-specific 76
fields 81 instantiating 10
See also columns nonstandard 90
accessing in Java objects 317, 318 parameters as 28
file cache 409 processing data in any order 80
file names 260, 380, 429 specifying multiple data sources for 98–
as arguments 343 103
iServer files 476 FindContentByClass method 112
specifying 349, 476 Finish method
file naming conventions 339, 488 AcControl 72
file numbers 379, 408 AcDataAdapter 78
files AcDataFilter 81
accessing data in flat 94–98 AcDataSource 80
accessing external 292 AcFrame 71
accessing on servers 376, 426 AcGroupSection 71
bundling report 493 AcReportComponent 68
closing 376 AcReportSection 70
copying executable 341 overriding
deleting temporary 107 for flat file access 97
generating multiple report 238 for generating reports 66
generating report 342 for multiple data sources 100
logging report generation to 66 for runtime properties 108
opening 407, 452, 470, 485, 500 to customize data streams 90

Index 529
FinishFlow event 73 adding OLE custom controls 300
FinishPage event 73 adding OLE objects 296, 297, 298
FirstPage method 478, 496 adding to reports 12
fixed-point numbers 272, 273 building 10
fixed-size arrays 264 building dynamically 104, 105
flat file databases creating content for 6
connecting to 95 defining characteristics of 6
getting data from 80, 94–98 determining page styles for 73
float type 318 generating content for 68, 71, 72
floating-point division 254 instantiating 71
floating-point numbers placing in flows 6
data as 420, 455 placing on pages 73
data types for 272, 273 freeing resources 423
date variables as 273 Function statement
getting as current value 401, 445 C functions in 311
getting as default 385, 434 defining procedures from 281, 282
mathematical operations on 254 functions 250
setting as default 421, 456 See also methods
flow (page layouts) accessing external 310
placing frames in 6 ActiveX alphabetical reference 491
report viewing events and 156 calling 202, 283, 285
flow class 6 from ActiveX controls 480, 493
fonts from DLLs 310, 314
applying to web pages 222 restrictions for 459
footers search extension API and 465
building 74 copying 360
generating content for 72 CPointer data types and 276
For...Next control structures creating mapping 154
counter variables in 272 date/time specific 274
declaring 287 declaring 282
FORM tag 210, 216 in Visual Basic forms 361
Format function 270 error codes for API 389
formatting error handling for 349–350
dates 274–275 exiting 287
displays 265 instantiating classes and 18
strings 270 referencing report files in 343
formatting data Requester API categorized 341–350
for XML reports 226 Requester API reference 375
Formula One product suite xxvii returning object information 44
formulas. See expressions search extension API categorized 462–464
forwarding messages 475 search extension API reference 467
foundation classes. See Actuate Foundation specifying multiple options for 378, 427
Classes stored procedures 182, 184
fractions 272, 273 subprocedures vs. 283
frames 156 type conversions 277
accessing control values in different 113 undocumented 459
adding browser scripting controls 209 fundamental data types. See data types
adding controls 111

530 Programming e.Repor ts

G GetUserACL method 140, 152
GetUserAgentString function 211
GenerateXML method 230, 233 GetXMLText method 233
generating global custom browser code 209
reports xxv global procedures 281
generating HTML tags 205 global scope
generating report files 342 as default 24
report bursting techniques for 238 procedures and 280
generating reports variables and 260
API functions for 377, 426 Global statement 34, 260, 261
canceling requests for 494 global variables
content creation protocol for 67–72 caution for using 113, 261
for DHTML pages 228 creating 261
from ActiveX controls 494 declaring 260, 261
from report files 408, 452 initializing 66, 262
from Visual Basic forms 362, 365 monitoring 125
from Visual C++ forms 369, 370 overview 260
getting status reports for 408 storing values in 113
initializing global variables for 66 watching 127
overview 63, 64 GlobalDHTMLCode property
prioritizing requests for 418 restrictions for 223
Requester API and 334 setting 209
sending completion notices for 66 GoToPage method 479, 498
setting parameters and 397, 443 GrantExp property 134, 137
generation options 378, 379, 427, 428 graph controls 13
generic connections 5 graphical objects 13
GetAppContext function 211 graphical user interfaces 329, 494
GetClassID method 44 graphics controls (third-party) 488
GetClassName method 44 graphics files
GetColumnDelimiter function 464, 468 See also images
GetControlValue method 110 accessing 292
GetJavaException method 320 embedding in reports 106, 295
GetKeyValue method 109 linking to reports 294
GetLastError method 478, 496 graphs 156
GetMostRecentListCount method 478, 497 adding from external applications 292
GetMostRecentListItemAt method 479, 497 instantiating 14
GetName function 463, 469 greater than operator (>) 255
GetOutputParameter method 189, 195 greater than or equal to operator (>=) 255
GetParameters function 463, 469 group boundaries 244
GetPosition method 79 group sections
GetProcedureStatus method 189, 195 creating content for 70
GetReportContext function 211 creating subreports with 244, 245
GetReportScalingFactor function 211, 212 displaying keys for 108
GetStatusCount method 497 initializing 71
GetStatusMessageAt method 498 grouping
GetText method 140 data 6, 70
default value for 213 parameters 344, 392, 437
overriding 210, 211, 213, 214 GUIs 329, 494

Index 531
H generating reports from 327
searching with 14
Halt command 125 Hypertext Markup Language (HTML) 202
hard-coding path names 360 See also HTML
HEAD tags 209
header files (C/C++) 337 I
header files (search extensions)
creating 466 I/O. See input; output
including 469 IBM AIX compilers 338
headers IBM AIX servers 340
building 74 IBM tables
generating content for 72 creating stored procedures 168
help xxxii–xxxiv icons in Variables window 126
building context-sensitive 163–165 identifiers. See symbols
creating balloon help text for 162–163 IDs
providing online 160, 162–163, 165 associated with names 192
help buttons 163 getting object 44
Help command 160, 163 If...Then control structure 286
Help menu xxxii If...Then...Else control structure 286
help topics xxxii image controls 14
HelpText property adding 214
not setting 160 images
hexadecimal numbers 265 accessing from external applications 292
hidden parameters 393, 439 display problems with 301
hide text attribute 394, 440 displaying 107, 214
hierarchy 4, 20 embedding in reports 106, 295
home page (Actuate) xxvii including at runtime 106–107
Horizontal duplex mode 412 linking 294
Horizontal property 207 printing 417
HP-UX compilers 338 scaling 417
HP-UX servers 340 storing in temporary files 107
HTML forms 202 Imp operator 255
creating 210, 222 implication 255
HTML reports implicit declarations 260
See also web pages include files. See header files
dynamically resizing elements in 212 IncludeHeader function 464, 469
HTML tags incorrect values 117
generating 205 indenting code 257
searching for 208 index (online documentation) xxxii
HTTP requests 211 index numbers (arrays) 263
hyperlinks 160 Information Delivery API xxvi
activating context menus for 160 information delivery solutions xxi, xxiii
adding to master reports 243, 245 information objects xxv
copying 160 informational error messages 117
creating dynamic 358–360 Informix tables 8
event handling for 479 inheritance 20
ambiguous methods calls and 41

532 Programming e.Repor ts

inherited methods variables 50–51, 125, 127
debugging 118 installDir parameter 409
overriding 56 installing
initializing ActiveX controls 486
objects 68 installing online documentation xxxii
Requester API 351, 355, 406 instance methods 318
in Visual Basic forms 362 instance variables
variables 66, 262 creating 54
in-place editing 299 described 24
input 503 monitoring 125
input adapters scope 55
accessing multiple 100 watching 127
closing 81 INSTANCE_TP type 471
filtering 98 instantiating
opening 81 classes 74–75
referencing 100 components 75, 104
input filter classes 80 connections 83
input filters data adapters 78, 81
creating multiple 99 data rows 81
instantiating 92, 98 objects 36
input parameters 177 reports 66
adding to stored procedures 179–182 SQL statements 85
defining 189 instantiation 74
returning columns with 194 abstract classes and 4
sample values for 171 based on conditions 104
testing for 179 concrete classes and 6
input records 81 declaring variables for 24
creating data rows for 6 InStr function 269
filtering data in 91 InStrB function 269
manipulating data in 90 int data type
input sources 76 Java objects and 319
accessing data in 79 int type 318
customizing connections for 85 INT_TP type 471
data streams with multiple 76 integer controls
opening 80 assigning values 272–273
retrieving data from 80 instantiating 14
InputParameters function 463, 470 Integer data type
Insert Object dialog box 293 assigning values 272
adding OLE custom controls 300, 301 C functions and 313, 316
embedding OLE objects 297, 298 converting to 277
linking OLE objects 297 declaring 266
opening 296 described 265
inspecting Java objects and 318
classes 48–49 returning as current 401, 446
methods 51–52 returning as default 386, 434
parameters 336 specifying parameters as 422, 456

Index 533
integers Java Native Interface (JNI) 316
See also numbers; integer controls Java objects xxvii
dividing 254 accessing 316, 317–318
floating-point numbers vs. 254 creating 317
overview 272 debugging 321
rounding 253 invoking methods in 317, 318
valid ranges for 265 type conversions for 318–320
integrated content xxiv Java programs
interfaces developing for xxvii
ActiveX controls and 474 Java Runtime Environment (JRE) 316
Actuate programming 326 Java Virtual Machine 316
creating Windows-based 329 JavaScript 202, 222
database-specific 5 debugging 208
enabling/disabling user elements 494 error messages 208
support for standard 20 JDK support 316
internal tools classes 14 JNI support 316
Internet Explorer JRE support 316
example implementation for 215–222
generating output for 211 K
scripting code for 204, 205 key fields 70
BrowserClipping property in 206, 207 See also sort key columns
invalid methods 58 key presses, mouse events and 158
invalid symbols 313 Key property 70
Is operator 44, 45, 255 keys. See sort keys
IsDate function 275 keywords
iServer C functions and 313
building applications for 351 operators as 253
generating reports from 410 restrictions 258
local reporting and 336
making multiple requests 357 L
managing multiple xxv
naming files for 476 label controls 14
overview xxii labels
programming interfaces for 326 changing characteristics of 39
running multiple xxv creating 36, 38
with Requester API 335 DHTML conversions and 203
iServer System Landscape orientation 413
overview xxv language extensions 250
IsKindOf method 44 language symbols 499
issuing requests 342 language. See Actuate Basic
iterators 15, 100 language-specific resources 499
large reports
J report bursting for 239, 240
LastPage method 479, 498
Java applets 202 LAYER tag 205, 222
Java class definitions 317 layouts. See page layouts
Java Development Kit (JDK) 316 LCase function 271
Java exceptions 320

534 Programming e.Repor ts

LCase$ function 271 linking
LD_LIBRARY_PATH variable 340 images to reports 294
leading spaces 270 OLE objects 292–299
LeadTools DLLs 488 embedding vs. 294
leaf classes 6 guidelines 296
Left function 269 links (online documentation) xxxii
LeftB function 269 LinkToExp property
left-to-right orientation 505 not setting 161
less than operator (<) 255 lists
less than or equal to operator (<=) 255 accessing contents 15
Let statement 43 comparing controls in 45
Lib statement 312 getting number of items in 497
LIBPATH variable 340 instantiating page 67
libraries 4 literal dates 273, 274
ActiveX controls and 487 literal strings 268
adding scripting controls 210, 215 loading language-specific resources 499
C functions in 310, 312 LoadResource method 498
closing 366, 423 local configurations 336
designing with xxiv local file names 476
initializing 405 local report generation 334, 500
relative paths and 360 local reporting 334, 336, 354
scoping conventions in 24 local scope 260
selecting for ActiveX API files 488 local variables
selecting for Requester API files 338–340 declaring 262
selecting for UNIX environments 340 monitoring 125
selecting for Windows environments 339 overview 262
specifying 312 retaining values for 262
library name argument 312 watching 127
Library Organizer locales 499
adding source files 310 e.reporting solutions for multiple xxii
creating source files 261, 281 log files 66
opening 261 logarithms 273
selecting source files 261, 281 logging into report server
library path (UNIX) 340 C++ example for 352
libreqstapi.sl 340 logic errors 117
libreqstapi.so 340 logical operators 255
libreqstapi_share.a 340 logical paper sizes 412, 416
licenses 474 logical values
lifetime. See scope performing calculations on 255
Like operator 255 returning 254
line continuation character (+) 257 logos 106
line controls 14 Long data type
linked lists 15 assigning values 272
comparing controls in 45 C functions and 313, 316
LinkExp property converting to 277
overview 243 declaring 266
report bursting example 245 described 265

Index 535
long statements 257 menus 14
long type 318 adding items 160
LONG_TP type 471 creating context 159–162
loops 250 creating for web browsers 215, 218
adding to programs 285 displaying context 157
arrays and 263 external applications and 299
exiting 287 merge filters 101
incrementing 287 messages
local variables and 262 See also error messages
nesting 287 forwarding 475
LRX (Live Report Extension) xxvii getting status 497
LTrim function 271 resetting status 503
Method Editor
M creating methods 59
mail dialog box 499 filtering options in 30, 50
mailing report files 480, 499 overriding methods 57
MailReportInstance method 480, 499 starting debugging sessions from 118
maintenance version 404, 449 Method Filtering dialog box 60, 61
Management Console xxv debugging in 118
managing clusters xxv method naming conventions 59
managing displays 6 methods 18, 251
mantissa 273 accessing 39, 310
Manuals directory xxxii ActiveX alphabetical reference 491
MapAcctTypes function 154 ActiveX categorized 477
mapping functions 154 Actuate Basic categorized 30
mapping variable types 198–199 associated with mouse events 157
mapping XML to reports sections 230, 234 calling 40
mark-up tags 226 resolving ambiguity when 41
master reports 238 caution for creating 58
adding hyperlinks 243, 245 caution for overriding 30, 32
examples for creating 240 class protocol for 4
mathematical operations component references and 75
date/time values in 274 creating 58–59
numbers in strings 268 customizing 250
operators for 254 data access 80
variants and 268 debugging 118, 128
matrix arrays 264 deleting 61
Me keyword 280 derived classes and 20
memory 45 displaying 51, 60, 111, 128
clearing programs from 125 dot notation and 39
local variables and 262 editing 60–61
managing external 310 empty 4, 20
OLE objects and 306 executing specific tasks with 252
memory buffers 10 extending functionality of 56
memory cleanup function 310 filtering 52, 60, 61
memory leaks 368 inspecting 51–52
variables in 127

536 Programming e.Repor ts

methods (continued) monetary values 265, 272
invoking Java 317, 318 monitoring values 125
multiple definitions for 32 Month function 274
naming 32, 41, 58, 59, 257 mouse cursor 157
OLE Automation objects and 305 mouse events 156–159
overloading 32 ActiveX controls 484
overriding 31, 56–57 key presses and 158
component references and 75 overview 156
for custom data streams 90 parameters listed 157
for XML documents 229 responding to 157
report generation and 66 moving OLE components 301
overview 30–32, 57, 280 moving through reports 478
procedures as 251, 280 ActiveX function calls for 498, 499, 502
properties vs. 58 MS SQL connections 8
redefining 20 Multi-Application Option xxvi
referencing 39, 40 multidimensional arrays 264
restoring functionality 40 C functions and 315
scope 280 Java objects and 319
setting breakpoints for 123 MultiLine property
specifying explicitly 40, 41 browser scripting controls and 208
stepping through 124 multi-line statements 257
stored procedures and 188, 193, 194 multilingual reporting xxii
storing values for 29, 52 multiplatform interface 326
viewing call stack for 128 multiple data adapters 78
visibility 20 multiple input filters 80, 98
with no parameters 318 multiple options 378, 427
Methods dialog 111 multiplication 254
Methods page (Component Editor) 30 multi-table reports 99, 101
adding methods 58
deleting methods 61 N
inspecting methods 51 name conflicts 23
overriding methods 57 Name property
Microsoft Internet Explorer. See Internet Me keyword vs. 280
Explorer names 21
Mid function 269 C functions and 312, 313
MidB function 269 duplicate 41, 59
MIME type 232 getting class 44
minus sign (–) in strings 270 getting parameter 344
mixed capitalization 257 guidelines for 258
Mod operator 254 hard-coding 360
modal dialogs 475 IDs associated with 192
modules 49 referencing 22
containing procedure declarations 281, naming
282 arrays 53
copying external functions to 360 classes 40, 257
user-defined types and 276 controls 23
modulus 254

Index 537
naming (continued) NO_TP type 471
executable files 352, 355 NoClipping setting 207, 222
iServer files 476 NoKeys setting 158
local files 476 nonstandard data sources 90
methods 32, 41, 58, 59, 257 nonstandard names 313
procedures 258, 285 non-visual classes 6
search extensions 464, 469 non-zero return values 407, 451
variables 53, 257 not equal to operator (<>) 255
naming conventions 257, 339, 488 Not operator 255
methods 59 Nothing keyword 43, 44
native file systems 476, 479 OLE Automation objects and 306
navigating through reports 478 notifications
ActiveX function calls for 498, 499, 502 report completion 66
navigation methods 478 null character 315
navigational tools 484, 485 Null keyword 315
Contents window as 485 null pointers 315
Navigator. See Netscape Navigator null values 315
negation 255 assigning to objects 43
negative exponents 254 testing for 44
negative numbers 108, 270 NULL_TP type 472
nested classes 21, 23 null-terminated strings 315
nested declarations 20 number sign (#)
nesting 67 in dates 273, 274
class data types 266 type declaration 267
control structures 287 numbers 37
controls 23 See also numeric controls; integers
procedures 257 arithmetic operators and 254
statements 257 computing powers and roots of 254
user-defined type declarations 276 concatenating with strings 256
Netscape Navigator converting
creating reports for 222–223 to character values 253
generating output for 211 to dates 275
scripting code for 205 to strings 270
BrowserClipping property in 206, 207 displaying 108
New keyword 36 dividing 254
New Library dialog 261 getting as current value 401, 402, 445, 446
New method 68 getting as default 385, 386, 434
overriding 104 overview 272
new pages 73 representing colors 265
NewConnection method 83 rounding 253
NewContent method 67 setting as default 421, 422, 456
NewPage method 73 valid ranges for 265
NewPageList method 67 variants and 268
Next buttons 484 numeric constants 253, 258, 267
Next_Click event 484 numeric controls
NextPage method 479, 484, 499 assigning values 272–273
NLS resource DLL 498 instantiating 14

538 Programming e.Repor ts

numeric data types 273 defining as persistent 37, 46
numeric expressions 254 defining attributes 25, 276
conditional statements and 286 defining behavior for 18
numeric variables 273 defining structural characteristics of 7
executing tasks on 40
O generating content for 68
Object command (Edit) 294, 295, 300 getting information about 31
Object command (Insert) 297, 300 initializing 68
Object data type 319 instantiating 36
object files (OLE) 292, 296 lifetime of 45
object IDs 44 nesting classes in 23
Object Linking and Embedding. See OLE overview 34
object reference variables 18 providing help with 162, 163
assigning values 42–43 referencing 37, 38, 39, 280
C functions and 316 releasing from memory 45
comparing 45, 255 returning values for 39
declaring 34–36 scope 45
AnyClass type for 36 selecting 157, 158
Java objects and 317 specifying actions for 30
monitoring 126 support for OLE 293
OLE Automation and 305, 306 temporary 45
overview 37–39 tracking 66
passing to procedures 43 viewing events for 156
restrictions for 42 ObjectVariable property 111
setting to Nothing 43 obsolete properties 117
testing 44–45 OCX controls 292
tracing 126 See also OLE custom controls
object references ODBC databases
returning 43 connecting to 8, 84
testing status 44, 45 ODBC stored procedures 168
Object type 319 OLE 292
object-oriented languages 250 OLE applications 292
object-oriented programming 250 closing 306
objects editing 294, 295, 299–300
accessing Java 316, 317–318 incorporating data from 294
accessing variables and methods in 39 OLE Automation objects
adding from external applications 292, 296 closing 306
altering behavior of 58 compared to OLE objects 304
assigning to variables 42 creating 305
assigning variables to 24 defined 304
base class for 5 OLE components
building 68 moving and sizing 301
creating 34–37 subclassing 302
for Java applications 317 OLE container components
customizing 37 adding 296, 297, 298
defined 34 inserting for OLE custom controls 300
OLE containers 14, 292

Index 539
OLE controls 14, 474 implementing 161, 164
OLE custom controls overriding 157, 161
accessing 292 OnRButtonUp method 157
adding 300–301 OnRead method
overview 293 overriding 90
OLE objects OnRow method
accessing 304 overriding 108, 112
adding 14, 296–299 Open function 463, 470
changing 294, 295, 299–300, 302 open server 64
compared to OLE Automation objects 304 open server reports
defined 292 invoking functions in 480, 493
linking and embedding 292–299 open server technology xxiv
guidelines 296 OpenConnection method 83
resizing 301 OpenCursor method 183
support for 293 opening
OLE registry 293 Component Editor 49
OLE strings 368 Contents window 506
OLE_TP type 472 executable files 485, 500
OnActuate method external applications 305
default action for 161 files 470
executing 160 input data adapters 81
overriding 161 input data sources 80
OnContextMenu method Library Organizer 261
creating context menus 159 log files 66
default action for 161 report files 342, 407, 452
implementing context-sensitive help 164 reports 477, 485, 500, 501
OnFollowLink method Stack window 129
creating context menus 160, 161 Variables window 126
default action for 161 Watch window 128
overriding 160 OpenRecentReportInstance method 479, 500
OnHelp method 160, 164 OpenReportExecutable method 480, 485, 500
OnLButtonClick method 157 OpenReportInstance method 478, 485, 501
OnLButtonDblClk method 157 operands 253
OnLButtonDown method 157, 158, 358 operating environments 329
overriding 157 operators
OnLButtonUp method 157 assignment 252
online documentation precedence 256
accessing xxxii scope-resolution 22
overview xxvii simple types described 253–256
syntax conventions for xxxv variants and 268
typographical conventions for xxxv optimizing Actuate Basic 267, 272
online help xxxii–xxxiv optional parameters 352
providing 160, 162–163, 165 testing for 442
OnRButtonClick method 157 options 378, 427
OnRButtonDblClk method 157 iServer System xxvi
OnRButtonDown method Or operator 255
default action for 157, 159 Oracle multiple result sets 194

540 Programming e.Repor ts

Oracle tables customizing ACLs for 153–154
accessing stored procedures in 191, 194– customizing security IDs 151–152
198 example for implementing 149–151
connecting to 8 implementing 135–140
creating stored procedures 168, 182–188 overview 132–135
order of evaluation 256 Page Level Security Option xxvi
orientation (page) 413 page list class 6
output page list components 73
aligning web browser 207 page list styles 73
clipping browser 206, 213 page lists
e.reporting solutions for xxiv Factory processes and 72
generating dynamically 214 instantiating 67
generating for web pages 211 page numbers
scaling 212 getting current 496
output files 352, 355 setting programmatically 498
output parameters viewing in secured reports 137
adding 180 page orientation 413
declaring as cursor variable 194, 195 page security 120
defining 189, 198 page structure (Factory) 67
testing for 179 page styles 73
Output window 117 PageBreakAfter property 73
viewing errors in 117 PageBreakBefore property 73
overloading methods 32 PageCount method 479, 501
overloading procedures 285 page-creation protocol 72–74
overriding methods 56–57 page-level security xxvi
caution for 30, 32 PageNumberType property 137
component references and 75 pages 156
for custom data streams 90 See also page layouts
for XML documents 229 adding report objects to 11
overview 31 building 6, 72
report generation and 66 counting 501
restoring functionality 40 creating content for 6
restrictions 31 creating report 11
overriding precedence 256 defining characteristics of 6
overwriting report flies 378, 427 printing options for 348
tracking number of created 66
P paging through reports 478
page breaks 73 ActiveX function calls for 498, 499, 502
page layout classes 11 PaintBrush applications 292
page layouts paper size
designing at runtime 104–107 by dimensions 414
determining style 73 by type 412
headers and footers paper trays 417
generating content for 72 parameter dialog 503
page creation process and 74 Parameter option 55
page level security Parameter Sample Values command 171

Index 541
parameter values files inspecting 336
ActiveX controls and 476 manipulating in C++ applications 369,
closing 376 370, 373
creating 122, 425, 459 manipulating in Visual Basic forms 363
described 342 methods and no 318
finding specific values in 346 mouse events and 157
generating reports from 377, 408, 426, 452, overloaded methods and 32
504 passing arguments to 284
getting parameter groups in 391, 394, 437, procedures and 283
440 prompting for 366
getting specific parameter in 392, 395, 438, saving 122
441 setting as Currency type 420, 454
opening 407, 452 setting as Date type 420, 455
parameter variables setting as Double type 421, 456
adding 52 setting as Integer type 422, 456
displaying 28, 50 setting as String type 423, 457
overview 25 setting default values for 96
parameterized queries. See stored procedures setting for successive debugging runs 116
parameter-passing conventions 43 setting programmatically 352, 355, 393
C functions and 311, 312, 315–316 stored procedures 171, 177, 179–182
parameters 330 storing 342, 352, 355, 425, 459
See also search parameters testing default assignment 405, 449
adding to image controls 106, 107 testing status 382, 393, 397, 430, 439, 442
assigning values 347, 396, 398, 442 Parameters page (stored procedures) 179, 181
assigning variables as 25, 28 parentheses in expressions 256
changing 336 parsing 208, 269
data filters and 91 passing by reference 284
defining input 189 C functions and 312
defining output 189, 198 passing by value
determining how retrieved 418 C functions and 312
displaying 394, 440 passwords 84, 351
generating reports and 397, 443 in API function calls 343
getting ad hoc 382, 430 obtaining customer xxvii
getting aliases for 382, 430 prompting for 477
getting attributes 345 specifying programmatically 495
getting current values 346, 399, 400, 401, patch number 404, 449
402, 403, 443, 444, 445, 446, 447, 448 PATH system variable 341
getting data types for 396, 398, 442 path variables (UNIX) 340
getting default values for 346 paths 260, 312, 349
getting defaults 383, 384, 385, 386, 387, DLLs and relative 360
388, 431, 432, 434, 435, 436 getting most recent 497
getting group names for 391, 394, 437, 440 hard-coding names in 360
getting names 344 specifying for API libraries 340
from Visual Basic forms 364 specifying in API function calls 343
from Visual C++ forms 369 pattern matching 177–178
getting specific 392, 395, 419, 438, 441 pausing program execution 123
grouping 344, 392, 437 PDF converter 213

542 Programming e.Repor ts

PDF files Print_Click event 485
adding objects from 292 printed documentation xxix
displaying controls in 214 printers
viewing reports as 213 changing default 348, 413, 453
PeopleSoft databases 168 configuring 348
percent (%) character in code 266 local configurations and 336
permissions 477, 501 setting paper size for 412, 414
Persistent keyword 37 specifying 353, 356, 410, 413, 453
persistent objects 6 specifying paper tray for 417
creating 37 printing images 417
Factory service and 64 printing options 348, 406, 450, 502, 503
overview 46 printing reports
personal views 132 API functions for 348
physical paper sizes 414, 416 from Actuate Viewer 214
placing frames in flows 6 from End User Desktop 336
platform-independent formats 226 from PDF files 213
pointers 276, 314 from report server 336, 353, 356
passing to C functions 315 from Requester API 335, 406, 450
pop-up menus 14 from Visual Basic forms 363
adding items 160 from Visual C++ forms 369, 371
creating 159–162 locally 336, 348, 407, 451
displaying 157 multiple copies 413
web browsers and 215, 218 overview 64
Portrait orientation 413 with ActiveX controls 480, 502
positive exponents 254 with images 107
positive numbers 108, 270 PrintReport method 480, 502
pound sign (#) priorities 418
in dates 273, 274 private classes 49
type declaration 267 private methods 30
powers 254 Private option 55
precedence 256 private variables 26
connections 84 privileges 336, 477, 501
precision 272 procedures 250, 280
predefined classes accessibility of 281
See also Actuate Foundation Classes accessing variables in 260
predefined functions 285 adding comments to 256
See also functions; methods C functions as 311, 312
predefined methods 30, 251 calling 281, 284
See also methods creating 251
Prepare method 85, 86 declaring 282
stored procedures and 194 defining arguments for 283
Preserve keyword 264 defining as global 281
Prev buttons 485 exiting 287
Prev_Click event 485 functions as 282
PreviousPage method 479, 485, 502 in DLLs 315
Print buttons 485 local variables and 262
Print method 502 methods as 30, 251

Index 543
procedures (continued) progress windows 378, 427
naming 258, 285 projects. See programs
nesting 257 prompts
object reference variables and 37 creating custom dialogs for 366
overloading 285 defining for Requester 383, 431
returning values 43 properties 25, 120
scope 280 browser scripting controls 204, 207, 214
stepping through 124 changing dynamically 108
types listed 280 component references and 74
product suite xxiv conditionally changing 110–113
product updates xxvii displaying 51
program files. See report files methods vs. 58
programmers 250, 256 referencing obsolete 117
programming interfaces setting 26–28, 51
accessing 337 at design time 34
choosing libraries for 338, 488 at runtime 28, 108
closing sessions for 353, 356 conditionally 108
error checking for 349–350 user-defined types and 275
file naming conventions 339, 488 XML-specific 229, 230
initializing sessions 351, 355 Properties page (Component Editor)
overview 326–328 adding variables 55
programming tasks for 341 setting property values 51
selection guidelines for 329–331, 337 viewing properties 51
setting up client stations for 340, 341 Property option 55
uninstalling class libraries for 423 Property setting 25
programming languages xxv, 250, 337 property variables
programming tools xxv, xxvi adding 52
programming. See Actuate Basic; object- inspecting 50, 125
oriented programming overview 25, 26
programs Public option 55
adding C functions to 310, 311 public variables 26
adding source files to 310 publishing data streams 83
clearing from memory 125 publishing XML reports 229–236
controlling execution of 123 PutRow function 464, 470
creating procedures for 280
debugging 116 Q
developing 251, 256 qtrly.dtd 227
improving readability of 285 qualified names 22, 41
resuming execution 124 queries 79
returning incorrect values 117 ad hoc parameters and 382, 430
running 123 creating 81, 86
stepping through 123 for report bursting 242
stopping execution 125 defining cursors for 189
Progress database connections 8, 85 executing 86
Progress databases xxvi instantiating statements in 85
creating stored procedures for 168 overview 85
Progress Option xxvi

544 Programming e.Repor ts

queries (continued) methods 39, 40
running ad hoc xxvi objects 37, 38, 280
setting conditions at runtime 28 dot notation for 39
stored procedures and 168 obsolete properties 117
query classes 9 report files 343
query data sources. See SQL data sources variables 39
Query Editor registering ActiveX controls 486, 488
creating queries 81 registry entries
filtering data 91 ActiveX installations 488
filtering multiple data sources 99 search parameters 463
Query Option xxvi regsvr32 DeskOCX command 488
query statements. See queries; SQL relational databases. See databases
statements relationship map (components) 66
Quit method 306 relationships xxvi, 68
quotation marks in strings 272 release notes xxvii
release numbers 404, 449
R Rem keyword 256
random access methods 80 remainders 254
random data access 79 removing type restrictions 312
range of values 265 renaming
dates 274 stored procedures 170
searching for specific 505 renaming C functions 313
type definitions and 265 repetitive tasks 280, 304, 330
real numbers 272 report bursting 238
real types. See Double data type; Single data asynchronous reports and 238
type examples 240
records. See data rows report class 6, 7
rectangle controls 14 report component class 6
calculating area of 283 report components
ReDim statement See also components
arrays and 264 abstract base classes for 4
object reference variables and 34 creating 68
REF_CURSOR type 195 instantiating 6
REF_TP type 472 Report Debug Options dialog 122
REFCUR3.GETMGRDATA 184 report designs 251
reference 375 adding browser scripting 205, 209
reference count 45 adding objects from external
references 20 applications 292
getting 112 creating at runtime 104–107
returning 43 creating for flat file data sources 94, 97
testing status 44, 45 creating with Design Editor 18, 74
referencing implementing page level security 135–140,
classes 20, 22 149
components 68, 74, 78 multiple data sources and 99, 102
global browser code 209 stacking controls in 214
input adapters 100 testing 138, 141
report examples xxviii

Index 545
report executables. See executable files Reporting Engines suite xxiv
report files 342–344 reporting features 329
accessing 376, 426 reporting solutions xxi, xxiii
bundling 493 ReportQuery technology xxiv
closing 376 reports
generating 342 accessing 496
multiple 238 in Encyclopedia volumes 335
generating reports from 408, 452 adding company names and logos 106
mailing 480, 499 as OLE containers 292
opening 407, 452, 485, 500 as OLE servers 292
overwriting 378, 427 building 4, 64
referencing in API function calls 343 starting Factory process for 66–67
server connections and 477 building pages for 6
specifying local names for 476 building subreports for large 238, 239, 240
report object files 343 canceling generation requests 494
report object structure classes 7 closing 477, 484, 495
report objects content/page structures for 67
default scope for 22 controlling access 132, 154
instantiating 6, 7, 66 converting to DHTML 202
nesting classes in 23 counting number of pages in 501
placing on page 11 creating programmatically 251
report parameters. See parameters customizing xxv, 31, 89
report sections debugging 139
accessing data in 153 designing xxiv
creating content for 68, 69 developing xxv, xxxiv
placing connection components in 83, 85 displaying xxvii, 155
report server ActiveX controls and 474, 485
See also e.Reporting Server API functions for 348
accessing report files from 477 as PDF 213–214
accessing volumes 335 in Actuate Viewer 214, 341, 411, 453,
connecting to 334, 351, 495 466
creating parameter values files for 425, in C++ applications 368
459 in Encyclopedia volumes 477
defined 326 in Visual Basic forms 362, 366
generating reports from 365, 377, 418, 426 in web pages 64, 202
opening report files from 407, 452 locally 336, 349, 356
printing from 353, 356, 406, 450 Requester API and 335, 336
running reports from 500 generating xxv, 63, 397, 443
viewing reports on 366, 424, 457 API functions for 377, 426
Report Server API xxvi Factory service and 64, 66, 67
overview 326, 330 from report files 408, 452
selecting DLLs for 339, 340 from Visual Basic forms 362, 365
Report Server Security Extension xxvi, 134 from Visual C++ forms 369, 370
report statistics 66 Requester API and 334
Report Wizard getting content for 76
generating SQL data sources 94 getting generation status for 408
ReportCast xxv getting values at runtime 28

546 Programming e.Repor ts

reports (continued) support for third-party 64
getting version 396 viewing
implementing secured 131 secured 134
invoking functions in 480, 493 reqapivb.txt 337
launching 379, 428 reqbasic.h 337
moving through 478, 498, 499, 502 REQCYTYPE struct 384, 399, 432, 444
multiplatform interface for 326 request handle 381, 429
opening 477, 485, 500, 501 Requester
personal views for 132 asterisks as text strings in 393
platform-independent formats 226 customizing 345, 351, 392, 437
printing 64, 107 Visual Basic example for 366–368
API functions for 348 defining debugging parameters 122
from Actuate Viewer 214 defining prompts for 383, 431
from PDF files 213 displaying variables in 55
from report server 353, 356 getting parameter names in 345
from Requester API 406, 450 Requester API xxv, 357
from Visual Basic forms 363 alphabetical function reference 375
from Visual C++ forms 369, 371 and iServer 335
locally 336, 348, 407, 451 building applications 350–357
multiple copies 413 client code for 409
with ActiveX controls 480, 502 client-server configuration for 335
providing online help for xxxiv closing libraries for 366, 423
publishing 334 closing session 353, 356
publishing as XML 229–236 customizing 383, 431
responding to events 156 developing with 334–341
running dynamic link libraries for 339, 340
API functions for 348 error codes for function calls 389
based on specified parameters 342 file naming conventions for 339
C++ sample code for 353, 370 functions categorized 341–350
default values and 383, 431 getting version information for 404, 448
from ActiveX controls 479, 485, 494, implementing ActiveX controls from 489
503, 504 initializing 351, 355, 406
from End User Desktop 410, 453 from Visual Basic forms 362
from parameter values files 352, 353, local reporting and 336
355, 356 operating environment described 340
in batch mode 327, 349, 380, 429 operating requirements for 336–341
locally 336, 349, 354 overview 326, 330, 334
on report server 500 programming examples 337
Requester API and 335, 336 for Actuate Basic 358–360
Visual Basic sample code for 356 for C++ 368–374
running on iServer 500 for Visual Basic 360–368
saving 480 running applications from 338, 339, 340
as XML documents 504 shutting down 423
scaling 485, 505 specifying multiple options 378, 427
specifying local file names for 476 requests
specifying server files names for 476 getting status 408
subclassing 239 issuing 342

Index 547
requests (continued) RightB function 269
prioritizing 418 right-to-left orientation 505
resubmitting 357 Rogue Wave programs 337, 339
submitting 217, 353, 356, 357 ROI files. See document files; report object
required parameters 352, 355 files
search extensions and 465 RoiFileName parameter
testing for 442 specifying 352, 355
reserved words roiimage.rod 107
C functions and 313 RoiIsTemporary method 238
operators as 253 roots 254
restrictions 258 ROS files. See search definition files
ResetStatus method 503 rotp syntax 335, 353, 476
resizing rounding 253
OLE objects 301 rounding errors 273
resolving ambiguous methods calls 41 routines 408
resources ROV files. See parameter values files
freeing 423 rows. See data rows
loading language-specific 499 ROX files. See executable files
responding to events 156 RoxFileName parameter 349
Result Columns page (stored specifying 352, 355
procedures) 175, 176 royalty-free distribution 474
result sets 168 RTrim function 271
accessing multiple 197–198 Run buttons 485
defining cursors for 189 Run_Click event 485
retrieving 175 running programs 123
returning different types 180 line by line 123
with duplicate column names 175 running queries 86
retrieving running reports
data 79, 80, 81, 82 API functions for 348
from data adapters 6, 78 based on specified parameters 342
from data streams 76 batch mode for 327, 349, 380, 429
from external data sources 6 C++ sample code for 353, 370
from flat files 94 canceling requests for 494
from multiple sources 98–103 default values and 383, 431
from nonstandard sources 90 from ActiveX controls 479, 485, 494, 503,
from text files 90 504
data rows from End User Desktop 410, 453
from stored procedures 189 from parameter values files 352, 353, 355,
with database cursors 85 356
return values 282, 283 locally 336, 349
C functions and 311, 316 sample application for 354
checking for errors with 350 on report server 500
getting from stored procedures 189, 192, Requester API and 335, 336
194 Visual Basic sample code for 356
printing functions and 407, 451 running stored procedures 189
procedures and 43, 284 RunReport method 480, 485, 503
Right function 269 RunReportWith Parameters method 480

548 Programming e.Repor ts

RunReportWithParameters method 504 SDK (Software Development Kit) 337
run-time errors 117 search criteria. See search parameters
run-time properties 28, 108 search definition files 463
run-time values 25 closing 468
RWCString class 314 creating 465
default directories for 463
S extension-specific parameters in 472
sample applications xxviii retrieving information from 469
sample database files Search Extension API xxv
Oracle8 stored procedures 184 search extension API
Sample Parameter Values 179 alphabetical function reference for 467
Sample Parameter Values dialog 170 data types for 471
sample reports xxviii function calls 465
report bursting techniques 240 functions categorized 462–464
sample Windows application 482 overview 327, 330, 462
running 485 shutting down 468
SampleValue property 205 search extension applications
SaveAsXMLData method 480, 504 creating header files for 466
saving defining column delimiter for 468
report parameters 122 developing 464–466
reports 480 including column names 469
as XML documents 504 installing 466
user-defined methods 59 naming 464, 469
scalar data type 273 opening files for 470
scale factor (default) 505 processing search results for 464, 470
scaling factor 212 prompting for input parameters 470
scaling images 417 running 463
scaling reports 485, 505 search extension directories 409
scheduling reports 274 search extensions 327, 409, 462
schema default directories for 463
verifying stored procedures 170 Search Extract Option dialog 463, 470
scope 21–23 search parameters
changing 24 getting 469
default 22 implementing 470
defined 20 setting programmatically 463, 472
determining 22 search paths 312, 349, 360
methods 280 Search window 475, 505
objects 45 SearchDefDir setting 463
procedures 280 SearchExtDir setting 463
variables 125, 260 searching 14, 327
setting in Component Editor 55 for HTML tags 208
scope-resolution operator 22 for specific values 505
scripting control. See browser scripting for stored procedures 177–178
controls third-party applications 462
scroll bars 207 with ActiveX controls 505
Scrollbar setting 207 SearchWindow method 479, 505
section classes 6, 10

Index 549
sections editing in 299
accessing data in 153 OLE linking for 292
adding data rows 71 Server Integration Technology xxv
building 10 server-based reporting xxiv
creating content for 68, 69, 70 servers
determining page styles for 73 accessing files 376, 426
mapping XML properties to 230, 234 accessing report files from 477
page creation process and 72 connecting to 5, 8, 334, 351, 376, 425, 495
placing connection components in 83, 84, disconnecting from 353, 377
85 e.reporting solutions for xxiii
secure read privilege 154 generating reports 377, 426
security 132–135, 336 managing clusters for xxv
customizing ACLs for 153–154 opening report files 407, 452
customizing security IDs 151–152 printing reports 406, 450
debugging with page 120 programming interfaces for 326
e.reporting solutions for xxiv referencing in API function calls 343
enabling page-level xxvi Set statement
example for implementing 149–151 compared to Let statement 43
implementing 135–140 New keyword and 36
server connections 351 Nothing keyword and 43
security IDs 133 object reference variables in 42
access control lists for 133 OLE Automation objects 305, 306
adding 134 SetDataTypeInfo function 464, 471
customizing 151–152 SetParameters function 463, 472
displaying 140 SetScaleFactor method 479, 485, 505
getting 134 SetSecurity method 153
suppressing 153 setting properties 26–28, 51
testing 138 See also properties
security role 133 at design time 34
security tools xxvi at runtime 28, 108
SeekBy method 79 conditionally for controls 108
SeekTo method 79 XML documents 229, 230
SeekToEnd method 79 setting watches 127
select filters 92–93 SetupDataRow method 82
SELECT statements 85 SetValue method 82
See also SQL statements SetWindowLayout method 479, 505
selecting shared libraries 310, 312
stored procedures 177 selecting for API files 340
selection formulas. See parameters shared tasks 280
selection state toggles 158 sharing connections 83
separation character (:) 257 sharing data 292, 304
sequential data access 79 shift parameter 158–159
serial numbers 274 ShiftKey Bor AltKey setting 158
server ShiftKey Bor ControlKey setting 158
accessing volumes 351 ShiftKey Bor CtrlKey Bor AltKey setting 158
server applications 329 ShiftKey setting 158
deploying to 334 SHLIB_PATH variable 340

550 Programming e.Repor ts

short date format 274 displaying specific methods in 128
short type 319 editing 48
Show all methods filter option 111 editing restrictions 55, 56, 60, 61
ShowInDHTML property 214 examples for 258
ShowInPDF property 214 extending functionality 310
ShowWhenPrinting method 107 getting values for 31
ShowWhenPrinting property 214 handling invalid methods in 58
ShowWhenViewing method 107 implicit declarations and 260
ShowWhenViewing property 214 indenting 257
Simplex mode 412 language elements in 252–256
simplifying programming tasks 280 locating errors in 117
Simulated Page Security Viewing programming conventions for 251
options 120 resuming execution of 124
Single data type running 119
assigning values 272, 273 setting watches 127
C functions and 313, 316 startup/cleanup
converting to 277 Factory services 66
declaring 267 Requester API 342, 353
described 265 search extension API 463
Java objects and 318 stepping through 123, 125
single input filters 80 stopping execution of 125
SINGLE_TP type 472 viewing comments in 49
single-byte characters 269 writing custom browser 209, 210
single-dimension arrays 319 source file window 119
single-line statements 257 source files 251
slots (Structure pane) 74 adding to projects 310
SOAP messaging protocol xxvi C functions and 310
Software Development Kit 337 creating 281
Solaris compilers 338 custom browser code in 209
sort filters 93–94 debugging 116
sort key columns 70 declarations sections in 261
getting at runtime 108 declaring procedures in 280, 281
sort keys starting debugging sessions for 119
setting at runtime 108 tracing through 124
setting programmatically 69 special characters 202, 204
sorting on 70 Specify Parameter File Name dialog 122
sorting data 70, 93 specifying multiple options 378, 427
sound files 292 spreadsheets
source code as data sources 80, 292
See also Actuate Basic as input sources 76
accessing Java objects in 318 designing xxv, xxvii
accessing variables in 26 generating xxvi
adding breakpoints 123 OLE automation and 304
adding comments 256 SQL data sources
conventions for 256–258 accessing data 85, 90
debugging 115 adding to reports 96
displaying browser 208 connecting to 8, 84

Index 551
SQL data sources (continued) described 252
filtering 81 executing conditionally 286
filtering multiple 99, 101 executing series of 283
improving performance for 168 fixing errors in 117
instantiating 10 incorrectly constructed 116
overview 85 instantiating classes and 18
reading columns in 82 monitoring 123
retrieving data from 10, 79, 80, 94 nesting 257
SQL statements programming conventions for 257
See also queries repeating indefinitely 286
as stored procedures 168 static controls 13
creating 86 static fields 317, 318
instantiating 85 static methods 318
overview 85 Static statement 260
running 86 creating static variables 24
square roots 285 declaring local variables 262
SrchDef directory 463 declaring object reference variables 34
SrchExt directory 463 static text 14
stack 497, 503 static variables 25
Stack window 128 creating 24, 54
opening 129 declaring 260
stacking controls 214 scope 55
standard data types. See data types visibility 20
Start method statistics 66
AcControl 72 status codes 408
AcDataAdapter 78 status information 408
AcDataFilter 81 status messages 497
AcDataSource 80 resetting 503
AcFrame 71 status stack 503
AcGroupSection 71 status strings 481
AcReportComponent 68 Step Into command 124
AcReportSection 69, 83 Step Into icon 124
overriding 66, 90 Step Over command 124
for flat file access 97 Step Over icon 124
for multiple data sources 100 stepping over code 124
StartFlow event 73 stepping through code 123, 125
starting stopping debugging sessions 125
Component Editor 49 stopping program execution 125
debugging sessions 118 stored functions 182, 194
Factory services 65, 66 example for 184
StartNextSet method 189 Stored Procedure Browser 170, 174
StartPage event 73 Oracle tables and 182
startup code stored procedure components 168
API functions for 342 Stored Procedure Data Source Builder 182
Factory services 66 accessing 169
search extensions 463 entering parameters 179, 180
statements 250 narrowing procedure list 177
defining blocks of 286 overview 168

552 Programming e.Repor ts

Stored Procedure DataSource Builder 188, string variables 213, 268, 269
194 STRING_TP type 472
Stored Procedure Name Editor 170 strings 37, 268–272
stored procedures as BSTRs 337, 368
accessing 188 asterisks as 394, 440
creating 171–174 binary data and 106, 269
for Oracle8 data sources 182–188 character limits 265
customizing 188–199 comparing 255, 270
defined 168 concatenating 256
defining parameters for 189, 198 converting Java 319
entering parameters 171, 177, 179–182 converting numbers to 253
extracting return values from 192, 194 converting to binary data 107
not returning data 175 converting to currency 384, 399, 432, 444
renaming 170 debugging Java 321
retrieving data 176–177 declaring 268
returning multiple result sets 197–198 as empty 215
returning status values 189 defining for online help 162
returning unknown values 180 delimiting literal 268
searching for specific 177–178 formatting 270
selecting 170, 174, 177 getting as current value 403, 447, 448
setting up 174 getting as default 387, 388, 435, 436
synchronizing 170, 177 leading spaces in 270
testing for parameter type 179 null-terminated 315
verifying contents 170, 177 parsing 269
storing values 260 passing to C functions 315
global variables for 113 PDF conversions and 213
methods and 29 quotation marks in 268, 272
objects and 39 returning numbers as 270
Str function 270 setting as default 423, 457
Str$ function 253 variants and 268
StrComp function 270 strong cursors (defined) 194
stretched images 301 Structure pane 74
string comparison operator (Like) 255 structured content technology xxii
string constants 267 structures 250
String data type See also control structures
C functions and 313, 316 defined 266
converting to 277 monitoring 126
declaring 267, 268 user-defined types as 275–276
described 265 style sheets 207, 222
returning as current value 402, 403, 447, STYLE tag 223
448 Sub statement
returning as default 387, 388, 435, 436 C functions in 311
specifying parameters as 422, 457 creating global procedures 281
string data types 314 creating subprocedures 282
string expressions 272 initializing global variables 262
string functions 269 subclass 20
String keyword 268

Index 553
subclasses 4 invalid 313
declaring 18 Synchronize Stored Procedure command 177
object reference variables and 35 Synchronize Stored Procedure With Schema
redefining methods in 20 icon 170
testing for instances of 44 synchronizing stored procedures 170, 177
subclassing 20 synchronous mode 378, 427
abstract base classes 4 synchronous report generation 379, 381, 428,
inherited properties and 28 429
OLE components 302 syntax
reports 239 See also declarations
stored procedures and 193 C function declarations 311
submitting requests 217, 353, 356, 357 Class statement 18
subpages 11 CreateJavaObject function 317
subprocedures Function statement 282
See also Sub statement local file names 476
C functions as 311 method calls 40
calling 284 object reference variables 34, 39, 42
declaring 282 server names in API function calls 343
defining as global 281, 282 Set statement 36
exiting 287 Sub statement 282
functions vs. 283 Typedef statement 275
initializing variables in 262 syntax conventions (documentation) xxxv
subreports 83 syntax errors 116
HTML documents 239 SysFreeString method 368
substrings System Properties dialog 317
comparing 270
concatenation and 256 T
getting 269 Table of Contents 475
subtraction operator (–) 254 opening 485, 506
successive debugging runs 116 TableOfContents method 479, 485, 506
SuggestRoiName method 243, 245 tables
summary graphs 14 getting from stored procedures 194
SunOS operating systems 340 tabular reports 4
Super keyword 40 tags 226
superclasses technical assistance xxviii
class relationships and 20 telephone numbers 268
overriding methods and 57 templates
referencing methods in 40 classes as 18
restrictions for 21 temporary calculations 262
suspending code execution 123 temporary files 107, 352, 353, 355, 357
Sybase tables deleting 107
accessing stored procedures in 189, 193 temporary objects 45, 304
connecting to 8, 85 terminating database connections 84
stored procedures and 168, 180 terminating server connections 353, 377
symbols 21, 253 testing applications 122
C functions and 312

554 Programming e.Repor ts

testing page level security 138 U
examples 141–148
text UCase function 271
string variables as 268 UCase$ function 271
text controls Undo command 56, 61
DHTML conversions and 203 undocumented functions 459
instantiating 14 uninstalling class libraries 423
text files unintended conversions 268
retrieving data from 90 union filters 99
text strings. See strings unique names 23
TextPlacement property 207 UNIX servers
third-party applications 327, 462 calling C functions from 310, 312
third-party DLLs 487, 488 developing applications for 326
third-party productivity tools xxv displaying reports 335
third-party reports 64 printing from 412, 416
third-party security tools xxvi selecting API files for 340
This 368 working locally from 336
time unknown object types 321
as literal value 275 UNKNOWN values 180
display formats for 274 UNKNOWN_TP type 472
valid values for 265, 273 unloading libraries 310
time controls 14 unresolved references 209
Toggle Breakpoint command 118, 123 unsigned long type 265
totals unstructured content xxiii
calculating cumulative 262 UPDATE queries 86
tracing 124, 126 updates xxvii
tracking values 125 updating DLLs 338, 488
transactions xxiii URLs
transient objects 45 getting most recent 497
data adapters as 76 user input 503
Factory service and 64 user interfaces 329, 494
transparent colors 215 user names 84, 351
Transporter technology. See search extensions in API function calls 343
trends xxvi prompting for 477
triggering events 156 specifying programmatically 495
Trim function 271 USER_TP type 472
two-sided printing 412 user-defined functions
type codes 199 calling 285
type definitions (typedefs) 265, 275 creating 282
Type keyword 265 exiting 287
Type mismatch errors 268 user-defined methods 250
type-declaration characters 253, 266 changing 60
types. See data types creating 58, 251
typing errors 267 debugging 128
typographic conventions deleting 61
(documentation) xxxv naming 58, 59
OLE Automation example for 306
saving 59

Index 555
user-defined types 275–276 storing 260
C functions and 315, 316 global variables for 113
described 265 methods and 29
user-defined variables 276 objects and 39
run-time 25
V testing assignment 44
V_CURRENCY type 199 testing for 396, 398, 405, 442, 449
V_DATE type 199 valid ranges 265, 274
V_DOUBLE type 199 variables and 37, 38
V_INTEGER type 199 Variable property 26
V_LONG type 199 variable type mappings 198–199
V_SINGLE type 199 variable-length arrays 264
V_STRING type 199 variable-length strings 268
validating connections 351 variables 18, 250
validating user names and passwords 496 See also global variables; local variables;
ValueExp property 82 object reference variables
calculated variables and 91 accessibility 125, 260
values accessing 39
assigning to parameters 347, 396, 398, 442 arguments as 283
assigning to variables 42, 43, 252 assigning data types to 53, 252, 266–267
changing dynamically 108 assigning null values 43
changing variable 284 assigning strings to 268
defining at design time 431 assigning to objects 24, 42
determining if current 399, 400, 401, 402, assigning to parameters 25, 28
403, 443, 444, 445, 446, 447, 448 assigning to variables 37, 38
displaying as hidden text 394, 440 assigning values 42, 43, 252
generating at runtime 104 attaching to classes 35
getting at runtime 28 as any class 36
getting current 347 with Component Editor 53
getting default 346 caution for using global 113
getting for code elements 31 changing values 284
getting incorrect 117 classifying data stored in 264
getting unknown 180 class-specific 24–29, 50
limiting access to 393, 439 constants vs. 267
monitoring 125 counters as 272
null 43, 44 creating 53–55, 261
placing limitations on 265 data rows and 81, 82
returning 282 declaring 260–263
from a single row 78, 80, 81 as global 261
from all rows 78 as local 262
from nonstandard sources 90 as private 26
from procedures 283 as public 26
from stored procedures 189, 192, 194 as specific type 266
object variables and 39 as static 24
subprocedures and 284 C++ sample code for 351
searching for specific 462, 505 type-declaration characters and 266
setting as defaults 347 user-defined types and 276

556 Programming e.Repor ts

variables (continued) Variant data type
defining for flat file connections 96, 97 See also AnyClass type
defining for multiple input filters 100, 102 arrays 263
defining output parameters as 194, 195 assigning 266
deleting 56 C functions and 314
derived classes and 20 converting to 277
displaying current values 125 overview 265, 267
dot notation and 39 procedures and 283, 284
editing 55 Variant variables 267
examining values 125 VARIANT_TP type 472
filtering 50 VarType function 268
frequently used 268 VBScript 202
initializing 66, 262 Verify Design command 117
inspecting 50–51, 125, 127 version information 492
instantiating classes and 18 version numbers 396, 404, 449
naming 53, 257 Vertical duplex mode 412
overview 29, 37, 52, 260 Vertical property 207
passing as arguments 284 View Browser Code command 208, 215
passing to procedures 43 View buttons 485
referencing 34, 39 view options 424, 458
restoring previous definitions 56 view processes 228–229
retaining values for 262 View_Click event 485
returning from external functions 310 Viewer xxvii, 156, 331, 474
scope 260 client applications and 335
setting in Component Editor 55 displaying browser code in 221
strings as 268 displaying reports 341, 411, 453, 466
testing assignment 44 launching local copy of 336
variants as 267 printing from 214
watching specific 127, 128 providing help for reports in 162–163, 165
Variables Browser command 126 running Requester API from 341
Variables command 56 setting location for 410, 452
Variables page (Component Editor) 25 setting up client stations for 466
adding variables 55 Viewer ActiveX controls
creating variables 53 See also ActiveX controls
inspecting variables 50 accessing Actuate Basic functions
opening 53 from 481
Variables window adding 474
monitoring in 125 methods calls for 491
opening 126 overview 327, 474
tracing object reference variables 126 Viewer directory 409
variant data viewing
changing case 271 classes 49
dates and 275 comments 49
numbers as 272, 273 context menus 157, 161
overview 267 controls 214
returning 283 custom browser code 208, 221
storage size and range 265 DHTML reports xxiii, 202

Index 557
viewing (continued) type codes for 199
error messages 117 Visual Basic programs
images 107 customizing Requester interface 383, 431
methods 51, 60, 111, 128 Visual C++ 475
online documentation xxxii Visual C++ compiler 466
predefined classes 35 Visual C++ forms 369
properties 51 visual classes 6
report parameters 394, 440 visual components
reports xxvii, 155, 424, 457 instantiating 6
ActiveX controls and 474, 485 visual distortion 208
API functions for 348 visual objects 156
in C++ applications 368 void type 319
in Encyclopedia volumes 477 volumes 326
in Visual Basic forms 362, 366 accessing 335, 351
in web pages 64, 202
locally 336, 349, 356 W
Requester API and 335, 336 Watch command 128
with Actuate Viewer 214, 341, 411, 453, Watch window 127
466 opening 128
with PDF converter 213–214 watches 127
with security restrictions 134 weak cursors (defined) 182, 194
variables 50, 125 Web applications 250
web pages 212 web browsers
viewing events 156–157 aligning output for 207
viewing methods 478 creating menus for 215, 218
viewing window (ActiveX) displaying online documentation in xxxii
changing views in 495 displaying reports in xxvii
displaying reports in 476, 479, 503, 504 example implementation for Internet
moving to specific page in 498, 499, 502 Explorer 215–222
resetting to first page 496 fixing visual distortion in 208
scaling reports for 505 guidelines for Netscape Navigator 222–
views 132 223
visibility. See scope scripting code for 205, 206
VisiblePageNumber constant 137 unresolved references in 209
Visual Basic 250 viewing code for 208
accessing Requester API from 360 web pages
ActiveX controls and 474 See also HTML reports; XML reports
creating Requester interface in 327 adding scroll bars 207
customizing Requester interface 366–368, changing scaling factor for 212
392, 437 debugging browser code for 208
developing with ActiveX controls 482 determining application context 211
generating and printing reports from 361– displaying reports for 64, 202
366 getting URLs for 497
initializing Requester API for 362 navigating through 484, 492, 493
running End User Desktop from 410, 453 specifying clipping for 206
sample application 354 viewing 212
selecting Actuate API for 337

558 Programming e.Repor ts

web sites XML extensions (AFC classes) 230
e.reporting solutions for xxii, xxiii XML formats
obtaining Actuate product updates xxvii converting to DHTML 228, 230, 234
securing xxv XML functions 232
Weekday function 274 XML properties 229, 230
whole numbers 272 XML reports
Windows applications 292, 293, 299 generating 504
building with ActiveX controls 482 XML tags 226
calling C functions for 310, 312 XMLAddContents property 232
choosing library files for 339 XMLAttribute setting 230
creating reports for 326, 328 XMLAttributes property 232
developing 474 XMLCharSet property 231
displaying reports in 336 XMLCustom setting 230
printing from 416 XMLDataProlog method 233
running Requester API 341 XMLDataProlog( ) method
specifying layouts for 505 overriding 227
Windows compilers 338 XMLDocType property 231
Windows file systems 476 XMLFileDescription property 231
Word documents 292 XMLFileExtension property 231
WordPad 299 XMLIndent property 232
word-processing applications 292, 304 XMLMimeType property 232
WordWrap property 208 XMLTag property 230, 232
XMLType property 230, 232
X Xor operator 255
XML data formats 226
XML Data property group 230 Y
XML data sources xxvii Year function 274
XML development tool xxvi
XML documents Z
document type definitions for 226 zip codes 268
format overview 227 zoom levels (web pages) 212
publishing Actuate reports as 229–236 zooming 505

Index 559
560 Programming e.Repor ts