Copyright: Actuate Software Corporation


  Actuate Software Development Kit

The Software Development Kit manuals describe how developers can use Actuate's programming interfaces to integrate features of the Actuate Reporting System into existing applications. Actuate offers several application programming interfaces:

•	Viewer and Desktop ActiveX controls

•	Requester API

•	Search Extension API

•	Report Server API

Viewer and Desktop ActiveX controls

The Viewer and Desktop ActiveX controls offer a high-level interface that simplifies the process of embedding Actuate reports in Windows applications. Using the Viewer ActiveX control, developers can build applications that display reports, print reports, and navigate efficiently through open documents. The Desktop ActiveX control adds the ability to generate new reports locally using current data. The relatively small number of access points and ActiveX control standardization shorten the development cycle for new applications.

Client API

Client API describes Requester API and Search Extension API.

The Requester API is a multiplatform interface for customizing, generating, displaying, and printing reports. A key feature of the Requester is its capability to modify report parameters before generating a new report. The Requester API works in conjunction with the Actuate End User Desktop or Actuate Viewer when generating or displaying reports. A subset of the Requester API, called the LRX API, works in conjunction with Live Report Extensions to print reports locally.

The Search Extension API extends the search feature of the Developer Workbench, Administrator Desktop, End User Desktop, LRX plug-ins, and ActiveX controls. Developers use the Search Extension API to transfer the results of a user-specified search to a third-party application.

Report Server API

The Report Server API allows developers to interact directly with the Report Server. Developers can access the Report Server's capabilities, including security and scheduling features that are unavailable through the other APIs.


About Actuate Software Development Kit

Actuate Software Development Kit documentation includes printed manuals, an installation card, online help, user documentation in Adobe Acrobat .PDF files, and release notes. Information about the product that could not be included 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 only to customers, telephone Actuate Customer Support. The engineers in Actuate Customer Support can also help you with the product, according to your service contract. The Customer Support telephone number, fax number and email information can be found in the printed materials in the product box.

A feature of the product are sample applications included with the SDK. The samples demonstrate how to use the APIs. The source code and other, related files required to create the sample applications are included as part of the SDK.

The printed and online documentation includes the following manuals.

For information about	See the following
Installation	Installation card
Late-breaking information about the software and documentation	Release notes
Overview of the Actuate ActiveX Controls Developer information and examples Actuate ActiveX Controls Reference
Overview of the Actuate Requester API and Search Extension API Developer information and examples Actuate Requester API Reference Actuate Search Extension API Reference
Overview of the Actuate Report Server API Developer information and examples Actuate Report Server API Reference


About the API features

The Actuate ActiveX controls, Requester API, and Report Server API each provide different features and levels of access to Actuate reports. The following table lists the functional capabilities for each Actuate interface.

Task	ActiveX	Requester	Search Extension	Report  Server
Generate reports	Yes (1)	Yes (2)		Yes
Print reports	Yes	Yes		Yes
Configure printer	Yes (3)	Yes		Yes
View reports	Yes	Yes (4)
Build a GUI application	Yes
Modify parameters		Yes
Schedule execution and printing reports				Yes
Distribute results			Yes	Yes
Security features				Yes
Encyclopedia management				Yes
Custom features				Yes
(1) 	Requires Desktop ActiveX control for local report generation.

(2) 	Requires local instance of the End User Desktop.

(3) 	Requires user input.

(4) 	Requires a local instance of the Viewer or End User Desktop.


Choosing which API to use

This section contains guidelines on choosing which API to use. The functionality of each API is summarized in the preceding table. The following are other characteristics to consider when choosing the appropriate API.

•	Level of abstraction--high-level APIs are easier to use and require shorter development cycles. The Actuate ActiveX controls have the simplest, easiest interface to use, followed by the Requester and the Search Extension, and then the Report Server.

•	User interface--Actuate ActiveX controls are the easiest tools to use to create Windows-based GUI applications to view and generate Actuate Reports.

•	Operating environment--the Requester and Report Server APIs operate on Windows and UNIX systems; ActiveX and Search Extension are Windows-specific.

•	Client/server or local model--ActiveX, Requester, and Report Server APIs provide access to the Report Encyclopedia. Actuate ActiveX controls and the Requester API can also work locally. Search Extension API works only with the client applications.

•	Feature group--all the APIs support basic reporting, but the Report Server API accesses the broadest range of the Actuate reporting features.

See also

When to use Actuate ActiveX controls
When to use the Requester API
When to use the Search Extension API
When to use the Report Server API


When to use Actuate ActiveX controls

If you want to embed Actuate reporting into your Windows application, the Actuate ActiveX controls are the easiest to implement. The Actuate ActiveX controls might be the optimal choice if you are developing an application with these requirements:

•	Environment--Windows-based application, either new or existing

•	Feature set--view, execute, and print reports with the Desktop ActiveX control, view and print reports with the Viewer ActiveX control

•	Development resources--short design cycle using 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.


When to use the Requester API

The Requester API is a choice for client applications running on different platforms and operating systems. Client applications often use the Actuate Viewer in conjunction with the Requester API for viewing and navigating reports. Use the Requester API if you are developing an application with these requirements:

•	Environment--varied platforms and operating systems

•	Feature set--view, execute, and print reports, and modify report parameters programmatically

•	Development resources--moderate design cycle

The capability of the Requester API to access the attributes and values of report parameters is an important feature. Often, developers use both the Requester and Report Server APIs in applications that must modify report parameters.

The LRX API is much smaller than the Requester API and is better suited to printing reports using the Live Report Extensions for Netscape's browser or Microsoft's Internet Explorer. The LRX API can only print reports locally. To work with the Report Server, you must use the Requester API.


When to use the Search Extension API

The Search Extension API is a tool developers use to customize the search feature of the Developer Workbench, Administrator Desktop, End User Desktop, LRX plug-ins, 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 Excel.


When to use the Report Server API

The Report Server API is a powerful interface for accessing the Report Server functionality. Use the Report Server API if you are developing an application with these requirements:

•	Environment--varied platforms and operating systems

•	Feature set--full Report Server functionality

•	Development resources--long design cycle that allows a learning curve

Using the Report Server API, you can integrate the Actuate reporting features into your existing applications and automate high-volume or routine reporting tasks.


About the Actuate Reporting System

Developers use the Actuate® Reporting System Release 3 to design, generate, and distribute both online and traditional reports throughout the enterprise. Online reports are both easy to use and more valuable than traditional reports. Actuate reports solve complex data access and formatting problems and can scale to support thousands of users.

The following summary describes the products in the Actuate Reporting System.

Product name	Use
Actuate Developer Workbench	Object-oriented application used by professional developers to design, build, and distribute report object designs and components throughout the enterprise. The Actuate Basic Language and Actuate Foundation Class Library support extensive customization capabilities.
Actuate End User Desktop	Application used by end users to request, generate, view, and print Live Report Documents on networked client systems. The ReportQuery™ capabilities enable seamless transfer of data from an Actuate report to any productivity tool or analysis tool.
Actuate Viewer	Application for end users to find, view, and print report documents. The ReportQuery™ capabilities are also part of the Actuate Viewer.
Actuate Administrator Desktop	Application for system and network administrators to manage and control one or more Actuate Report Servers.
Actuate Report Server	Server application that generates Live Report Documents, manages them in the Report Encyclopedia®, and makes them available to users.
Actuate ReportCast™	Actuate Live Report Extension extends Microsoft Internet Explorer and Netscape Navigator with report viewing and printing.
	Actuate Web Agent transforms the Report Encyclopedia into a dynamic, secure web site. Provides the foundation for ReportCast Channels and seamless integration with other web sites.
Actuate Software Development Kit	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 is generated, displays and prints reports, and configures report print setup. 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 Report Server API implements common Report Encyclopedia tasks, integrates Report Server features into existing corporate applications, automates routine or time-consuming tasks, and implements new feature groupings for custom business processes. Access the Report Server API using C++.
Actuate Viewer is included with all products except Actuate Report Server, Actuate ReportCast, and Actuate Software Development Kit.


About Actuate ActiveX Controls Guide

The Actuate ActiveX Controls Guide provides information for incorporating the following functionality, prebuilt by Actuate, into your Windows applications:

•	Open and view a report (Desktop and Viewer ActiveX controls)

•	Navigate the report (Desktop and Viewer ActiveX controls)

•	Run a report executable (Desktop ActiveX control only)

•	Print a report (Desktop and Viewer ActiveX controls)

Actuate ActiveX Controls Guide includes the following sections.

•	Introduction. This section provides an overview of the Actuate APIs, the features of the Actuate APIs and presents guidelines for choosing among them.

•	Actuate ActiveX Controls user guide. This section 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.

•	Actuate ActiveX Controls reference. This section provides an alphabetical reference with descriptions and programmatic details for the Actuate Viewer and Desktop ActiveX controls.

See also

When to use Actuate ActiveX controls


Online documentation

The information in the printed manuals is also available as online books in Adobe Acrobat .PDF format and in the online help system for the Actuate products. For products without a Windows interface such as the Actuate Report Server and the Actuate Web Agent, we provide HTML help files.

See also

Using online manuals


Using online manuals

The online manuals do not install automatically with the product. On the product CD, you find those files in the Pdf directory. Open the introductory .PDF file to get an overview of the manuals. Copy this file and the files for each book you want to be able to use online to your local drive. 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 your cursor over the page number, not the topic.

The .HTML files install automatically with the product. These files can be viewed with standard browsers.


Online help

Actuate products provide both context-sensitive online help about the product and report-specific online help about the report you are viewing. For a detailed description of how online help corresponds to and compares with the printed manuals, see the Introduction in the online help system. The Actuate Reporting System also makes it possible for developers to create customized report-specific online help.

See also

Using context-sensitive online help
Using the Actuate online help system
Using report-specific online help


Using context-sensitive online help

Sections from the printed manuals have been linked directly to the software interface to make relevant information available while you work. Dialog boxes that need additional explanation about how to use them have a help button. To access online help, use the Help menu in the menu bar.

An alternative method is to use the F1 key.


Using the Actuate online help system

The Actuate online help system consists of two separate windows. The window on the right displays the contents of the online help topics. The window on the left displays the Table of Contents or the Index of the online help system.

The tabs at the bottom of the left-hand window allow you to switch views between Table of Contents, Find, and Index. The buttons at the top of the window change according to the tab you selected at the bottom.

The following illustrations show an example of the Index and the results of an Index search.

The following illustration shows the results of the search as they appear in the left-hand window. In order to view the topic in the right-hand window you need to select the topic from the list and press View. The topic displays in the right-hand window.


Using report-specific online help

During the design phase, report developers have the option to include report-specific online help. For example, the report developer can add comments to give further detail about specific report objects or to explain how calculations were created.

For detailed information on report specific online help see Using online help in a sample report.


Typographical conventions

The following table describes the typographical conventions.

Item	Convention	Example
File names	All uppercase letters	DETAIL.ROI
Glossary terms	Initial reference italicized	.ROI file
Key combination	A + sign between the keys means to press both keys at the same time	Ctrl + Shift
Actuate Basic keywords	Bold	Dim
Menu items	Capitalized. No boldface	File
Submenu items	Separated from main menu item with small arrow	File→New


Syntax conventions

The following table describes the symbols used to present the syntax of Actuate Basic language elements.

Symbol	Description	Example
[]	Optional item	[Alias<alias name>]
<>	Argument you must supply	<expression to format>
{}	Groups two or more mutually exclusive options or arguments	{While | Until}
|	Separates mutually exclusive options or arguments in a group	Exit {Do | For | Function | Sub}


Actuate ActiveX Controls reference

The Actuate Desktop and Viewer ActiveX controls conform to the Microsoft standard for ActiveX (OCX) controls. This reference describes the methods available for use with the controls. Some methods are available only with the Desktop control and are marked as such.


AboutBox

Opens the Actuate ActiveX About dialog box.

Syntax

void AboutBox()

Description

This method opens the Actuate ActiveX About dialog box. The dialog box displays the Actuate ActiveX version number and copyright information.


BundleReportInstance

Bundles a report executable (.ROX) with a report document (.ROI) file.

Syntax

BOOL BundleReportInstance(LPCTSTR fileName)

fileName

The name of the bundled report.

Description

This method bundles the report executable (.ROX) file into the report document (.ROI) file that is displayed. BundleReportInstance saves the bundled report under the specified file name.

Return value

Indicates success or failure of the bundle:

•	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


CancelReport (Desktop ActiveX control only)

See also

Cancels generation of a report.

Syntax

void CancelReport()

Description

This method stops generation of a report previously requested with RunReport or RunReportWithParameters. Call during report generation.


See also

RunReport (Desktop ActiveX control only)

RunReportWithParameters (Desktop ActiveX control only)


CanRunReport (Desktop ActiveX control only)

See also

Indicates whether a report executable can be run.

Syntax

BOOL CanRunReport()

Description

A report can be generated if a report executable is open and there is no current report execution running. The return value can be used to enable or disable user interface elements.

Return value

Indicates whether a report can be generated at the current time:

•	TRUE if a report executable can be run

•	FALSE if a report executable cannot be run


See also

OpenReportExecutable (Desktop ActiveX control only)

RunReport (Desktop ActiveX control only)


CloseReportExecutable (Desktop ActiveX control only)

See also

Closes the report executable.

Syntax

BOOL CloseReportExecutable()

Description

This method closes the open report instance, if there is one, and the report executable. Call this method after the report executable is finished running.

Return value

Indicates success or failure of the operation:

•	TRUE if the method succeeded

•	FALSE if the method failed


See also

OpenReportExecutable (Desktop ActiveX control only)


CloseReportInstance

See also

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.

Return value

Indicates success or failure of the operation:

•	One if the method succeeded

•	Zero if the method failed


See also

OpenReportInstance

OpenReportExecutable (Desktop ActiveX control only)


ConnectToServer

Establishes a Report Server connection.

Syntax

BOOL ConnectToServer(LPCTSTR hostName, LPCTSTR userName, LPCTSTR password)

hostName

The name of the host computer where the report server is running. The report server 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.

Description

To access reports stored on Actuate's Report Encyclopedia, the client application must first connect to the report server as a user with the necessary read permissions.

This method makes the necessary server connection and validates the username and password. If you attempt to open a report on a server before calling this method, a dialog box is displayed for entering the user name and password. All other methods use this connection to exchange information with the report server. Accessing reports stored in the native file system does not require this connection.

Return value

Indicates the success or failure of the connection request:

•	TRUE if the connection succeeded

•	FALSE if the connection failed


CurrentPage

Returns the current page number in the view window.

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.

Return value

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 procedure has no effect.

Return value

Indicates success or failure of the page change:

•	TRUE if the change succeeded

•	FALSE if the change failed


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 returns a description of the last error encountered, not the result of the last method executed. For more information on using GetLastError, see Handling error conditions.

Return value

A text string describing the error condition. An empty string if no errors have occurred.


GoToPage

Changes the view to a specific page number of the report.

Syntax

BOOL GoToPage(long Page)

Page

The number of the desired page.

Description

Use this method to move quickly through large Actuate reports when you know the content location.

Return value

Indicates success or failure of the change:

•	TRUE if the change succeeded

•	FALSE if the change failed


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 procedure has no effect.

Return value

Indicates success or failure of the page change:

•	TRUE if the change succeeded

•	FALSE if the change failed


LoadResource

Loads the NLS resource DLL.

Syntax

BOOL LoadResource(LPCTSTR localeName)

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 dialog boxes and error messages are displayed in the language specified by localeName.

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

To view loaded language resources, your system must be setup for the appropriate language. For example, you can load a Japanese resource DLL under US English Windows, but it will not display correctly.

Return value

Indicates success or failure of loading the file:

•	TRUE if the file was loaded

•	FALSE if the file was not loaded


MailReportInstance

Brings up the mail dialog box with the current report instance attached.

Syntax

BOOL MailReportInstance()

Description

This method brings up the mail dialog box with the current report instance attached.

Return value

Indicates success or failure of attaching the report:

•	True if the .ROI was attached to an e-mail

•	False if the .ROI was not attached to an e-mail


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 procedure has no effect.

Return value

Indicates success or failure of the advance:

•	TRUE if the page change succeeded

•	FALSE if the page change failed


OpenReportExecutable  (Desktop ActiveX control only)

See also

Opens an executable report file.

Syntax

BOOL OpenReportExecutable (LPCTSTR reportName)

reportName

The fully qualified name of the report file (.ROX), expressed as a Windows path and filename; the rotp format is not valid in this context.

Description

This method opens a report executable in preparation for report generation. Client applications use report executables to generate reports with updated data. Only one report executable can be open at a time.

The Desktop ActiveX control can only read report executables 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 the Report Server, or to extract report executables from the server for local execution, use the Client API or Report Server API in conjunction with the Desktop ActiveX control. For more information on using the Client API or Report Server API, see Actuate Client API Guide or Actuate Report Server API Guide.

Return value

Indicates success or failure of the request to open the report:

•	TRUE if the file open succeeded

•	FALSE if the file open failed


See also

RunReport (Desktop ActiveX control only)

CloseReportInstance

CloseReportExecutable (Desktop ActiveX control only)


OpenReportInstance

See also

Opens a report saved on the Report Encyclopedia or the client file system.

Syntax

short OpenReportInstance (LPCTSTR reportName)

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 Report Encyclopedia if the reportName is formatted in the rotp format. For example, to open a report called forecast in the Eastern Region folder on the Paradise Report Encyclopedia, enter "rotp://Paradise/Eastern Region/FORECAST.ROI" as the reportName. The server enforces access permissions before opening the report, so the user must have read permission to open the requested report. If this method is called without an active server connection, it opens a dialog box that prompts for a username 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 on specifying local or server reports, see Report files and the Actuate ActiveX controls.

Return value

Indicates success or failure of the request to open the report:

•	One if the file open succeeded

•	Zero if the file open failed


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. Developers typically use this method to display report page information, like page x of y, where y is the page count.

Return value

The number of pages in the current view.


PreviousPage

Moves to the previous page of the report.

Syntax

BOOL PreviousPage()

Description

This method is a navigation aid for client applications. Developers typically use this method to page backwards through the report. At the first page, this procedure has no effect.

Return value

Indicates success or failure of the page change:

•	TRUE if the page change succeeded

•	FALSE if the page change failed


Print

See also

Opens the standard Windows print dialog box for report printing. Use in C++ applications only.

Syntax

void Print(BOOL showDialog)

showDialog

Specifies print dialog box usage:

•	TRUE opens the standard Windows print dialog box

•	FALSE prints with default print parameters

Description

With this method, users 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

See also

Opens the standard Windows print dialog box for report printing. This method supersedes Print.

Syntax

void PrintReport(BOOL showDialog)

showDialog

Specifies print dialog box usage:

•	TRUE opens the standard Windows print dialog box

•	FALSE prints with default print parameters

Description

With this method, users 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


RunReport (Desktop ActiveX control only)

See also

Runs the open report executable to generate a new report instance.

Syntax

BOOL RunReport()

Description

This method runs the open report executable and generates a report instance in the local file system. Before calling this method, open the report executable with OpenReportExecutable.

Before running the report, RunReport opens the parameter dialog box 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.

Return value

Indicates success or failure of report generation:

•	TRUE if the report executed successfully

•	FALSE if the report execution failed


See also

OpenReportExecutable (Desktop ActiveX control only)

CancelReport (Desktop ActiveX control only)


RunReportWithParameters  (Desktop ActiveX control only)

See also

Runs the open report executable to generate a new report instance.

Syntax

BOOL RunReportWithParameters(LPCTSTR parameterFile)

parameterFile

The fully qualified name of the report parameter file (.ROV) to open.

Description

This method runs the open report executable 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 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 that 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.

Return value

Indicates success or failure of report generation:

•	TRUE if the report executed successfully

•	FALSE if the report execution failed


See also

OpenReportExecutable (Desktop ActiveX control only)

CancelReport (Desktop ActiveX control only)


SaveAsHtml

Saves the open report in HTML format.

Syntax

BOOL SaveAsHtml(LPCTSTR fileName)

fileName

The filename for HTML output.

Description

This method converts the open document to HTML format and saves it to disk.

Return value

Indicates success or failure of report generation:

•	TRUE if the conversion was successful

•	FALSE if the conversion failed


SearchWindow

Opens a window for searching a report.

Syntax

BOOL SearchWindow()

Description

This method opens an Actuate search window. Users can search objects in the open report for specific values or ranges. For example, from the search dialog box a user could search the company-name field for a specific company. The Actuate control search window is identical to the Viewer search window.

Return value

Indicates success or failure of the request:

•	TRUE if the request succeeded

•	FALSE if the request failed


SetScaleFactor

Sets the scale factor for the view.

Syntax

BOOL SetScaleFactor(long factor)

factor

The scale factor for the view, stated as a percent.

Minimum: 25%
Maximum: 400%

Description

This method is typically linked to a view control that lets users zoom in and out on reports. The default scale factor is 100%.

Return value

Indicates success or failure of the request:

•	TRUE if the scale factor request succeeded

•	FALSE if the scale factor request failed


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 provides a summary or overview of the report contents. It displays the sorting and grouping structure of the report and facilitates quickly moving between sections by selection of the desired branch. When finished, users can close the dialog box using standard Windows procedures.

Return value

Indicates success or failure of the request:

•	TRUE if the table of contents request succeeded

•	FALSE if the table of contents request failed


Actuate ActiveX Controls user guide

Actuate ActiveX controls include two powerful controls you can use in custom reporting applications--the Actuate Viewer ActiveX control and the Actuate Desktop ActiveX control. Actuate ActiveX controls are an optional product that is purchased separately from the Actuate Developer Workbench but used in conjunction with it.

ActiveX controls, formerly known as OLE or OCX controls, are Microsoft Windows components for embedding prebuilt functionality into your custom applications. Using the Actuate ActiveX controls, you can add many of the Actuate Viewer and End User Desktop features to custom Windows applications.

See also

Features
The ActiveX development environment
Report files and the Actuate ActiveX controls
Actuate ActiveX methods by programming task
Visual Basic example
How to install Actuate ActiveX controls


Features

Actuate ActiveX controls have a programmatic interface for incorporating the following functionality, prebuilt by Actuate, into your Windows applications:

•	Open and view a report (Desktop and Viewer ActiveX controls)

•	Navigate the report (Desktop and Viewer ActiveX controls)

•	Run a report executable (Desktop ActiveX control only)

•	Print a report (Desktop and Viewer ActiveX controls)

Applications built with the Viewer ActiveX control may 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. Modern development tools make this process fast and easy.


The ActiveX development environment

ActiveX is an interface recognized by the Windows operating system that simplifies the process of embedding custom controls in your application. Once registered with the operating system, ActiveX controls are available to developers at design time and to applications at run time.

See also

Adding the Actuate ActiveX controls to your application
Adding the Actuate ActiveX controls to Visual Basic
Adding the Actuate ActiveX controls to C or C++


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. The Actuate control features are accessed 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.


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.


Report files and the Actuate ActiveX controls

When using the controls, you work with the following files:

•	Report parameter values (.ROV) file

The parameter file contains the parameter definitions and values used when generating a report. Developers create and modify parameter files programmatically using the Requester API.

•	Report executable (.ROX) file

The report executable file is the vehicle for creating a new report instance that contains current report information. The report executable uses the report parameter file, when specified, to set the parameter values used during execution.

•	Report document (.ROI) file

The report document is the viewable report that appears in the ActiveX viewing window. The Actuate reporting system creates a new report document each time the report executable is run.

See also

Specifying local file names for Actuate reports
Specifying Report Server file names for Actuate reports


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


Specifying Report Server file names for Actuate reports

Files on a Report Server are specified in the rotp format:

rotp: [//<server>]/<path>/<filename>[;<version>]

server

Optional specification of the Report Server name. The default is the current connection.

path

The full path to the file, using UNIX path separators.

filename

The complete file name, including the .ROX, .ROV, or .ROI extension.

version

Optional specification of the file version. The default is the latest version.

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 specific version number of the file
<version name>	The specific version name of the file


Actuate ActiveX methods by programming task

The Actuate ActiveX controls implement several groups of programming tasks:

•	Opening and closing a report instance

•	Navigating and viewing the report instance

•	Running a report (Desktop control only)

•	Printing, mailing, and saving a report

•	Handling error conditions

See also

Opening and closing a report instance
Navigating and viewing the report instance
Running a report
Printing, mailing, and saving a report
Handling error conditions


Opening and closing a report instance

The Actuate controls can display reports stored in the Report Encyclopedia or the native file system. To open and view a report stored in the Report Encyclopedia, the application must connect to the server 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 will open a dialog box for entering a username and password.

The following methods implement server connections and report access:

Method	Description
ConnectToServer	Establishes a report server connection, which is used by other methods to access, view, and print reports stored in the Report Encyclopedia.
OpenReportInstance	Opens a report, either in the Report Encyclopedia 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 using:

•	Table of contents window

•	Search window

•	Go to page

•	Page forward and back

The following table summarizes the navigation and viewing methods available:

Method	Description
AboutBox	Opens the Actuate ActiveX About dialog box.
CurrentPage	Returns the current page number of the open report.
FirstPage	Resets the report view to the first page.
GoToPage	Opens Actuate's Go To Page dialog box.
LastPage	Sets the report view to the last page.
NextPage	Advances the report view to the next page.
PageCount	Returns a page count for 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 viewed report.
TableOfContents	Opens the Actuate table of contents window.


Running a report

The Desktop control runs reports only on the native file system. The first page of the new report instance automatically displays in the Actuate ActiveX control window when the report is available.

The following table summarizes the methods for running reports:

Method	Description
OpenReportExecutable (Desktop ActiveX control only)	Opens a report executable (.ROX) file. Used in conjunction with RunReport to generate a new report.
RunReport (Desktop ActiveX control only)	Opens the standard parameter screen, runs the open report executable, and displays the generated report in the view window.
RunReportWithParameters (Desktop ActiveX control only)	Runs the open report executable using a parameter file and displays the generated report in the view window.
CanRunReport (Desktop ActiveX control only)	Indicates whether a report executable is open and can be run.
CancelReport (Desktop ActiveX control only)	Cancels a currently executing request to run a report.
CloseReportExecutable (Desktop ActiveX control only)	Closes the current report instance, if there is one, and the report executable.


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 (.ROX) with a report document (.ROI) file
MailReportInstance	Brings up the mail dialog box with the current report instance attached
PrintReport	Opens the Windows print dialog box for operator action or prints with system defaults. Supersedes the Print method
SaveAsHtml	Saves the open report in HTML format for viewing with a browser


Handling error conditions

Most ActiveX methods indicate success or failure by returning a boolean result code, either TRUE or FALSE. If a method returns FALSE, use GetLastError to retrieve a text description of the problem. GetLastError returns a description of the last error encountered, not the result of the last method executed.

To assure correct handling of errors:

1	Test the return value for all methods that return a result code.

2	If a method returns FALSE, call GetLastError to retrieve a description of the problem.

3	Present the text description returned by GetLastError to the end user, if appropriate.

For more information, see GetLastError.


Visual Basic example

This section describes a sample Windows application developed in Visual Basic. The application uses the Desktop ActiveX control to implement the following reporting features:

•	Open an existing report for viewing

•	Run a report executable and view the new report

•	Print the screen

•	Page forward

•	Page backward

•	Open an Actuate table of contents

The sample application has an opening screen that contains the opening window for the Desktop ActiveX control and seven control buttons.

The center window is the primary Desktop control element and serves as the viewing window for the open report instance. In this simple example, the Desktop control always opens a report called forecast when the View or Run button is selected. Each of the buttons around the viewing area invokes additional viewer functionality by making calls to the Desktop control interface.

See also

Building the sample application
Visual Basic code segment descriptions
Running the sample application


Building the sample application

Build the sample application as follows:

•	Add the Desktop control to the toolbox.

•	Add the Desktop control buttons and window to the application.

•	Program window and button events in Visual Basic.

The next sections describe how to perform these tasks.

See also

Adding the Actuate Desktop ActiveX control to the toolbox
Adding the Desktop control and button controls to your application
Write Basic code for window and button events


Adding the Actuate Desktop ActiveX control to the toolbox

To include a custom control to your application, first add it to the toolbox. From the Project menu select Components. In the Components dialog box, place a check mark next to Actuate Desktop Control and click OK. The Actuate Desktop control then appears in the toolbox along with the other controls:


Adding the Desktop control and button controls to your application

Select the Desktop ActiveX control and draw a viewing window in your application. Using the Button control, add control buttons around the viewing area to implement the functionality you desire. In this example, there are seven buttons that implement the specified features.


Write Basic code for window and button events

By doubl-clicking on each button, add Visual Basic code to link Windows events to Actuate functionality. 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 allows users to page forward through the document.

Prev_Click

The Prev button uses PreviousPage() to back up one page in the report. This is a simple navigation tool used for paging backward through the document.

Print_Click

The Print button opens the standard Windows dialog box for user input. By passing an argument of FALSE, the open document prints with default Windows printer settings.

Run_Click

The Run button invokes two Desktop control methods. First it opens the report executable with OpenReportExecutable() and then runs the report with RunReport(). When completed, the new report displays in the window.

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 the desired 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 report server connection first. The display is zoomed out 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 SDK

•	Actuate End User Desktop or Developer Workbench

The End User Desktop and Developer Workbench include the sample database and drivers used by the sample report.

You can use the sample application two ways. If you just want to try it out, simply launch the Desktop executable. To modify the code, recompile, and run the application, open the project file and work in the Visual Basic development environment. The following procedures explain each option.

To run the sample application:

1	Using the Windows Explorer or File Manager, navigate to the SDK Examples folder. If you installed the ActiveX Control in the default location, the fully qualified filename is
<drive>:\Actuate\SDK\ActiveX\Examples.

2	Locate the Windows executable, Desktop.exe, and double click on it. This opens the sample application and sets the default directory.

3	Try out the sample application.

To modify, compile, and run the sample application:

1	Using the Windows Explorer or File Manager, navigate to the SDK Examples folder. If you installed the ActiveX Control in the default location, the folder is <drive>:\Actuate\SDK\ActiveX\Examples.

2	Locate the Visual Basic project file, Desktop.vbp, and double click on it. This launches Visual Basic, opens the sample application, and sets the default directory.

3	Compile and run the application using standard Visual Basic procedures.

4	Experiment with the sample application.

If you have trouble opening the sample report, check the following:

•	Make sure sfdata is set up as an ODBC database on your machine. For more information on setting up sfdata, see Chapter 1, "Building your first report," in Building Reports.

•	Verify that Visual Basic is using the Examples directory as the default. The sample application looks for Forecast.roi and Forecast.rox in the default directory.


How to install Actuate ActiveX controls

If you plan to ship an Actuate ActiveX control with your application, your install program needs to copy the necessary files and register the Actuate ActiveX control as follows:

1	Create a directory structure for the control as follows:

2	Copy the following files to the bin directory:

•	AXDESK.DLL--ActiveX Desktop control

•	AXVIEW.DLL--ActiveX Viewer control

•	LEAD51N.DLL--Third-party graphics control

3	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, see Choosing API files.

4	Copy the file TRNSINT to the etc directory.

5	Copy the following Actuate DLLs to the system32 directory of Windows NT or the system directory of Windows 95:

•	ACRSXXXX.DLL

•	ACRXXXX.DLL

For more information, see Choosing API files.

1	Copy the following Microsoft DLLs to the system32 directory of Windows NT or the system directory of Windows 95:

•	MSVCRT.DLL

•	MSVCIRT.DLL

•	MFC42.DLL

•	MFCANS32.DLL

•	OLEPRO32.DLL

•	OC30.DLL

2	Copy the following third-party DLLs to the system32 directory of Windows NT or the system directory of Windows 95:

•	WINRPC32.DLL

•	EZRPCW32.DLL

•	WIDGE32.DLL

•	GSWAG32.DLL

•	GSW32.EXE

•	GSWDLL32.DLL

For proper operation of the ActiveX Control, the graphics server files (gsw*.*) must be in the system32 directory of Windows NT or the system directory of Windows 95. Also, the client machine must not have duplicate or additional graphics server files in the following locations:

•	Any directory included in the PATH, other than the system32 directory of Windows NT or the system directory of Windows 95

•	Current directory for your application

•	Directory that contains the .ROI and.ROX files

3	Register the Actuate control using regsvr32. For the Desktop product the command-line syntax for registering is

regsvr32 <drive> : <path> AXDESK.DLL

4	If your application uses the Actuate server, set the following registry values:

HKEY_LOCAL_MACHINE\SOFTWARE\Actuate\ReportServer\
AC_CLIENT_HOME = <drive> : <path>\ActiveX

See also

Choosing API files


Choosing API files

The ActiveX controls utilize dynamic link libraries (DLL) and compiled libraries (ROX) files 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.

See also

API file name conventions
API file versions


API file name conventions

The following table summarizes the naming conventions for files used by the ActiveX controls

DLL	File Name
Report Server API DLL	ACRSxxyy.DLL • xx = Report Server API version • yy = Visual C++ version (4.1, 4.2, or 5.0) Example: ACRS3041.DLL
RogueWave DLL	ACRxxyy.DLL • xx = RogueWave version • yy = Visual C++ version (4.1, 4.2, or 5.0) Example: ACR7042.DLL
Compiled library	AFCxxx.ROX xxx = Compiled library version Example: AFC853.ROX
.


API file versions

When choosing the correct API file for your application, follow these guidelines:

•	Always use the DLL from the release you are using.

•	Choose the DLL compiled for the Microsoft VC++ version you are using.

•	Use the ROX file used to compile the reports the ActiveX Control will open. You can copy multiple ROX versions to the afc folder when necessary.

•	Refer to the release notes for the most up-to-date information on DLL or ROX files.

The following table summarizes the DLL and ROX files for each Actuate SDK release:

SDK Release	VC++ 4.2	VC++ 5.0
3.0.6	ACRS3242.DLL AFC774.ROX	N/A
3.1	ACRS3342.DLL AFC846.ROX	N/A
3.1.1	ACRS3342.DLL AFC853.ROX	N/A
3.2	See the release notes for ROX file name and DLL file name updates ACRS3442.DLL AFCxxx.ROX	ACRS3450.DLL AFCxxx.ROX1
For those applications that use ActiveX with the Requester API, include the following Requester API DLL along with the Report Server DLL shown above.

SDK Release	VC++ 4.2	VC++ 5.0
3.0.6	Use ACRQ3042.DLL file dated before 4/20/98 ACRQ3042.DLL	N/A
3.1 to 3.1.1	ACRQ3042.DLL	N/A
3.2	N/A	ACRQ3050.DLL