Copyright: Actuate Software Corporation


  Actuate Developer Workbench

Actuate Developer Workbench documentation includes printed manuals, an installation card, online help, user documentation in 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 among the printed materials in the product box.

A feature of the product is an Example folder that contains numerous report examples. Each of the sample report folders contains a variety of files often including a text file that discusses how the report was developed and how the example works.

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 Actuate reporting concepts How to build your first report How to design reports using the graphical user interface Glossary
Viewing, running, finding, and printing reports
Actuate Basic programming fundamentals Conceptual information about how to program with Actuate Foundation Classes Programming in the Windows environment
Actuate Basic statements and functions
Actuate Foundation Classes, their properties, variables, and methods
Overview of the Actuate Requester API and Search Extension API Developer information and examples Actuate Requester API Reference Actuate Search Extension API Reference


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.

See also

Online help
Online documentation
Syntax conventions
Typographical conventions


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}


  Building Reports

Building Reports provides information for using the Developer Workbench graphical tools to design reports.

Building Reports includes the following sections.

•	Introduction. This section provides overviews of the Actuate reporting system.

•	Building your first report. This section provides a tutorial for building a sample report.

•	Concepts. This section explains the basic report-building concepts, such as object-oriented programming and the report-building process.

•	The Developer Workbench environment. This section provides a high-level overview of the Developer Workbench tools and interface.

•	Customizing the Developer Workbench environment. This section describes how to customize the Developer Workbench tools.

•	Query data streams. This section describes how to define a query data stream to select the database data the report will use.

•	Using the Design Editor. This section describes how to use the Design Editor to work with components in a report design.

•	Working with sections. This section describes the various section components and how to use them in a report design.

•	Working with frames and controls. This section describes frames and controls and how to use them in a report design.

•	Presenting data in graphs. This section describes the various graph controls and how to use them in a report design.

•	Presenting data in crosstabs. This section describes how to design crosstab reports.

•	Designing page layouts. This section describes the various page components and how to use them in a report design.

•	Designing report parameters. This section describes how to create report parameters for which users specify, at run time, values that determine the data to display in a report.

•	Working with component libraries. This section describes how to publish reusable components in a library.

•	Building an HTML report. This section describes how to build an HTML report that can be viewed in a Web browser.

•	Terminology Map. This section lists the common report terms and gives the equivalent Actuate terms.


Viewing a report

The following topics are available. To view the topics in order, use the Browse button (>>) in the Help window's toolbar.

•	Opening and viewing a report

•	Moving around in a report

•	Using links to other Windows applications

•	Zooming

•	Using screen arrangement options

•	Using online help in a sample report

•	Using context menus while you view a report


Opening and viewing a report

Opening and viewing a report that is stored in a file system (on a stand alone machine or a network file server) or in the Report Encyclopedia involves a somewhat different sequence of tasks. Once the report is open, the viewing features are the same whether you view a report stored in the file system or in the Report Encyclopedia.

See also

Opening and viewing a report in a file system
Viewing a Report Encyclopedia report
HTML Reports


Opening and viewing a report in a file system

To help you get started, the Actuate products include sample reports. Viewing these reports introduces you to the active viewing features, unique to Actuate reports.We will be using DETAIL.ROI as an example in this help file.

See also

How to open a sample report from a file system


How to open a sample report from a file system

1	Choose File→Open.

The Open dialog box appears.

2	From the Files of Type list, choose Reports (*.ROI) to find the sample report, DETAIL.ROI. Go to the Actuate Examples directory. For instance, the default examples directory for the End User Desktop is
c:\actuate\eudt\examples.

3	Select DETAIL.ROI.

4	Choose Open.

DETAIL.ROI opens. The following illustration shows the first page of DETAIL.ROI in Actuate End User Desktop. With this sample report, you can explore many of the viewing capabilities.

Use the split box at the top of the vertical scroll bar or the left of the horizontal scrollbar to create a split window. View different parts of the report simultaneously with a split window. To remove splits from a window, double-click the split bar.


Viewing a Report Encyclopedia report

You can view a report stored in a Report Encyclopedia if you have access to the Report Encyclopedia and if you have been granted the read privilege for the report. For more information about privileges, see Assigning privileges for Report Encyclopedia folders and files.

See also

How to open a report in a Report Encyclopedia for viewing


How to open a report in a Report Encyclopedia for viewing

1	Log in to the Report Encyclopedia if you have not already done so.

The Navigator appears.

2	Locate and select the report you wish to open.

3	Press the right mouse button to access the context menu.

4	Choose View Report from the context menu, as shown in the following illustration.

The report appears.

Demand paging

When you view a report that is stored in a Report Encyclopedia, the disk pages stream to your computer on an as-needed basis. For example, if you specify page 103 as the page to go to, the server sends only that page. This method of paging is called demand paging. Demand paging optimizes resource usage on both the Report Server and the client. In addition, on-demand paging reduces network traffic, thereby enhancing system performance.


HTML Reports

An HTML report document file (.ROW) is stored in the Report Encyclopedia and created with the Report Server, Developer Workbench, End User Desktop, or Administrator Desktop from a report executable (.ROX). You can view an HTML report using a web browser without using the Actuate LRX (Live Report Extension).

To view an HTML report, open it the same way you would a report document (.ROI). Acutate starts your default web browser and displays the HTML report in the browser.


Moving around in a report

There are a number of ways to move around in an Actuate report. You can

•	Page through the report sequentially, or go to the first or last page using the paging commands.

•	Go to a specific page by specifying a page number.

•	Use hyperlinks, if provided by the report developer, to go from one part of the report to another part in the same or different report.

•	Use the report's table of contents to traverse the content hierarchy.

•	Use the search feature to find and go to specified report data.

See also

Using the paging commands
Using Go To
Using hyperlinks
Using the table of contents


Using the paging commands

The View menu includes various paging commands: first page, previous page, next page, and last page. Actuate reports store data in a highly compressed form. It is possible to move very quickly through large Actuate reports. Paging sequentially through the report is an option, but it is more convenient and faster to choose specific paging commands. Use either toolbar buttons or menu items to access the paging commands.


Using Go To

If you happen to be familiar with the page layout of the report or you are working from a printout to find particular report pages, use Search→Go To or the Go To Page button to access a specific page by number.

Go to Page brings up a dialog box where you type the number of the page to display.


Using hyperlinks

During the design process, the report developer has the option to provide hyperlinks in any Actuate report. Hyperlinks make it easy to move from information in one part of a report to related information in another part of a report. Not all reports include hyperlinks.

See also

How to use a hyperlink


How to use a hyperlink

1	Pass the mouse over a hyperlinked field. The cursor changes to a small hand to show that the field contains a hyperlink. In the following illustration, the hyperlink for "Boston Office" is active. Look on page 2 of DETAIL.ROI to find this example. Clicking the hyperlink takes you directly to the main entry for the Boston Office.

2	Click the hyperlinked field to go directly to the related field. The following illustration shows the field to which the hyperlink connects.

Other hyperlink techniques exist in some reports. For example, each section on a summary page in a report can be linked by a More button to a detailed section of the report. In the more detailed report, the developer can insert More and Back buttons to facilitate navigating through the pages of that part of the report. The following illustration shows a page of FORECAST.ROI with More and Back buttons.

To see several examples of hyperlinks, open the FORECAST.ROI and work with the hyperlinks provided on pages 1 and 2 of that example report.


Using the table of contents

Reports typically contain a generated table of contents. You can view the table of contents with sections collapsed or expanded depending upon what level of detail you want to see. The following illustration shows the table of contents, partially expanded, for the sample report, DETAIL.ROI.

As the table of contents for DETAIL.ROI shows, the Eastern Region Sales Forecast includes three offices. Each office includes a group of sales representatives and each of those representatives has a group of customers. Each customer, in turn, has one or more orders.

In some cases, the report design includes a table of contents with additional items to highlight particularly important sections.

See also

How to access the report's table of contents
How to use the report's table of contents
How to go to an item displayed in the table of contents


How to access the report's table of contents

 Choose View→Table of Contents or press the TOC icon.

The table of contents for the report appears. The following illustration shows the table of contents for the sample report, DETAIL.ROI.


How to use the report's table of contents

1	To expand the table of contents to show more levels of information, click +. The following illustration shows the Boston Office folder expanded to display sales representatives in that office.

2	To collapse the table of contents to show fewer levels of information, click -.


How to go to an item displayed in the table of contents

Double-click the item in the table of contents.

The report displays the chosen item.


Using links to other Windows applications

Actuate reports can display and manipulate data from Windows applications that support Object Linking and Embedding (OLE). For example, report developers can use OLE to link a Word document, an Excel graph, a spreadsheet, or a Paintbrush picture to an Actuate report. What the developer is able to provide depends to some degree on the particular OLE object and the applications installed on your computer. For example, if a report contains a link to an Excel graph, the graph appears only if Excel is installed on your computer. Otherwise, a grey box appears in place of the graph.

See also

The difference between linked and embedded objects
Editing linked and embedded objects
OLE automation


The difference between linked and embedded objects

During the report design phase, the report developer has the option to link or to embed objects such as Excel spreadsheets or Paintbrush pictures to the report design. If the data is in the form of a linked OLE object, the data remains in an file maintained by the application that created it. In that case, what is in the Actuate report is a reference to that file. If the object is embedded, the data itself is in the Actuate report.

Linked objects can be used by several applications, but the data such as a spreadsheet is kept in one place. Embedded objects are not shared, requiring more effort to maintain updated data.


Editing linked and embedded objects

Depending upon the application used to create the original object, it is possible to manipulate the linked object in the report. For example, if the linked object is an Excel bar graph, printing or viewing the data in a variety of ways, such as a pie chart or a ribbon graph, is an option.

Any change in the view is for that session only. The change is not stored or saved in the original document. Nor are you able to save this variation in the Actuate report. A linked OLE object is external to the report you are viewing.


OLE automation

Report developers use OLE automation to make it possible for you to run another application from within an Actuate report. Typically, accessing the other application is transparent for the end user. For example, the developer can provide a button on a report that accesses Microsoft Excel and transfers data to the report.


Zooming

Zooming in and out of a report makes it easier to view specific sections. The scaling range is from 25% to 400%. The following illustrations show a report at 50% and at 200%. The example shown is in the End User Desktop. If you are working in another product in the Actuate Reporting System, your menus and toolbars are somewhat different. However, the same capabilities exist.


Using screen arrangement options

The Window menu provides the option to cascade or tile windows. The windows can contain different reports or different views of a single report.

See also

Using New Window
Using Cascade
Using Tile


Using New Window

New Window lets you add report windows. Use this feature if you need multiple views of the same report. Depending upon how you have used the Window menu options, the windows appear one on top of another until you use Cascade or Tile to arrange them.


Using Cascade

The cascade commands cascades existing windows and any subsequent windows you open. In the following illustration, some windows are cascaded and some are not to permit comparison.


Using Tile

Select Tile to arrange file windows you have open. The first three windows tile horizontally. The fourth window divides the main window into four report windows. Subsequent windows continue to subdivide the screen. The following illustration shows two tiled windows.


Using online help in a sample report

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 specific calculations were created.

See also

How to access report online help


How to access report online help

1	Select the object in the report for which you want online information. In this example, select one of the dates, 4/15/95 or 4/27/95, on page 2 of DETAIL.ROI.

2	Press the right mouse button to access the context menu, which displays options provided by the report developer.

3	Select Help on that menu. The help item explains what the Needed/ Forecast heading on that column means.

 Another way to access the online help is to select the help icon. Then use the help icon to click on the object to see if the report developer provided help on that item.


Using context menus while you view a report

Context menus are an option the developer can choose to provide. If context menus have been provided by the developer, first select the object, then press the right mouse button to access the context menus. By default, Actuate reports provide the context menus "Default action" and "Help." If, however, the report developer does not write code for these context menu items, they will not do anything.

The report developer can add other context menu items. For example, the following illustration shows a context menu that appears when you hold down the right mouse button over the number, 1855, in the sample report, DETAIL.ROI. Here the developer has chosen to provide the option "Evaluate Discount."

It is important to remember that context menu actions are an option provided by the developer. Although you see them in the examples shown here, they are not available in every report.


Running a report

The following topics are available. To view the topics in order, use the Browse button (>>) in the Help window's toolbar.

•	Using an existing report vs. running a report

•	Running a report on a client system

•	Running a report in the Report Encyclopedia

•	Creating a request to run a report in the Report Encyclopedia

•	Checking the status of report requests


Using an existing report vs. running a report

Report developers typically create and distribute report documents, which other users can view and print. Sometimes, however, developers also distribute report executables, which other users can run--at any time, and as often as they want--to generate reports with updated data.

You can run reports in all Actuate client products except the Viewer, which you use only with report documents that are already generated.

About using reports

A report document contains objects that store both the report structure and data. When the report developer ships a report, the report executable and the data are bundled with the file. When you view that report, no database access is required because the data is within the report.

Reports you receive in that format cannot be run to refresh the data. You can, however, use searching techniques to find and display selected data from the report. For more information about searching, see Searching for and exporting report data.

About running reports

A report executable contains compiled Actuate Basic code that specifies how Actuate generates a report and what data it retrieves for the report. The advantage of running a report executable is that the resulting report contains the most current data.

When you run the report executable, Actuate draws from data sources originally selected by the report developer. Therefore, you need access to the data source. The data source could be shipped with the report by the developer or, more likely, you access a database on a server.

You can optionally bundle the report executable (.ROX) with the report document, if the report developer enables this option. You select the option to bundle the report executable in the Requester dialog when you run a report. For information on using the Requester, see Specifying report parameters.

Bundling the report executable creates a larger report document (.ROI), but allows you to move the report executable and report document as a single file. This makes sending reports to remote users and viewing reports on remote systems easier.

Creating HTML reports

Depending on the report executable, generating a report document can create an HTML report document that you can view with your web browser.

When you generate an HTML report on a client system, a subdirectory is created and the HTML files that make up the HTML report are in placed in the subdirectory. You can view the HTML report by opening the file INDEX.HTML in your web browser.

When you generate an HTML report in the Report Encyclopedia, an HTML report file (ROW) is created. When you open this file, Actuate starts your default web browser and displays the HTML report in your browser.


Running a report on a client system

Running a report that is stored on a client system provides different options and therefore involves different tasks from running a report in a Report Encyclopedia. When you run a report on a client system, the report is generated immediately. When you run a report in a Report Encyclopedia, you can schedule the time and day to generate the report, even specify if the report should be generated regularly. For information about running a report in a Report Encyclopedia, see Running a report in the Report Encyclopedia.

Running a report on a client system might create a directory that contains an HTML report. For more information, see Creating HTML reports.

See also

How to run a report executable on a client system
Monitoring report generation
Viewing pages during report generation


How to run a report executable on a client system

1	Choose File→Open.

The Open dialog box appears.

2	From the Files of Type list, choose Executables (*.ROX) to display only report executables in the Open dialog box.

3	Choose the executable you want to run.

The Factory window appears.

4	Choose Run to start the report generation process.

The Requester dialog box appears.

5	Choose OK to accept the default parameter values, or enter parameter values to narrow the range of data Actuate retrieves. For information about how to use the Requester, see Specifying report parameters.

The Factory begins generating the report.

6	To stop report generation at any time, choose Halt.

7	Choose Close after the report is finished running.


Monitoring report generation

The Factory window displays the status of the generation process and the number of the page being generated. The title bar displays the name of the report. The Viewer title bar displays "[In Progress]" while the report is being generated. When the Factory finishes generating the report, only the file name appears.


Viewing pages during report generation

Typically, when you run a report object executable file, the Viewer displays the report as soon as the first page is generated. There is one exception. If you set the "Bundle Rox in Roi" output parameter in the Requester dialog box to True, the Viewer displays the report only when the Factory completes generating. For information about using parameters, see Specifying report parameters.

As the report is being generated, you can use all the Viewer features except for the Table of Contents and Search features. These features are unavailable because they rely on all the data in a completed report.

See also

Understanding checkpoints
Refreshing the report in the Viewer


Understanding checkpoints

As the Factory generates the pages of the report, it writes the completed pages to the report at designated checkpoints. The checkpoints occur after the completion of the 1st, 5th, 10th, 25th, and 50th pages and every 50 pages after the 50th.

The Viewer displays the portions of the report that have been written to a file when you manually refresh the report. For information about refreshing the report, see Refreshing the report in the Viewer.


Refreshing the report in the Viewer

To refresh a report in the Viewer as the Factory generates the report, choose any of the paging commands--First Page, Previous Page, Next Page, or Last Page--from the toolbar or the menu bar. Sometimes when you choose a paging command, the report in the Viewer is not immediately refreshed. The delay occurs when the Factory has not reached a new checkpoint since the last refresh. For example, if the last page of the displayed report is 50, the report is not refreshed until the Factory has finished processing the 100th page.

Use the Page information in the Factory window to refresh the report at the appropriate times. For optimal results, choose a paging command immediately after a checkpoint.


Running a report in the Report Encyclopedia

To access a Report Encyclopedia, your system administrator should have assigned you a user name and password and set up your access rights. If you have access to a Report Encyclopedia, you can run any report executable stored on that server for which you have been granted read and execute privileges. To see what executables are available, use the Navigator to log into the Report Encyclopedia and view the report files stored there.

Running an executable on a server gives you more options than running it on a client system. These options are collectively called a report request. Depending on the report executable, when you run it, you might create an HTML report file (.ROW). For more information, see Creating HTML reports.


Creating a request to run a report in the Report Encyclopedia

The following list summarizes the options you can set for a report request. For each option in this list, there is a corresponding section with detailed, step-by-step instructions.

•	Specify parameter values to filter the data to retrieve, set formatting options, processing options, and so on, during report generation.

•	Save the parameter values to a report parameter values file to reuse whenever you want to run the executable with the same values.

•	Schedule the executable to run immediately, on a regular basis, or on selected dates.

•	Distribute the completed report to a folder in the Report Encyclopedia and set privileges.

•	Request that the server send notification messages, including email notification, to selected users or user groups when the report is completed.

•	Request that the server print the report when it is completed.

See also

How to start a new report request
Specifying report parameters
Saving parameter values
Scheduling the time to run the executable
Distributing a report
Setting notification options
Printing a completed report
Viewing a completed report


How to start a new report request

1	Locate and select the report executable in the Report Encyclopedia.

2	Press the right mouse button to display the context menu associated with the executable.

3	Choose New Request.

The Requester dialog box appears. It contains six tabs, each corresponding to options you can specify with the report request. The following illustration shows a sample Requester dialog box.


Specifying report parameters

Parameters let you enter criteria when you run a report. These parameters, defined by the report developer in the report design, can control aspects of report generation such as

•	Records retrieved

•	Sort sequence of data

•	Output format

If you do not specify any parameter values, Actuate uses the default values defined by the report developer.

Using the default interface

The way you enter parameter values depends on whether the report developer used Actuate's default interface or built a custom dialog box for gathering parameter values. If the developer used the default interface, you enter parameter values next to the parameter names.

Using a custom Requester dialog box

If the report developer created a custom dialog box for gathering parameter values, an Edit Parameters button appears at the bottom of the Parameters page. Choose this button to launch the custom dialog box in which you enter and edit parameter values. The Parameters page displays the values as
read only.

See also

Understanding parameter types
Optional parameters
Required parameters
Ad hoc parameters
Specifying a single value for an ad hoc parameter
Specifying a QBE conditional expression for an ad hoc parameter


Understanding parameter types

There are three types of parameters:

•	Optional

•	Required

•	Ad hoc


Optional parameters

Optional parameters do not require that values be entered. Most report parameters are optional. They are a convenient way for users to narrow the scope of the report, if desired. If you do not specify any values, default settings are used. Optional parameters appear in the parameter list without a trailing asterisk, as the following illustration shows.


Required parameters

Certain parameters must have a value supplied in order for the report to run. For instance, a user name and password are required to access a database. A required parameter is indicated in the Requester by an asterisk after the parameter name.

A required parameter typically has a default value supplied by the developer. Those default values appear in the Requester as gray text. In the following example, both output parameters are required, but default values have been supplied so that the report runs.

If you change the Output File Name parameter from the default, this output file name overrides the output name specified in the Distribution tab.


Ad hoc parameters

Ad hoc parameters narrow the scope of the data retrieved by a SQL query. A SQL query is designed by the report developer to retrieve data from a database. By entering values for ad hoc parameters in the Requester, you modify the WHERE clause of the SQL statement to retrieve data that meet certain criteria.

An ad hoc parameter is indicated in the Requester by an iconic "A" next to the parameter name. Ad hoc parameters can be either optional or required.


Specifying a single value for an ad hoc parameter

Typically, you supply a single value for ad hoc parameters. When you change that value, the data retrieved will change. In the following illustration, the ad hoc parameter value "C" results in a sales detail report that lists all customers with a credit ranking of "C." In SQL terms, setting the parameter to "C" narrows the selection of customer data with the clause "WHERE customers.creditrank LIKE 'C%'".


Specifying a QBE conditional expression for an ad hoc parameter

You can use a QBE conditional expression instead of a single value. The conditional expression can include items such as lists and ranges. For example, you can set the credit rank parameter to C,D and the purchase volume parameter to 1000-2000, as the following illustration shows.

Actuate adds the following clause to the SQL query:

WHERE (customers.creditrank LIKE 'C%' OR customer.creditrank LIKE 'D%')

AND customers.purchasevolume BETWEEN '1000%' and '2000%'


Saving parameter values

After you set the parameter values in the Parameters page of the Requester dialog box, you can save them to a report parameter values (.ROV) file to reuse whenever you want to run the report executable with the same values. To do so, modify the settings in the Values page of the Requester.

By default, Actuate writes the parameter values to a file and stores that file in a temporary folder. When the report is generated, Actuate deletes the temporary parameter values file.

See also

Maintaining versions of the parameter values file


Maintaining versions of the parameter values file

When you save the parameter values to a file, you can choose to create a new parameter values file or replace a previous version. The first option is useful for creating different parameter values files for different sets of parameter values. For example, if you regularly generate two sales reports from a single report executable--one that reports sales in Boston, and the other, sales in New York--create a parameter values file for each report.

If you save different versions of the parameters file, successive files created from the same executable will be saved with the same name with incrementing version names. The report documents generated from these parameter values files have the same version names. With this autoversioning capability, you can maintain a chronologically ordered set of versions of the same report items.

The following illustration shows how the Report Encyclopedia maintains different versions of report items.


Scheduling the time to run the executable

Use the Schedule tab in the Requester to schedule when a report request should be run. You can schedule the executable to run immediately, once at a specified time, on a recurring basis, or on any specified schedule. If you do not specify a schedule, Actuate runs the executable immediately.

The following are three examples of report scheduling.

Example 1: Scheduling a report to run once

Example 2: Scheduling a report to run daily for a specified week

Example 3: Scheduling a report to run on a specified weekday for a specified period, excluding holidays

See also

Example 1: Scheduling a report to run once
Example 2: Scheduling a report to run daily for a specified week
Example 3: Scheduling a report to run on a specified weekday for a specified period, excluding holidays
Creating complex report-generation schedules
Setting the priority at which to run the executable


Example 1: Scheduling a report to run once

You want a report on this week's new accounts after close-of-business Friday. To set this schedule, choose Once, then enter the settings as shown in the following illustration:


Example 2: Scheduling a report to run daily for a specified week

You want an hourly report on new account activity every day during the last week of September at a sales conference. The first report is run at 11:00 am, and the last, at 10:00 pm. To set this schedule, choose Schedule, then the Edit Schedule button. Enter the settings as shown in the following illustration:


Example 3: Scheduling a report to run on a specified weekday for a specified period, excluding holidays

You want a weekly report that is generated once every Friday during the fourth quarter, except on holidays. To set this schedule, you would set up a weekly run for the specified duration, then exclude the Fridays that are holidays. In this example, November 29 falls on a Friday and is a company holiday, so you need to exclude this day from the schedule.

To set the schedule, use the following steps.

1	Choose Schedule, then choose the Edit Schedule button.

2	Enter the settings as shown in the following illustration.

3	Choose Add to save the schedule information.

The text box displays the schedule information you set, that is, how often the report runs, the start and end dates and times. The calendar on the right displays the selected dates in a highlighted color.

Now that you have finished setting up the recurring schedule, you can exclude November 29 from it.

To exclude this day from the schedule, do the following:

1	Click the right arrow button next to the calendar until November is displayed. The following illustration shows the schedule information for the month of November.

2	Select November 29 on the calendar, then choose Delete.

The date is excluded from the schedule. It is no longer highlighted in the calendar, and the information in the text box contains an additional clause "except 11/29/96."


Creating complex report-generation schedules

For examples of creating complex schedules, see the following topics:

Example 2: Scheduling a report to run daily for a specified week

Example 3: Scheduling a report to run on a specified weekday for a specified period, excluding holidays

These examples are just two examples of how you can use the Edit Schedule dialog box to create complex schedules. You can create even more complex schedules by adding more conditions. For example, you can select a date from the calendar, select the 1 Day option, then specify time and frequency values for a run request on that particular day. Your choices are reflected in the text box of the Edit Schedule dialog box, so you can always keep track of the scheduling conditions.


Setting the priority at which to run the executable

Reports can be run at three priority levels: high, medium, or low. These priorities represent the order in which reports are run if there are many requests in the queue.

The priority levels you can specify depend on what the administrator assigned as the maximum priority you can set for requests. If, for example, the administrator set your maximum request priority at medium, you can run reports only at the medium and low priorities.


Distributing a report

Use the Distribution tab in the Requester to specify where and how to distribute reports produced in the Report Encyclopedia. You can specify the following:

•	A different name for the report. By default, Actuate uses the same root name as the executable used to generate the report. Changing the default report name in the Parameters tab overrides the name specified in this tab.

•	A folder in the Report Encyclopedia in which to place the report. By default, the report is stored in the folder where the executable resides.

•	Whether the report should be a new version or should replace existing reports with the same name. By default, a new version is created.

•	A version name for the report. By default, a version number is used, for example, "Version 1" or "Version 2."

•	Read, write, delete, execute, and grant privileges to different users and roles. If you do not assign privileges, users have the default privileges specified in your privilege template. For information about privileges, see Assigning privileges for Report Encyclopedia folders and files.

See also

Using report versions


Using report versions

If you choose to save version results, successive report instances created from the same report request will all be saved under the same name with incrementing version names. Versions allow you to keep a chronologically ordered set of versions of the same report. If you choose to replace previous results, all previous versions of the report are deleted.


Setting notification options

Use the Notification page in the Requester to choose users and groups to be notified when the report is completed. By default, only you and the administrator are notified when the report has been generated.

The left pane of the Notification page displays the available users and groups for the Report Encyclopedia. Users and groups are set up by the Report Server administrator. Ask the administrator to set up a group that contains users to whom you regularly send a particular report.

See also

Types of notification
Report Server notification
Email notification


Types of notification

There are two types of notification:

•	Report Server notification

•	Email notification

The type of notification a user gets depends on the user's notification preference.


Report Server notification

When Report Server notification is in effect, reports appear in the Completed folder as soon as they are generated. Actuate uses the Report Server notification when the user's notification preference is set to "Completed folder notice." Only the Report Server administrator can set the notification preference.


Email notification

Users receive email notification of a completed report if their notification preference is set to "Email notice." Only the Report Server administrator can set the notification preference.


Printing a completed report

Use the Print tab in the Requester to specify where and how to print the completed report. By default, Actuate does not print the report.

You can specify the following printing options:

•	The file name if Print to file is selected.

•	The network printer to use to print the report.

•	Printer properties, such as paper size, paper orientation, duplex, number of copies, and so on. By default, the printer uses the default properties you set for the selected printer. If you did not set default properties for the printer, the printer uses the system-level defaults set by the system administrator. For more information about setting printer properties, see Setting printer properties in the Report Encyclopedia.

•	The pages to print. You can print a single page, a range of pages, or all the pages.


Viewing a completed report

After you receive notification of a report request completion, you can view the report from its notification in the Completed folder, or directly from the report document in the destination folder you specified when you created the request. To view the report, select View Report from its context menu.

For information about interactive viewing features, see Viewing a report.


Checking the status of report requests

The Report Encyclopedia stores status information about report requests in the Requests folder. You can view this information at any time by opening the Requests folder and the folders it contains.

If you are using the Actuate Viewer, you see only the Completed folder that contains requests that have been processed. If you are using Actuate client software other than the Actuate Viewer, for example, the Actuate End User Desktop, you can see scheduled and active requests.

See also

How the Report Server manages report requests
Checking the Requests subfolders


How the Report Server manages report requests

Report requests can be in one of three states, in the following order: scheduled, active, or completed. Corresponding to each state is a folder. As a report request progresses from one state to the next, it moves to the corresponding folder.

A request appears in the Scheduled folder once it has been submitted. That request moves to the Active folder when it is time for the report to be run. Once the request has been processed, the request moves to the Completed folder, where it remains until you delete it.

For example, if you scheduled a report to be run at 12:00 am on August 15, 1996, the request appears in the Scheduled folder until 12:00 am on August 15, 1996, at which time the request moves to the Active folder. The request stays in the Active folder until the Factory finishes processing it, at which time the request moves to the Completed folder.

A report is not always run at the scheduled time. The time it is actually run depends on several factors, for example, the priority level of a request, the availability of Factory processes, the number of requests in the queue, and so on. You can specify the priority of your request, but only the administrator can control the number and schedules of concurrent Factory processes.


Checking the Requests subfolders

Checking the contents of the Scheduled, Active, and Completed folders tells you the status of requests you scheduled. Requests scheduled by other users are not visible to you, just as your requests are not visible to others. The Completed folder, however, contains requests you submitted and requests that other users submitted and notified you about. Only the administrator can monitor all requests managed by the Report Server.

See also

Contents in the Scheduled folder
Getting more details about a scheduled request
Editing a scheduled request
Deleting requests in the Scheduled folder
Contents in the Active folder
Getting more details about an active request
Deleting requests in the Active folder
Contents in the Completed folder
Changing the number of completed requests displayed
Viewing reports in the Completed folder
Creating requests in the Completed folder
Getting more details about a completed request
Deleting requests in the Completed folder


Contents in the Scheduled folder

The Scheduled folder contains the requests you scheduled to run at a later date and time. This folder is not visible when you use the Actuate Viewer.

You can view the following information about the scheduled request in the right pane of the Navigator window:

•	Name of the report executable that will be run.

•	User who submitted the request.

•	Date and time the report executable is to be run.

•	The priority of the request. By default, the priority levels are indicated as follows: 200 = low, 500 = medium, 800 = high.

The following illustration shows the contents in a user's Scheduled folder, and the context menu associated with scheduled requests.


Getting more details about a scheduled request

To get more details about a request in the Scheduled folder, right-click the scheduled request icon or the name of the job, then choose Properties from the context menu. The Properties dialog box that appears displays the information you specified when you created the request: the parameter values used to run the report, the schedule, distribution, notification, and printing information.


Editing a scheduled request

You can edit a request in the Scheduled folder at any time. You can change the parameter values, schedule, distribution, notification, and print options. To do so, right-click the scheduled request icon or the name of the job, and choose Properties from the context menu. Then edit the information in the Properties dialog box that appears.


Deleting requests in the Scheduled folder

You can delete requests any time before the request is processed. To do so, right-click the scheduled request icon or the name of the job, then choose Delete Scheduled Request. You cannot recover a deleted request.

After a scheduled request is completed, the request remains in the scheduled requests folder for at least 24 hours. After 24 hours, the scheduled request remains in the folder until all the completed notices related to the scheduled request are removed from the completed requests folder.


Contents in the Active folder

The Active folder contains the requests that are ready to be processed or are currently being processed. This folder is not visible when you use the Actuate Viewer.

You can update the information in the Active folder by using the Active folder's context menu. Right-click the Active folder and select Refresh.

You can view the following information about the active request in the right pane of the Navigator window:

•	Job name as maintained by the Report Server. This name is a combination of the date and time of the scheduled run and the file version name.

•	Name of the report executable that is ready for processing or is currently being processed.

•	User who submitted the request.

•	Date and time the generation process was started, if it has started.

•	Priority of the request. By default, the priority levels are indicated as follows: 200 = low, 500 = medium, 800 = high.

•	Name of the generated report.

•	Name of the Factory process used to generate the report.

The following illustration shows the contents in a user's Active folder.


Getting more details about an active request

To get more details about a request in the Active folder, right-click the active request icon or the name of the job, then choose Properties from the context menu. The Properties dialog box that appears displays additional general information about the request.


Deleting requests in the Active folder

You can delete requests while they are in the queue. To do so, right-click the active request icon or the name of the job, then choose Delete Active Request. You cannot recover a deleted request.


Contents in the Completed folder

The Completed folder contains the requests that have been processed. You can view the following information about the completed request in the right pane of the Navigator window:

•	Job name as maintained by the Report Server. This name is a combination of the date and time of the scheduled run and the file version name.

•	Name of the report executable that was run.

•	Name of the generated report.

•	User who submitted the request.

•	Date and time the report was completed.

•	Number of pages in the report.

The following illustration shows the contents in a user's Completed folder, and the context menu associated with completed requests.

The Completed folder contains requests that have been processed, including those that failed to generate a report. Failed requests are represented by this icon:  To get information about why the request failed, right-click the icon, then select Properties from the context menu.


Changing the number of completed requests displayed

You can limit the number of requests that are visible in the Completed folder by changing the Display settings in the Completed folder Properties dialog. Right-click the Active folder and select Properties to display the Properties dialog. Select either Display all completed requests, or set the number of requests to display.


Viewing reports in the Completed folder

To view a report in the Completed folder, right-click the request icon or the name of the job, then choose View Report from the context menu. The report opens in the Viewer.


Creating requests in the Completed folder

To create request to run a report from the Completed folder, right-click the request icon or the name of the job, then choose New Request from the context menu. The Requester dialog box appears. The Report Encyclopedia runs the report displayed in the General tab.

To create a request that uses the same parameters as the completed request, right-click the request icon or the name of the job, then choose Retry completed request from the context menu. A confirmation dialog box appears. Choose Yes to resubmit the request.


Getting more details about a completed request

To get more details about a request in the Completed folder, right-click the request icon or the name of the job, then choose Properties from the context menu. The Properties dialog box that appears displays additional information, such as the time the report was run, the size of the finished report, the priority it was scheduled with, the full path names of the executable and report files, and so on.


Deleting requests in the Completed folder

Requests remain in the Completed folder until you delete them. To do so, right-click the request icon or the name of the job, then choose Delete Completed Request. You cannot recover a deleted request.

To delete all the requests in the Completed folder, use the Requests folder's context menu. Right-click the Requests folder and select Delete completed notices.


Searching for and exporting report data

The following topics are available. To view the topics in order, use the Browse button (>>) in the Help window's toolbar.

•	About Actuate report searches

•	Using basic searching techniques

•	Executing a single-object search

•	Executing a multiobject search

•	Using operators and wildcards in search expressions

•	Specifying data to display in the Results page

•	Using search definition files

•	Exporting report data


About Actuate report searches

Using the Actuate report search feature you can

•	Perform complex searches on the data in an Actuate report document.

•	Save the search criteria and search settings as a search definition.

•	Export all or part of the data from an Actuate report to a file.

•	Transfer report data to other applications.


Using basic searching techniques

You begin a search by selecting a searchable object in a report. Then, you add the selected object to the Search dialog box and specify the value to find.

See also

How to find searchable objects


How to find searchable objects

As you move the cursor around the report, you notice the cursor shape changes to an arrow with an active symbol at the tip. The change in cursor shape indicates that an object is searchable.

The following illustration shows a searchable object in the sample report, DETAIL.ROI.

Use a single mouse-click to highlight or select a searchable object. The search cursor lets you select only one object at a time. For information about searching multiple objects, see How to select multiple objects to search.


Executing a single-object search

This section walks through the process of executing a single-object search. In the following example, the objective is to find all companies whose names start with the word Advanced in the sample report, DETAIL.ROI.

How to execute a simple search

1	Select a searchable object from the report. In this example, select a company name such as "TeleBoards Co."

You can select any company name because the purpose of this step is to specify the object--CompanyName--to search, not the object's value. You specify the value to search in a later step.

2	 Choose Search→Find or the Search toolbar button to activate the Search dialog.

The Search dialog box appears.

3	To use the selection as criteria for your search, choose Add Selection.

4	In the Value column, specify the value to search. In this example, type Advanced*.

The asterisk (*) is a wildcard that specifies you want to find all values that contain "Advanced" in the first part of the string, and any number of characters after that.

5	Choose Search to start the search process.

Matches to the search target appear in the Results page in order of their occurrence in the report.

See also

Using search results


Using search results

The Results page displays the matches found in the report. You can go to the page containing any of those matches directly from the Results page. The following example shows the matches retrieved from a search for all company names that begin with Advanced, and how to use the results to go to specific matches in the report.

How to use the Results page to go to a specific match in the report

1	Select the match you wish to see.

2	Choose Go To or double-click the selection.

The report becomes active and displays the matching value. If you selected Advanced MicroSystems Co. as shown in the previous illustration, the page containing the company name, Advanced MicroSystems Co., appears. The company name is highlighted.

3	To go to another match in the report, use the Next, Previous, or Go To button in the Results page.


Executing a multiobject search

You can select multiple objects from a report to add to the search criteria to execute a more specific search. For example, instead of just searching for company names that start with "Advanced", you can search for company names that start with "Advanced" and that are located in Boston.

The number of conditions on which you can search is limited only by the number of objects in the report. Each condition you add to the search criteria adds an And logical operation. For example, if you specify three objects and values for the search, the search expression in effect is condition1 And condition2 And Condition3. There is a match only if all conditions are true.

Depending on your report design, some multiobject searches result in no matches even if data matches the search values. Actuate displays a warning message when you select objects that will result in no matches.

The following sections explain the basic techniques for a multiobject search, and provide two examples of executing multiobject searches.

See also

How to select multiple objects to search


How to select multiple objects to search

There are two ways to select multiple objects from a report.

•	Hold down the Shift key and use mouse clicks to select each object you wish to include in the group of objects.

•	Use the left mouse button and drag a rubberband to select the area containing the group of multiple objects.

Using either method, when you release the mouse button, all the selected objects are included in your search.

See also

How to add objects to a search
How to execute a multiobject search
Example 1: Searching for specified values on two objects
Example 2: Adding and deleting objects from a multiobject search


How to add objects to a search

Actuate provides the capability to add objects to your search after you begin searching.

1	Leave the Search dialog box open.

2	Return to the report behind it to select other objects.

3	Choose Add Selection after selecting each object.


How to execute a multiobject search

The following examples walk through the process of executing two multi-object searches. The process you follow is the same as the process for single-object searching, but the results are more specific.

Example 1: Searching for specified values on two objects

Example 2: Adding and deleting objects from a multiobject search


Example 1: Searching for specified values on two objects

In this example, a search finds orders of item code MP1632 that exceed 500 units. DETAIL.ROI is the report used in the example.

1	Select searchable objects from the report. In this example, rubberband several objects that include both the item code and the quantity objects.

The rubberband draws a boundary around the search objects. For the selection to be successful, the entire object must be within the rubberband area. To deselect a previously selected object, double-click somewhere in the white space around the report.

2	To narrow the search criteria, delete the objects you want to exclude from the search. In this example, delete ItemDescription and Price.

3	Specify the values to search. In this example, type the values as shown in the following illustration to retrieve orders for item code MP1632 whose quantity exceeds 500.

4	Choose Search to begin the search process.

The search results appear in the Results page.


Example 2: Adding and deleting objects from a multiobject search

This example shows how to add and delete objects from the search, as well as how to modify the values to search. DETAIL.ROI is the report used in the example.

1	Select searchable objects from the report. In this example, select the following objects under the following column headings: Code, Description, Quantity and Price.

2	Choose Search→Find to open the Search dialog box.

3	Choose Add Selection.

As the following illustration shows, the item code, description, quantity, and price objects (indicated as Integer Controls) are added to the search. The names that appear in the Name column are not the same as the descriptive column headings that appear in the report. The names in the column are the names of the objects as assigned by the report developer at design time.

4	To delete an object, select it and choose Delete Entry. In this example, delete ItemDescription, IntegerControl, and IntegerControl1.

5	To add another object, leave the Search dialog box open and select a new object from the report behind it. In this example, add the Extension Price object to the search.

6	After selecting the objects on which to search, you can specify the values to search. For this example, change the IntegerControl2 (which represents the extension price) value in the Value column to > 100000.

The search now looks for orders of item code MP1632 which have an extension price greater than $100,000.

7	Choose Search to execute the search.

The search results appear in the Results page. Results for multiobject searches are formatted in columns, as the following illustration shows. You can resize the width of the columns.


Using operators and wildcards in search expressions

Use operators and wildcards in search expressions in the Value column of the Search page to narrow or widen your search.

To search an integer control, an operator compares numbers. To search a text control, an operator compares letters. For instance, the expression "> Moore" as the value for the SalesRep object would find all the names that fall after "Moore" in the alphabet.

See also

Using operators and symbols in a search expression
Using wildcards in a search expression
Using patterns in a search expression
Searching for the characters ?,*,#, and [ ]
Using nonprinting ASCII characters in a search


Using operators and symbols in a search expression

Actuate accepts the following operators and symbols.

Symbol	Meaning
=	Equals or is the same as
>	Greater than or alphabetically after
<	Less than or alphabetically before
>=	Greater than or equal to
<=	Less than or equal to
-	Range (hyphen separates upper and lower limits of the range)
,	Or (comma separates two values)
!	Not

The following example shows a search in the sample detail sales report for all orders for item code MR1680 that are greater than or equal to $56,595.


Using wildcards in a search expression

Use wildcard characters to do pattern matching on text objects. Actuate accepts the following wildcards.

Wildcard	Meaning
?	Find any one character
*	Find any number of characters
#	Find any one ASCII numeric character (0-9)

See also

Using the ? wildcard in a search expression
Using the * wildcard in a search expression
Using the # wildcard in a search expression
Using multiple wildcard characters in a search expression


Using the ? wildcard in a search expression

The following illustration shows the results of a search in the samples sales detail using the ? wildcard. We search the report for the ItemCode "M?1680". This search retrieves only those item codes that begin with "M", end with "1680", and are exactly six characters long.


Using the * wildcard in a search expression

The following illustration shows the results of a search in the sample sales detail using the * wildcard. We search the report for the ItemDescription "32M*". This search retrieves all items with descriptions of any length that begin with "32M".


Using the # wildcard in a search expression

The following illustration shows the results of a search in the sample sales detail using the # wildcard. Use the pound sign to exclude characters other than the numeric characters zero through nine from your search. For example, "MS??90" or "MS*90" matches both "MSL390" and "MS1690". "MS##90" limits the search to codes in the "MS" group. The following illustration shows the results of the search for the item code "MS##90".


Using multiple wildcard characters in a search expression

Use a wildcard character multiple times in a single value to broaden a search. For example, the following illustration shows the results of a search in the sample sales detail report for the item code "M*16*". This search retrieves all item codes that begin with "M" and contain "16".


Using patterns in a search expression

Use patterns in a search expression to qualify a search. Patterns allow you to look for characters in a range or to select only certain characters for searching. Use the brackets ([ ]) to place a pattern inside a search term. The following table defines pattern meanings and provides examples of using patterns in a search.

Pattern	Meaning	Example
[character list]	Match any one character inside the brackets.	[M]16 In this example, match the M.
[a-z0-9]	Match any lowercase character and ASCII numeric character	a-c and 1-3
[a-z-]	Match any character or hyphen	a-
[^a-z0-9]	Match any character other than lowercase or ASCII numeric	^Z
[^]	Match one caret	^and

The following illustration shows a search in the sample sales detail report for item codes "MP1680", "MR1680", "MS1680", or "MV1680".


Searching for the characters ?,*,#, and [ ]

Because the characters ?, *, #, and [ ] have special meanings in search expressions, you must indicate when you want to search for the characters themselves. Use the backslash (\) before any special character to search for the character itself, or place the character inside brackets. The following table defines some special characters.

Special characters	Definition
[?] or \?	Match one question mark
[#] or \#	Match one pound sign
[*] or \*	Match one asterisk
[[] or \[	Match one open bracket
[]] or \]	Match one close bracket
[\[-\]]	Match any ASCII character code between "[" and "]"


Using nonprinting ASCII characters in a search

Tabs, line feeds, and carriage returns are examples of nonprinting ASCII characters. With the backslash as an escape character, use the following nonprinting ASCII codes in search expressions.

Special characters	Definition
\	Escape next character (one- or two-byte character)
\a	Match one alarm (0x07)
\b	Match one backspace (0x08)
\t	Match one tab (0x09)
\n	Match one new line (0x0a)
\f	Match one form feed (0x0c)
\r	Match one carriage return (0x0d)
\\	Match one backslash (\)
[\1-\377]	Match any one-byte character excluding NUL (0x00)
[\x100-xffff]	Match any two-byte character

The following illustration is a search of the sample sales detail report for closed orders in excess of $15,000 that are for items whose description contains "32M" and whose item code is in the "Mx" group and in the "32x0" range.

The following illustration shows the search results.


Specifying data to display in the Results page

Besides displaying the results of a search, the Results page can display data from other objects in a report. If, for example, you search for companies by state, the Results page displays, by default, only the company names that match the search criteria. You might, however, also want to display the full company address and credit rank next to the company name, as shown in the following illustration.

You can specify any number of object values to display in the Results page. This capability is useful for creating a quick view of particular data in a report.

See also

How to specify object data to display in the Results page


How to specify object data to display in the Results page

The instructions in this section assume you have already specified the search criteria. For more information about specifying search criteria, see Executing a single-object search and Executing a multiobject search.

1	Choose the Select tab of the Search dialog box.

The Select page appears. By default, the name of the object or objects you selected as criteria for the search appears in the Name column. The values to these objects, in turn, will appear in the Results page after you execute the search.

2	If you want the Results page to display only some of the objects, select each object to exclude. Then choose Delete Entry. To exclude all objects, choose Clear All.

3	To specify additional objects, select each object you want to add. Then choose Add Selection on the Select page.

The names of the objects you select appear in the Name list.

4	Choose Search to start the search process.

The search results appear in the Results page.


Using search definition files

Actuate ReportQuery extends the report search functionality. You can save and use searches stored in search definition (.ROS) files on an Actuate report document.

Actuate saves the following information in a search definition file:

•	Search criteria in the Search page

•	Data to display in the Select page

•	Options in the Search Extract Options dialog box

•	Report document structure information

You can use search definition files with different report document (.ROI) files if they are generated from the same report executable (.ROX). For example, if you have report executable that you use to create weekly reports, you can create a search definition that searches for and extracts data from the report. You can use the same search definition file with any weekly report as long as the report executable has not changed.

You can run a search definition from either the Search dialog box or from the toolbar. For more information on opening and running a search definition see Opening and running a search definition.For information on creating searches and specifying data to be returned from searches, seeUsing basic searching techniques, Executing a single-object search, Executing a multiobject search, Using operators and wildcards in search expressions and Specifying data to display in the Results page.

For information on the options available for exporting data, see Exporting report data.

See also

Saving a search definition
Opening and running a search definition


Saving a search definition

After you have set up a search, you can save the search criteria and options in a search definition (.ROS) file. Choose Save in the Search dialog box to save the search definition. The search definition file is saved in the Actuate search definition directory. If you use the default installation directory, the search definitions are saved in C:\ACTUATE\SRCHDEF.

Actuate saves the following information in a search definition file.

•	The search criteria in the Search page

•	The data to display in the Select page

•	The options in the Search Extract Options dialog box

•	Report document structure information

The report document structure information is used when Actuate runs the search on a report document.


Opening and running a search definition

You can open and run a search definition from either the Search dialog box or from the toolbar. You can open and use a search definition file only from a client machine. The report document can be in the Report Encyclopedia or on a system that you have access to. The search definition file must be on your system or another system that you have access to outside the Report Encyclopedia. Actuate searches for the search definition files in the report document directory and the Actuate search definition directory. If you use the default installation directory, the search definition directory is
C:\Actuate\SrchDef.

If the search definition file cannot be used with the current report, Actuate displays a message when you try to use it.

From the Search dialog box, choose Open to open a search without running it. Choose Start to run the search.

From the toolbar, select a search definition from the list of search definitions and select the Export data button to open the search and run it.

In the toolbar, the list of search definitions lists the search definition files that are in the same directory as the report document and the search definition directory. If you select the Export data button after selecting a search from the list Actuate opens and runs the search.

If you have a search definition file that exports data to an application, using Export data from the toolbar runs the search, exports the data, and starts the application in a single step.


Exporting report data

There are two ways to export data from an Actuate report to another document:

•	Use Actuate's search feature to select only report data that meet specified criteria and send that data to an ASCII file, the Clipboard or to an application. Using this technique, you are, in effect, creating a new report from the original report.

•	Select text or images in the report itself, copy the selection, and paste it in the destination document. This technique is similar to the standard copy-and-paste operation available in other Windows applications.

Exporting report data to an application can be done only on 32-bit Windows systems such as Windows 95 or Windows NT.

See also

Exporting search results
Copying report data to another document


Exporting search results

When you use Actuate's search feature to locate and display report object values that meet specified criteria, you can also copy the search results to the Clipboard or export them to an ASCII file or an application. You can choose to export the entire result set or only a portion of it.

Your exported file can also be used as the data source for another report. For information about using an ASCII file as a data source, see Programming with Actuate which is part of the Actuate Developer Workbench documentation.

Using Actuate search extensions, a part of Actuate Transporter™ technology, you can export all or part of the results of a search to

•	Microsoft Excel spreadsheet

•	Brio Technology BrioQuery document

•	A text file

See Search extension options dialog box for more information on the Actuate search extensions.

To use a custom search extension, a .DLL that Actuate uses to export data directly to another application, see the documentation for the custom search extension for information on installing and using the software. If the search extension uses the default Actuate search extension directory, add the search extension to the Actuate search extension directory. The default the search extension directory is C:\ACTUATE\SRCHEXT.

See also

How to export all of the search results
How to export a portion of the search results
Search extension options dialog box


How to export all of the search results

The instructions in this section assume you have already specified search criteria and selected the objects whose values you want to appear in the result set. For information about specifying search criteria, see Using basic searching techniques, Executing a multiobject search, Specifying data to display in the Results page.

1	To export the search results to a file or Clipboard, perform one of the following steps:

1	Choose Options in the Search page or Select page.

2	Choose Search, then Export in the Results page that appears.

The Search Export Options dialog box appears. The options differ slightly, depending on whether you access the dialog box from the Search page, Select page or the Results page. The following illustration shows the Search Export Options dialog box accessed from the Select page.

2	Select the location or locations to which to send the search results. Portions of the dialog box are enabled or disabled, depending on the export locations you select.

•	If the location is a file or the Clipboard, select the delimiter to use between values if the result set contains values from multiple objects. You can select a tab, comma, or space.

Select Column Header to include the names of the objects as column headings when exporting data.

•	If the location is a file, specify a file name or use the default file name.

•	If the location is an external application, select the application from the list and choose Options to set the options. For information on the options, see Search extension options dialog box.

3	When you have finished selecting the desired options, choose OK.

If you accessed the Search Export Options dialog box from the Select page, the Select page reappears.

If you accessed the dialog box from the Results page, Actuate sends the data to the locations specified in step 2.

4	If you are at the Select page, choose Search to start the search process.

The search results appear in the locations specified in step 2. If you used the settings as shown in the previous illustration, the results are written to SEARCH.TXT. The following illustration shows the contents of the file opened in WordPad.


How to export a portion of the search results

The instructions in this section assume you have already specified search criteria and selected the objects whose values you want to appear in the result set. For information about specifying search criteria, see Using basic searching techniques, Executing a multiobject search, Specifying data to display in the Results page.

1	Choose Search to start the search process.

The search results appear in the Results page.

2	Select the matches you want to export.

3	Choose Export.

The Search Export Options dialog box appears.

4	Select the location or locations to which to send the search results. Portions of the dialog box are enabled or disabled, depending on the export locations you select.

•	If the location is a file or the Clipboard, select the delimiter to use between values if the result set contains values from multiple objects. You can select a tab, comma, or space.

Select Column Header to display the names of the objects in the result set.

•	If the location is a file, specify a file name or use the default file name.

•	If the location is an external application, select the application from the list and choose Options to set the options. For information on the options, see Search extension options dialog box.

5	Select Selection Only to export only the items you selected in step 2.

6	When you have finished selecting the desired options, choose OK.

Actuate sends the data to the locations specified in step 4. If you used the settings as shown in the previous illustration, the results are written to SEARCH.TXT. The following illustration shows the contents of the file opened in WordPad.


Search extension options dialog box

Using Actuate search extensions, you can search for data in a report document and export the data to

•	Brio Technology BrioQuery document

•	Microsoft Excel spreadsheet

•	Text file

The next three sections describe the fields in the Options dialog box for these search extensions.

If you have a custom search extension, a.DLL that Actuate can use to export data directly to another application, see the documentation for the search extension for information on using it.

BrioQuery search extension options dialog box

The following fields are in the BrioQuery Options dialog box

•	BrioQuery document specifies the destination BrioQuery document when the data is exported.

•	Data file specifies the file name of the temporary data file used for transferring the data to BrioQuery. BrioQuery will read the data from this file (required).

The Excel 97 search extension options dialog box

The following items are in the Microsoft Excel Options dialog box

•	New File radio button specifies the data is transferred into a new, blank Excel workbook.

•	Existing File radio button specifies the data is transferred into the workbook specified in the Workbook field.

•	Workbook specifies the name of destination Excel workbook (document). Field is required if Existing File radio button is selected.

•	Workbook sheet specifies the destination sheet within the specified workbook. This is an optional field.

•	Row specifies the row number of the top left cell of the workbook sheet where the exported data is placed. This is an optional field.

•	Column specifies the column letter or letters of the top left cell of the workbook sheet where the exported data is placed. This is an optional field.

•	Include Column Header check box specifies if column headings are written to the workbook. Enabled is the default.

•	Macro specifies a macro that is executed after the data is transferred to the Excel workbook. This is an optional field.

File search extension options dialog box

The following items are in the File Output Options dialog box:

•	Temporary Data File Name specifies the name of the output text data file. This is a required field.

•	Command line specifies a command line string that is executed after the data is written to the file. This is an option field.

•	Include Column Header check box specifies if the column headers are included in the data file. Enabled is the default.

•	Column Delimiter specifies the delimiter between data fields. Comma is the default.


Copying report data to another document

You can copy data in the form of numbers, images, or text from an Actuate report and paste the data into another document. As with the standard Windows copy-and-paste operation, the report data you copy is stored in the Clipboard. You can then paste the data into any other document.

How to copy report data

1	Select text or images within a report. You can drag the mouse to enclose the area of interest, or hold the Shift key down and use the left mouse button to select multiple objects.

The following illustration shows a selected area in page 2 of DETAIL.ROI.

2	 Choose Edit→Copy or the copy button on the toolbar.

3	Move to the destination document in an external application.

4	Use Edit→Paste in the destination document to insert the copy into the destination document.

The following illustration shows the report data pasted into a WordPad document.


Printing and distributing a report

The following topics are available. To view the topics in order, use the Browse button (>>) in the Help window's toolbar

•	Comparing viewing and printing

•	Printing reports on a client system

•	Command line options for printing

•	Saving reports in HTML format

•	Printing reports in a Report Encyclopedia

•	Setting printer properties in the Report Encyclopedia

•	Running a report before printing

•	Distributing a report from a client system

•	Distributing a report stored in the Report Encyclopedia


Comparing viewing and printing

A major feature of the Actuate reporting system is the live, interactive presentation of online reports. Actuate reports can also be printed.


Printing reports on a client system

To print an Actuate report, you use the standard Windows procedure to select a printer and set printer properties. In addition, Actuate provides printing options specific to Actuate reports.

See also

How to print a report on a client system


How to print a report on a client system

1	Open the report you want to print in the Developer Workbench or the End User Desktop.

2	Choose File→Print.

The Print dialog box appears. The options available from this dialog box let you select the printer and report printing options such as page range and number of copies.

3	Select the desired printing options: the printer, the pages to print, the order in which to print the pages, the number of copies to print.

4	To specify a printer's other properties, or to change the printer's default settings, choose Properties.

The Document Properties dialog box appears. The following illustration shows the Page Setup tab of the dialog box for an HP LaserJet 4Si MX printer driver. Options and defaults are different for different printers.

5	Set the options in this dialog box to specify paper related settings such as paper size and duplex printing.

A printed report's page orientation is determined by the layout of the report when the report is designed.

6	To view and change other printer settings, choose the Advanced tab.

The following illustration shows the Advanced properties tab for a HP LaserJet 4Si MX printer. Options and defaults are slightly different for different printers.

7	Set the desired printer properties, then choose OK.

8	When the Print dialog box reappears, choose OK to start printing.

See also

How to preview a report before printing


How to preview a report before printing

1	Choose File→Print Preview to preview the report before printing it.

Previewing gives you an opportunity to review and change the printing options you selected.

2	Use Next Page, Prev Page, Two Page, Zoom In, and Zoom Out to see different pages and to see different levels of detail.

3	When you have finished previewing the report, choose Close to close the preview window or Print to print the report.


Command line options for printing

You can print an Actuate report document from the command line using Actuate client applications. With the Actuate LRX, you can use the command line only to print a report from the command line. To view a report with the Actuate LRX, open the report in your web browser. This is the command line syntax for printing reports:

<client> -p <file>.roi [-rox <filename>.rox] -rspn<printer>[ -h]

The <client> is the client application. You can use these Actuate applications: End User Desktop, Viewer, LRX, Administrator Desktop, Developer Workbench.

The -p <filename>.roi parameter is required and specifies the name of the report document. The .ROI extension is required.

The parameter -rox <filename>.rox is optional and is the name of the report executable .ROX file used with the report document. Use this parameter if the ROX name stored within the ROI is not sufficient to locate the ROX. If used, the .ROX extension is required.

The parameter -rspn <printer> is required and specifies the printer name. Use the UNC name for the printer. For example, \\myserver\printer3 is the printer named printer3 on the machine myserver.

The parameter -h is optional and enables silent (hidden) mode. If you use the -h option, the client application does not open a window and error messages are displayed on the command line. The LRX always uses hidden mode. If you do not use the -h option, the client application opens a window and the startup splash screen appears.

For example, the following command uses the Actuate Viewer to print a report that is in the c:\actuate\viewer\bin directory to a printer on the network:

viewer -p forecast.roi -rox forecast.rox -rspn \\actuate\printer3 -h


Saving reports in HTML format

To save an Actuate report document in HTML format, use a standard Windows save dialog box to specify a location and name of the HTML file. Actuate converts the report document to HTML format and attempts to preserve Actuate report document formatting by using HTML tables and text formatting.

See also

How to save a report in HTML format


How to save a report in HTML format

1	Open the report document (.ROI) you want to save.

2	Choose File→Save as HTML.

The New HTML File dialog box appears. Use the items in the dialog box to navigate to a directory. Specify the file name in the File Name edit box and choose Save to save the report in HTML format.


Printing reports in a Report Encyclopedia

There are two times when you can send a report in a Report Encyclopedia to a network printer.

•	When you create a report request, the Print tab in the Requester lets you specify the network printer to which a completed report is sent. For information about creating report requests, see Creating a request to run a report in the Report Encyclopedia.

•	You can print any report at any time. To do so, choose Print Report from the report's context menu.

When you print a report from a UNIX Report Server to a UNIX printer, the printout might appear different from the displayed report or the report printed on a local Windows printer. This might be due to the UNIX printer configuration or the Report Server printing configuration. Contact your Report Server administrator if this occurs.


Setting printer properties in the Report Encyclopedia

When you print a report in the Report Encyclopedia, the network printer gets its printing options from three sources, in the following order:

1	The printer properties you set for the print job

2	The printer properties you set as the default settings for a specific printer

3	The printer's system level properties, set by the administrator

The following conceptual diagram illustrates how a printer determines what printer properties to use for a print job.

As a user, you can

•	Set printer properties that are used only for the print request you are about to send.

•	Set default properties for a specified printer so that the properties are retained for future use. If you have access to multiple network printers, you can set and save print properties for each printer.

If you do not specify any printer properties, the printer uses the system level defaults, which only the administrator can change. Some printer properties, such as duplexing and color, are available only if the printer supports them.

See also

Setting default properties for a printer
Setting properties for a specific print request


Setting default properties for a printer

If you print reports on the server frequently, it is best if you set default printer properties for each of the printers you use often. By doing so, you can print reports without having to set properties for each print request, and you will always get the same format. If your print requirements change, you can modify the default settings easily. Or, if you need a different format for one print request only, you can specify property settings that apply only to the print request.

When you set the default printer properties, they are associated with your user account. In other words, your printer settings apply only to your print requests, and do not affect the settings for other users.

See also

How to set default properties for a printer


How to set default properties for a printer

1	Choose Printers from the left pane of the Navigator window.

A list of network printers appears in the right pane of the Navigator.

2	Choose the printer whose properties you want to set.

3	Press the right mouse button and choose Properties from the context menu.

The User Print Properties dialog box appears with the General page open, as the following illustration shows. This page displays read only information, specified by the administrator, about the printer.

4	If you want to set this network printer as the default, check the Set As Default option.

Future print requests you submit will use the default printer unless you specify a different one at that time.

5	Choose the Paper tab to set paper properties, such as size, paper tray, and duplex mode.

The printer's default values, set by the administrator, appear in gray. You can accept or change the defaults. If the option headings are gray, that means the option is unavailable. A printed report's page orientation is determined by the layout of the report when the report is designed.

The following illustration shows the Paper page and describes the properties.

6	Choose the Option tab to set other properties, such as number of copies, image size, and print resolution.

A printed report's page orientation is determined by the layout of the report when the report is designed.


Setting properties for a specific print request

Set printer properties for a print request if your requirements are different from the defaults you set previously for a specific printer, and if you do not want to use the system level defaults established by the system administrator.

See also

How to set properties for a specific print request


How to set properties for a specific print request

1	Select the report you want to print.

2	Press the right mouse button and choose Print Report from the context menu that appears.

The Print Request dialog box appears.

3	Select the network printer, priority, and print range.

The priority levels you can specify depend on what the administrator assigned as the maximum priority you can set for requests. If, for example, the administrator set your maximum request priority at medium, you can print reports only at the medium and low priorities.

If you select Print to file, the file will be sent to the file you specify on the Report Server's local file system.

4	Choose Properties to specify printing options.

The Request Print Options dialog box appears.

5	Set the desired properties. For information about each property, see How to set default properties for a printer.


Running a report before printing

If a report object executable (.ROX) file is available, you can generate a new report to print. There are several reasons for rerunning a report just before printing.

•	To include database updates made since the developer designed the report and made it available to you.

•	To include database updates made since the last time you worked with the report.

•	To specify parameters to generate a report that are more useful for current needs than the parameters of the original report design.

For information about running reports, see Running a report.


Distributing a report from a client system

There are two ways to distribute a report from a client system to users throughout an organization. You can

•	Send the report through email or fax software.

•	Copy the report to the Report Encyclopedia and inform the users of the report's location. You can use this method only if you and the recipients of the report work in a client/server reporting environment, and have access to the Report Encyclopedia.

To distribute a report, you provide the appropriate report files and Actuate Viewer, if required. The Viewer is required if the recipients do not have any Actuate client applications, such as the Developer Workbench or the End User Desktop.

When a user opens a report for viewing or printing, Actuate runs the report executable from which the report was generated. Therefore, when you distribute a report to other users, you need to include the executable as well. To simplify the distribution process, Actuate provides the option of bundling the executable with the report so you need to send only one file.

See also

How to distribute a report from a client system using email


How to distribute a report from a client system using email

1	Open the report document you want to distribute. You can use the Developer Workbench, End User Desktop, or the Administrator Desktop to open the report.

2	Choose File→Send.

You have the option to send just this file or all open reports.

3	Choose whether to send just the current report, or all open reports.

Actuate displays a message prompting you to bundle the executable with the report.

4	Choose Yes to start the bundling process.

The Choose Profile dialog box appears. This dialog box provides the option of distributing a report through various services. The default choice is Microsoft Exchange. You can, however, choose other mail services.

5	Choose the service to distribute the report, then choose OK.

A mail dialog box appears, prompting you to enter your mail user name and password.

6	Type the required information in the mail dialog box, then choose OK.

A mail window appears with the report as an attachment.

7	Address the mail message and send it.

The recipients will receive the report as a mail attachment.

See also

Linked and embedded objects in the report
How to distribute a report from a client system using the Report Encyclopedia
How to distribute Actuate Viewer


Linked and embedded objects in the report

Bitmaps, spreadsheets, or other files might be used by report developers as part of a report design. If these external objects are linked to the report, the distributed report searches the path to find them. If it cannot find the path, the linked object does not appear in the report.

If you see an X in your report, a necessary file might not have been included when the report was distributed. Embedded objects, on the other hand, are part of the report. If you are distributing a report you designed, it is best to embed objects in the report design. The following illustration shows a report that has lost a link to an external object.


How to distribute a report from a client system using the Report Encyclopedia

The instructions in this section assume you and the recipients have access to the Report Encyclopedia.

1	Prepare the report for distribution by performing the following steps:

1	Open the report you want to distribute. You can use the Developer Workbench, End User Desktop, or the Administrator Desktop to open the report.

2	Choose File→Bundle Executable.

The New Report File with ROX dialog box appears.

3	Type a new file name for the report with the bundled executable.

You must specify a new name. Actuate does not allow you to overwrite the original report because it is open.

4	Select the folder in which to save the new report file.

5	Choose Save to save the new report file.

2	Log in to the Report Encyclopedia. For instructions, see Connecting to the Report Encyclopedia.

3	Copy the file from your local machine to the Report Encyclopedia. For instructions, see Copying files to the Report Encyclopedia.

4	Inform the recipients of the report's availability and location.


How to distribute Actuate Viewer

Actuate Viewer is a royalty free tool for viewing Actuate reports. You can distribute copies of Actuate Viewer freely. Use one of the following methods to distribute Actuate Viewer.

•	Download the Viewer installation file from the Actuate Web site
http://www.actuate.com to a location all users have access to and let the users download and install the Viewer.

•	Allow users to download the Viewer installation file from the Actuate Web site.

Also, users can install the Actuate LRX to view Actuate reports using a Web browser.


Distributing a report stored in the Report Encyclopedia

Storing files in a Report Encyclopedia makes physical distribution of files unnecessary. Users with access to the Report Encyclopedia can log in at any time and find reports for which they have been granted appropriate file privileges.

If you have been granted the privilege to run report executables (.ROXs), you can specify the users or groups to whom you want to distribute report documents. You can also specify different file privileges for different users and groups. You specify the distribution list and the file privileges as part of issuing a report request. For instructions on issuing a report request, see Creating a request to run a report in the Report Encyclopedia.


Using reports on the Web

The following topics are available. To view the topics in order, use the Browse button (>>) in the Help window's toolbar.

•	Using a Web browser to view reports

•	Overview of the Actuate Web interface

•	Navigating the Report Encyclopedia on the Web

•	Accessing and generating reports on the Web

•	About ReportCast channels

•	Subscribing to channels

•	Viewing channels and their contents


Using a Web browser to view reports

If you install the Actuate LRX (live report extension) with your Web browser, you can view Actuate reports (ROI) from your browser. You can view reports that are stored on your local file system, or if your system is configured to do so, you can log into an Actuate Report Encyclopedia using your Web browser and view reports that are stored in the Encyclopedia.

From either your local file system or a Report Encyclopedia, you have the same report viewing, navigation, and searching capabilities that are available with the Actuate Viewer. For information about Actuate viewing and searching capabilities, see Viewing a report and Searching for and exporting report data.

This illustration shows a sample report when viewed from a Web browser with the Actuate LRX installed.

Using a Web browser with the Actuate LRX installed to open and view a report stored locally is similar to opening a report with the Viewer. For more information seeOpening and viewing a report in a file system.  To view a report that is in stored in a Report Encyclopedia, see Navigating the Report Encyclopedia on the Web.


Overview of the Actuate Web interface

Using the Actuate Web Agent and a Web server, you can access an Actuate Report Encyclopedia over the Web using a Web browser. The following illustration shows where the Actuate Web Agent fits into the Actuate Internet architecture.

In addition to letting users navigate through an Encyclopedia and view reports, Actuate lets administrators create ReportCast channels. Channels use internet "push" technology to give users access to reports. Actuate supplies the following ReportCast channel Web pages:

•	List of Channels. A page that lists the channels to which the user is subscribed. (A Web site designer can elect to put this list on other pages as well.) This list is sorted alphabetically.

•	Channel Contents Page. Displays the contents of a channel. The contents are completed report requests that appear in descending chronological order.

•	Subscription Page. A list of channels with check boxes so that the user can subscribe to or unsubscribe from a channel.

•	Channel Administration Page. A page that lets an administrator create, delete and modify channels.

As administrator, you can customize the look of the Report Encyclopedia pages by changing the Web Agent templates. See Using the Actuate Web Agent distributed with the Actuate Web Agent product for more information on customizing Report Encyclopedia Web pages.


Navigating the Report Encyclopedia on the Web

Check with your Actuate Report Server administrator to find out if you can access reports on the Web.

To navigate through the Report Encyclopedia via your Web browser, click on hyperlinks contained on the Encyclopedia's Web pages, or enter URLs in the Address or Location window of your Web browser.

 We assume that you are familiar with the Web and using Web browsers. The illustrations in these topics use the standard Web pages provided by Actuate. Your Report Server administrator may customize the look of the Web pages for your site, so your pages may appear differently from those in the illustrations.

Navigating through the Report Encyclopedia with a web browser is similar to navigating through the Report Encyclopedia using an Actuate Navigator window. From the main Report Encyclopedia Web page, click on a folder's link. The folder contents page displays in the browser. You can continue clicking on subfolder links to display their contents, click on a report executable to generate a report, or click on report ROI's, ROV's, or ROW's to view reports.

See also

Accessing the Report Encyclopedia on the Web
About a Report Encyclopedia Web page


Accessing the Report Encyclopedia on the Web

To access your Report Encyclopedia, bring up your Web browser and enter a URL that points to a Web server that is connected to your Report Server:

http://<Web server>/acweb/<report server>

where:

•	<Web server> is the name of the Web server that is running the Web interface to the Report Encyclopedia

•	acWeb is a keyword that indicates that you want to access the Report Encyclopedia

•	<report server> is the name of the Report Server whose Encyclopedia you want to access

For example, to access reports from a Report Server on a machine called Mustique from a Web server called Caligari:

http://caligari/acweb/mustique

Depending upon your setup, a login dialog box may appear. If it does, enter the user name and password you normally use to access your Report Encyclopedia.

See also

Logging in as a Report Encyclopedia user
Logging in as the anonymous user


Logging in as a Report Encyclopedia user

When you first access the Report Encyclopedia using a Web browser, the login dialog box appears. When you enter a valid user name and password, the initial Report Server view appears in your browser.

If your Report Server administrator has set up an anonymous user, you will not see a login dialog box. For more information on the Report Encyclopedia anonymous user, see Logging in as the anonymous user.


Logging in as the anonymous user

The anonymous user allows users to access a Report Encyclopedia without having to log in.

When the anonymous user attempts to view an object that he only has visible privilege for, the login dialog appears to let the user log in as another user with privilege to view the object. The user must enter a valid user name and password to be able to view the selected object. The user is reconnected to the Report Encyclopedia with the new authentication information and privileges.

For more information on the visible privilege see Types of privileges.


About a Report Encyclopedia Web page

When you log into a Report Encyclopedia over the Web, the initial Report Encyclopedia page is similar to the following:

From this main page, you can:

•	View the contents of the Report Encyclopedia

•	Access your personal channel (your Completed reports folder)

•	Access the available Report Encyclopedia folders

•	Get detailed information about folders

•	Sort the folders by name, type, or creation date and time

The left-hand side of the page contains links to the Report Encyclopedia's system folders and the user's Personal folder:

•	The Personal Folder is the folder the Report Server Administrator creates to hold the user's reports and other files

•	The home folder for the current Report Encyclopedia (urup, in this case)

•	The Active Requests and Scheduled Requests folders contain information about current and scheduled requests

•	The Channels folder provides access to completed requests in the Personal Channel, the channel subscription pages, and channel administration pages for Administrators.

The right-hand side of the page lists the Report Encyclopedia objects available for viewing. Click on the Details link to find out more about them, including the privileges needed to access them. Click on a folder to view the folder's contents.

Accessing a folder's contents page

When you click on a Report Encyclopedia folder's link to display its contents, you see the folder's contents page similar to this one:

The folder Web page lists the folder's contents, including any subfolders, as well as links to your personal folder and to the Active and Scheduled requests Web pages.

For information about the types of Actuate files see Understanding the types of Report Encyclopedia files.


Accessing and generating reports on the Web

You can get to reports on the Web by navigating through the Report Encyclopedia folders using links from Report Encyclopedia Web pages. See About a Report Encyclopedia Web page.

You can also get to links to report documents in your personal channel Web page or from other ReportCast channel pages. See About ReportCast channels.

Once you see the link to a report document on a Web page, clicking on the link displays the document.

You can generate reports on the Web by clicking on report executable links in a Report Encyclopedia folder. See About report generation and the Web.

The rules regarding report generation and viewing from a Report Encyclopedia apply. You still need the appropriate privileges to generate and view a report. And the users viewing the report via a channel also need the appropriate privileges. See Assigning privileges for Report Encyclopedia folders and files for information on privileges.

About report generation and the Web

When you generate a report from the Report Server, a notification message is displayed in one or more ReportCast channels. The notification appears in the your personal channel and in the personal channels of users who are selected to be notified of a completed request. Users can view the report by selecting the notification item in the channel's page.

If you generate a report from a Web browser, you can send a notification message to ReportCast channels you have access to. A subscriber to the channel can view the report by selecting the item in the channel's page.

See also

How to generate a report request from a Web browser


How to generate a report request from a Web browser

1	From your Web browser, log into the Report Encyclopedia.

2	Go the folder containing the report executable (.ROX) or report parameter values file (.ROV).

3	Click the report executable to display the Request Report page.

4	Enter the report request information. For reports displayed in channels, you can specify a headline. At the bottom of the Web page, the available channels appear. Select the channels you want to notify when the report is completed. For each channel, you can exclude roles that have access to the report.

5	To submit the report request, choose Submit Request at the bottom of the page.

6	A confirmation form displays in the browser similar to the following illustration. Click the Request Status button to check on your request's status. To cancel the request, click the Cancel Request button.


About ReportCast channels

Actuate ReportCast channels requires the Actuate Web Agent and a Web server. ReportCast channels is a service which allows users to subscribe to particular Web "channels" of interest, and view Actuate reports that are available on those channels. ReportCast channels use "push" technology (also called Webcasting, push/distribution, and publish/subscribe) to "push" reports to particular Web channels, where interested users can access and view them. When new reports become available, the appropriate channel receives a notification. From a Report Encyclopedia, subscribed users can check the channel's Web page to get a list of available reports. When users click on a report link, the report appears in the Web browser window. The following are ReportCast channel features:

•	Channels are supported only on the Web. They are administered only over the Web

•	Channels are secure; they use the same security scheme as Actuate Encyclopedia folders and items

•	Channels have unique names

•	Every user has a default personal channel. This is the user's Report Server Completed folder

•	Channels receive notifications when reports generated for the channel are complete

•	Reports in channels can display headlines that describe the reports. This headline appears when listing the contents of a channel

•	Channel items expire after a given time period and are automatically removed from the channel

As a user, you can

•	Retrieve the list of available channels

•	Subscribe to a channel

•	Drop a channel subscription

•	View the list of reports in a channel

•	View the reports in a channel

As administrator using a Web browser, you can also

•	Create a channel

•	Delete a channel

•	Change a channel's properties

•	Update a channel's contents

See also

About your Personal Channel


About your Personal Channel

From a Web browser, the user's Completed request folder is the personal channel. After a successful report generation, the report notification appears in the user's personal channel.

Accessing your Personal Channel page

When you click on the Channels link on the main Report Encyclopedia Web page, a page such as the following displays in the browser:

From your Personal Channel, you can

•	Click the Subscribe button to subscribe to or unsubscribe from ReportCast channels

•	Click the Channel Admin button to administer ReportCast channels (administrators only)

•	Click the channel icons to access particular channels you're subscribed to

•	View completed reports

•	Click the Details icon to view a report's status, view the report, or delete status information for the report.

About ReportCast channel headlines

When you generate a report for a ReportCast channel, you can specify a headline that will be generated as part of the channel notification. The headline appears as the second line of a channel notification on a Web page.

Users who generate reports from an Actuate client like the End User Desktop can enter a headline in the Requester dialog. Users who generate a report from a Web browser can enter a headline in the Requester Web page. In the Requester dialog, the Headline parameter is one of the Output Parameters. In the Requester page, the Headline parameter appears as a field in the Requester Web page form. The following illustration shows the Headline parameter in a Requester dialog.

Report developers can also access the headline parameter. By default, the Report Server copies the value of the headline parameter into the completed request headline. Developers can change the headline by changing the global variable that corresponds to the parameter. Changing the headline for a completed request does not change the original parameter. That is, if the report is run from an ROV file, then changing the headline for the completed request does not change the original parameter value in the ROV file.


Subscribing to channels

You can subscribe to channels and drop channel subscriptions using your Web browser. After connecting to a Report Server, you can go to a page that lists all channels to which you have access. Each channel name appears next to a check box. The box will be checked if you are subscribed to the channel. You can change the check marks to subscribe to or unsubscribe from a channel.


Viewing channels and their contents

You can view a list of channels from your Web browser. Actuate supplies a default Web page that lists all the your subscribed channels. From this page, you can subscribe to channels and view the channel's contents. See Subscribing to channels for more information on subscribing to channels.

As the Actuate default, when you view the contents of a channel, the contents appear as a list containing the report headline and optionally the report name, the creation date, and so on. Clicking on the link for a channel item displays the report itself. The page that lists the channel contents can also list all the subscribed channels in the menu bar on the left.

The contents of a channel remain in the channel even after you have viewed them. The Web browser uses a different color to display visited reports, so you can easily track which reports have been read.


Building your first report

To build your first report, follow the step by step instructions in the following topics. To view these topics in order, use the Browse button (>>) in the Help window's toolbar.

Before you begin: the example database

Before you begin: the example report

Lessons in building the example report

Lesson 1. Start the report design

Lesson 2. Set up the database connection

Lesson 3. Write a query to select data for the report

Lesson 4. Group and sort the data

Lesson 5. Add frames to the group sections

Lesson 6. Add headers and totals to the report

Lesson 7. Build a frame and controls

Lesson 8. Change text formats

Lesson 9. Configure the Table of Contents

Lesson 10. Run the report

Lesson 11. View the finished report

Lesson 12. Print the report

Lesson 13. Save as an HTML report


Before you begin: the example database

The data in the example report you will build in this chapter is drawn from a relational database called sfdata. This database contains sales information for MultiChip Technology, a fictitious semiconductor manufacturer. Tables in the database record information about customers, sales representatives, forecasted orders, line items, and so forth.

The following illustration shows the three tables used in the example report.


Setting up the example database

The sample database, SFDATA.MDB, is set up automatically if you selected the installation of ODBC drivers when you installed the Developer Workbench. If you did not select the installation of ODBC drivers and you want to use the sample database or run the example reports, do one of the following:

•	Run the installation program again and select "ODBC drivers."

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

See also

How to set up the data source manually


How to set up the data source manually

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

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

The ODBC Data Source Administrator dialog box appears.

3	Choose Add.

The Create New Data Source dialog box appears.

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

5	Choose Finish.

The ODBC Microsoft Access Setup dialog box appears.

6	In the Data Source Name field of the ODBC Microsoft Access Setup dialog box, type sfdata.

7	In the Database section, choose Select.

The Select Database dialog box appears.

8	Select the Examples\Database subdirectory of the directory in which you installed the Developer Workbench.

9	Select sfdata.mdb and choose OK.

10	Choose OK to close the other dialog boxes.

For more information on setting up databases, see  Query data streams.


Before you begin: the example report

The lessons step you through the process of creating a typical example report. You will review the steps again in  Overview of the report design process. The diagram of report steps is repeated at the beginning of each lesson to help you see your progress.

The following illustration shows the report you will build. It is a typical grouped report with two groups, customers and orders.

Before building the example report, view it by following these steps.

1	Start the Developer Workbench.

The main application window appears.

2	Close the Welcome screen, if it appears.

3	Choose File→Open.

4	In Files of Type, select Report Document (*.ROI).

5	Select BYFR.ROI. It is located in the Actuate/Devwb/Examples/FirstRpt directory, if you selected the default options when you installed the Actuate Developer Workbench.

6	Choose OK.

The example report appears in the Viewer window. If you wish, use the Zoom feature to adjust the viewing size of the report. Choose 75%, for example.

To see the active viewing features of the report, such as hyperlinks, follow the procedures in Lesson 11. View the finished report

When you are finished viewing the sample report, close the BYFR.ROI file and any other Actuate files that might be open.


Introducing HTML reports

You may save the example report you create in these steps as an HTML report. HTML supports a narrower range of layout and font options than does a "regular" Actuate report. When you view your HTML report in your Internet browser, you will see how the report changes in HTML. To learn how to create HTML reports, see Chapter 14, "Building HTML reports."Building HTML reports.


Lessons in building the example report

The following list summarizes the tasks you will perform. To view these lessons in order, use the Browse button (>>) in the Help window's toolbar.

Lesson 1. Start the report design

Lesson 2. Set up the database connection

Lesson 3. Write a query to select data for the report

Lesson 4. Group and sort the data

Lesson 5. Add frames to the group sections

Lesson 6. Add headers and totals to the report

Lesson 7. Build a frame and controls

Lesson 8. Change text formats

Lesson 9. Configure the Table of Contents

Lesson 10. Run the report

Lesson 11. View the finished report

Lesson 12. Print the report

Lesson 13. Save as an HTML report


Lesson 1. Start the report design

Before you start work, you will start the Actuate Developer Workbench and create a new design file.

1	Start the Developer Workbench.

The main application window appears.

2	Choose File→New.

3	Select New Report Wizard. Choose OK.

The New Report Wizard appears.

4	Choose the Connection tab.

The Connection page appears.

5	Select ODBC as the database connection.

6	Use the default connection properties.

If you had selected the installation of ODBC drivers in the "Before you begin" sections at the beginning of this chapter, you see the following default properties. If these properties are not set, type them:

Datasource: sfdata

Dllpath: ODBC32

7	Choose Finish.

By choosing Finish, you accept all the other defaults in the Wizard. The Design Editor opens, showing the structure and layout of a new report.

The structure pane is on the left side. The layout pane is on the right side.

As you can see in the two panes of the Design Editor, the report design already contains some components. Actuate automatically added these components to the report design when you accepted the defaults in the New Report Wizard. For example, a default page list has been provided.

8	In the structure pane, click the plus icon next to the Content-Report component.

More components appear. In the Design Editor, a plus icon indicates that additional levels of components exist.

9	Choose File→Save As.

10	Type a new name for your copy of the example report, such as MYREPORT.ROD, and choose Save.

The file extension .ROD is the extension Actuate expects for a report design file.


Lesson 2. Set up the database connection

In the "Before you begin" section at the beginning of the chapter you set up a database connection.

1	You should have installed and set up ODBC on your computer. When you installed the Developer Workbench, you probably chose to automatically install the ODBC database and data source used by this example report.

2	In the structure pane, double-click the connection component.

The Component Editor appears.

3	In the Component Editor, in the Properties tab, click in the area to the right of the DataSource property and type the following text, if it does not already appear.

sfdata

4	Press Apply.

5	Close the Component Editor.

6	Choose File→Save, or Ctrl+S to save changes to the report design.


Lesson 3. Write a query to select data for the report

To specify which data you want to include in the report, you write a query. A query is a SQL SELECT statement that controls how data is retrieved from the database.

If you are planning to use stored procedures provided by the database, do not write a query or use the Query Editor. Instead, use the Stored Procedures Data Source Builder. For more information on working with stored procedures, see Using stored procedures.

To write the query, perform the following procedures. To view these procedures in order, use the Browse button (>>) in the Help window's toolbar.

Open the Query Editor

Select tables

Select columns

Add a condition to the query

View the SQL SELECT statement

See also

Open the Query Editor
Select tables
Select columns
Add a condition to the query
View the SQL SELECT statement


Open the Query Editor

To write the query, you use the Query Editor, which helps you access the data source you'll work with to graphically select the tables and columns that contain data for the report. Actuate writes the SQL SELECT statement automatically as you make selections in the Query Editor.

1	Choose View→Data Source.

If the Data Source menu item is unavailable, click in the structure pane, then try again.

The Database Login dialog box appears.

2	The example database does not require a user name or password, so choose OK.

The Query Editor and Database Browser appear.

3	Click the plus icon next to the database in the Database Browser.

Or, from the View menu select Options... Choose the Query Editor tab and select Show Tables and Views.

Your DB Browser window will show the location of your example database, similar to the illustration.

The tables in the Sales database appear. You will drag and drop certain tables into the Query Editor to start selecting data for your report.


Select tables

Begin writing the query by selecting the tables that contain the information you want in your report.

1	Drag and drop the customers table from the Database Browser to the upper pane of the Query Editor. The cursor changes when you drag and drop.

2	Drag and drop the orders table.

3	Drag and drop the items table.

Lines that indicate joins appear automatically between the tables.

4	To align the tables, click inside the upper pane of the Query Editor and then choose Edit→Arrange Tables.

More information

In this query, the joins were created automatically. You can also create your own joins. For more information about how to create a join, see Creating joins.


Select columns

You will use all the columns from the tables you just selected.

1	Make sure the Columns tab is selected in the lower pane of the Query Editor.

2	Drag and drop the asterisk (*) from the items table to Column Name in the lower pane.

The asterisk provides a quick way to select all columns from a table. The column names appear in the lower pane.

3	Repeat step 2 for the orders and customers tables.


Add a condition to the query

Narrow your request for data by adding a condition to the query.

1	Select the Conditions tab.

2	Click under Column Name and select customers.creditrank from the drop-down list.

3	In Query Expression, type the following expression. In this example, this must be a capital C.

= 'C'

The query will select only rows for customers that have a credit ranking code of C.


View the SQL SELECT statement

Now you are finished specifying which data to include in the report. While you have been working with the Query Editor, Actuate has automatically written a SQL SELECT statement based on your choices.

1	To view the SQL SELECT statement, select the SQL tab. It should look like the following illustration. Scroll right to see the complete SELECT and WHERE clauses.

2	Close the Query Editor window. The DB Browser closes with the Query Editor window.

3	Choose File→Save to save changes to the report design.

More information

For this query, you used only the Tables and Joins, Columns, Conditions and SQL tabs. You could also have put conditions on row retrieval and created aggregate rows using the Group By and Having tabs. For more information about using these parts of the Query Editor, seeChapter 5, "Query data streams."  Query data streams.

You could also have set up parameters, such as a range of dates, for the user to enter when running the report. For more information about defining parameters, see Designing report parameters.


Lesson 4. Group and sort the data

Next, you will add group sections, which help you arrange data. For example, you may want to group data according to the customer ID and customer name. A group is a set of rows that have one column value in common, such as customer name. In this example, group sections also sort the data.

You will add group sections for two groups, customers and orders. Later, you will add a frame to display the items in each order.

To sort and group the data, perform the following procedures. To view these procedures in order, use the Browse button (>>) in the Help window's toolbar.

Select the Prompt for Name option

Add the two group sections

Deselect the Prompt for Name option

See also

Select the Prompt for Name option
Add the two group sections
Deselect the Prompt for Name option


Select the Prompt for Name option

1	Position the mouse pointer in the background of the structure pane, which is the pane on the left, and press the right mouse button.

The context menu appears.

2	Choose Prompt for Name.

When you select the Prompt for Name option, the Developer Workbench gives you an opportunity to name each component you add to the report design.

3	Display the context menu again and choose one of the Name options: Show Slot Names Only, Show Component Names Only, or Show Slot and Component Names.

When you select the Show Slot and Component Names option, the structure pane displays both the names of slots and the names of components placed in those slots. This setting is the default, so your display might already show both names.


Add the two group sections

1	From the main component palette, choose Structure.

The Structure palette appears.

If you pin the Structure palette into place, it will not disappear when you close the Developer Workbench session. Also, if you click several icons on the main palette to set up several palettes, each palette remains visible while you click the next icon to open another palette. Experiment with pinning and unpinning to see the behavior of the palettes during your session.

2	From the Structure palette, drag and drop a group section component to the Content slot.

The Class Name dialog box appears.

3	Type CustomerGroup. Choose OK.

The Component Properties dialog box lets you name the key property. The key property binds the group section to the data to be sorted and displayed. In this example, you are asking to gather the customer, item and order data and group it under its corresponding customerID, or key.

4	Click in the area to the right of the Key property and select [customers.custID] from the drop-down list. Choose OK.

The CustomerGroup component appears in the structure pane along with its slots.

5	Drag and drop another group section component from the Structure palette to the CustomerGroup's Content slot.

The Class Name dialog box appears.

6	Type OrderGroup. Choose OK.

The Component Properties dialog box appears.

7	Click in the area to the right of the Key property and select [orders.orderID] from the drop-down list. Choose OK.

Later, you will place a frame to display the order items in the OrderGroup component's Content slot.

8	Choose File→Save to save changes to the report design.

This report is now set to sort the OrderGroup data as a subset under the headings of the customer group. When you run the report, Actuate adds sorting instructions to the Order By clause of the query.

More information

Group sections are not the only way to sort data. In a report that does not use a query data stream, you must use other techniques for sorting. For more information about sorting data, see About sorting data.


Deselect the Prompt for Name option

From now on, you will be adding components that already have names, so you no longer need the Prompt for New Name option.

1	Position the mouse pointer in the background of the structure pane or the layout pane and press the right mouse button.

The context menu appears.

2	Deselect Prompt for Name.

More information

For more information about group sections, see About group sections.

Actuate provides four other types of sections that you can use to accomplish other reporting tasks, including the following.

•	Using a sequential section, print several components in a specified order

•	Using a conditional section, determine which of two components to print using a conditional section

•	Using a parallel section, print two or more subreports simultaneously

•	Using a report section, design a subreport using a report section

For more information about sections, see Working with sections.


Lesson 5. Add frames to the group sections

Next, you will add components to display data in each of the group sections. The components you will use are called frames. Each frame is a rectangular area that contains controls. Each control displays one data item, such as a column heading. You will add the following frames:

•	CustomerTitleFrame, to print at the start of each customer's group of orders

•	CustomerPageHeader, to print at the top of every page of the customer group

•	OrderTitleFrame, to print at the start of each order

•	OrderPageHeader, to print at the top of every page of the order group

•	OrderTotals, to print after each order

•	Customer Totals, to print after each customer's group of orders

To add frames to the group sections, perform the following procedures. To view these procedures in order, use the Browse button (>>) in the Help window's toolbar.

Add the component library to the design

Add frames

See also

Add the component library to the design
Add frames


Add the component library to the design

You will use a set of pre-built components to add frames to the example report. These components are stored in a library file. Before you can use them in the report, you must include the library file in the report design.

1	Choose File→Include Module.

2	In List Files of Type, select Design Libraries (*rol).

The available component libraries appear in the list box.

3	Select actuate\devwb\examples\firstrpt\byfr.rol. Choose OK or Open, depending on your operating system.

The Library View appears, showing the pre-built components you will use to build the example report.

4	Position the Library View next to the structure pane in the Design Editor.

5	If you can see the individual controls such as text and label controls in the Library View, click the minus icons to shorten the list as in the illustration above.

To do the steps that follow, you only need to work with frames, not the individual controls inside the frames.

More information

You will use components from the library to build most of the example report. For more information about how library components are created, see Working with component libraries.


Add frames

1	Drag the CustomerTitle component from the Library View and drop it in the Content - CustomerGroup component's Before slot.

2	Repeat step 1 to drag the following frames from the Library View to the corresponding slots under the CustomerGroup and OrderGroup components.

You may wish to click on the minus icons or the plus icons to shorten or expand the lists in the structure pane. This will help you view the group names and so drop each frame into the correct group.

Following this list is an illustration of which components to drop into which slots.

CustomerPageHeader→Page Header slot under Content-CustomerGroup
OrderTitleFrame→Before slot under Content-OrderGroup
OrdersPageHeader→Page Header slot under Content-Order Group
OrderTotalsFrame→After slot under Content-Order Group
CustomerGroupTotals→After slot under CustomerGroup

The following picture shows the frames you drag to the structure pane.

3	Choose File→Save to save changes to the report design.


Lesson 6. Add headers and totals to the report

Next, you will use the library components for report page headers and totals. These components cause the page header to appear at the top of every page in the report and the totals to appear at the end of the report.

1	Drag the ReportPageHeader component from the Library View and drop it into the first PageHeader slot, just under the DataStream-DataSource component, as in the following picture.

The ReportPageHeader component is part of your report design. The layout pane, which is on the right, shows the contents of the component.

When you run the report, the text contained in this ReportPageHeader library component will appear at the top of every page except the first page. In the next step, you define a different header to appear on the first page of the report.

2	Repeat step 1, dragging the ReportTitle component from the Library View to the first Before slot, which appears just below the PageHeader-ReportPage Header frame and its components.

This title will appear only at the beginning of the report. The page header, which you dragged to the structure pane in the previous step, will appear at the top of every page.

3	Repeat step 1 again, and drag the ReportTotals component from the Library View to the After slot, which is just below the Content-CustomerGroup frame and its components.

The report totals will appear at the end of the report. Because this report has no page footers and no subpages, leave the PageFooter and the Subpage slots empty.

4	Close the Library View.

5	To observe the groups, frames and contained components of your report, click the minus and plus icons in the structure pane a few times.

Note how the contained components are hidden.

6	Choose File→Save to save changes to the report.


Lesson 7. Build a frame and controls

In previous steps, you used pre-built frames from a library. Now you will create a frame yourself. This frame displays the data for each item in an order.

To build a frame and controls, perform the following procedures. To view these procedures in order, use the Browse button (>>) in the Help window's toolbar.

Add and size the frame

Add controls to display retrieved data

Specify the formula to calculate the extension

See also

Add and size the frame
Add controls to display retrieved data
Specify the formula to calculate the extension


Add and size the frame

1	Drag and drop a frame component from the Structure palette to the Content slot under Content-OrderGroup. The frame component button looks like a white page containing a graph, folded in the upper right corner.

2	Place your cursor in the layout pane, which is on the right side of your screen, and select the area under OrderGroup:Content-Frame.

3	Place your cursor on the handle, which is the small black box that appears on the edge of the frame, and drag the handle to enlarge the frame.


Add controls to display retrieved data

Next, you will add components called controls, which display the data retrieved by the query. Each control you add displays data from one database column. Actuate automatically adds a control for each column.

1	Choose View→Field List.

The Field List appears. It shows all the fields from all the columns included in the query you built earlier in this chapter.

Note that when you select a frame in the structure pane on the left, the corresponding frame and its layout area are selected in the layout pane on the right of your screen.

2	In the Field List, note the following five items.

items.category
items.itemCode
items.description
items.quantity
items.pricequote

3	Drag and drop these five items to the area under OrderGroup:Content-Frame in the layout pane, on the right side of the screen. Place each item to lie below its corresponding column heading of "Category," "Code," "Description," "Quantity," and "Price."

4	Work with the handles on each item to bring each item to a manageable size.

In this example, the area under the column heading "Extension" is blank. In the next procedure you will place a control to calculate the amount to appear under the "Extension" column.

5	As you drop each column name, Actuate adds a control to the report design and sets the control to display data from that field.

6	Close the Field List.

At this point it is difficult to modify the location of the column headers. You can do it, but you'll need to modify the library and drag and drop again from the Library View.

The next control you add calculates the total price for each item in the order group and displays it as a dollar amount, under the "Extension" column header. First you choose the currency control. Then you write a mathematical expression to calculate the dollar amount.

7	In the main component palette, choose the Controls palette.

The Controls palette appears.

8	Select the Currency control.

9	Drag the currency control to the right of the other controls, under the "Extension" column header.

The Component Properties dialog box appears, showing the ValueExp property of the currency control. In the next procedure, you will specify a value for this property.


Specify the formula to calculate the extension

In this procedure, you will write a mathematical expression to specify how the control you just added will calculate the item extension. This procedure is similar to programming a cell in a spreadsheet.

1	Click in the field to the right of ValueExp.

2	Type the following expression.

[items.quantity] * [items.pricequote]

3	Choose OK.

4	Close the Component Editor.

5	Choose File→Save to save changes to the report design.

More information

In steps 1 and 2, just above, you can type the expression for the ValueExp property. Or you can click the "3-dot" button to the right of the ValueExp field to activate the Expression Builder.

For more information about the Expression Builder, see About the Expression Builder.For more information about frames and controls, see Working with frames and controls.


Lesson 8. Change text formats

Next, you will change the font and size of text in the currency control.

You would usually set up the page layout at this point, but the report you are creating uses the default page layout supplied by Actuate when you started the report design. For information about how to design your own page layout, see Designing page layouts.

1	In the layout pane, select the currency control in the OrderGroupContent frame. Handles appear.

Ensure the formatting toolbar is visible.

2	If the formatting toolbar is not visible, choose View→Toolbars→Format.

3	In the formatting toolbar's font name list, select Arial.

4	In the formatting toolbar's size list, select 12 pt.

5	Choose File→Save to save changes to the report design.


Lesson 9. Configure the Table of Contents

Next, you will specify descriptive display names to appear in the report's online Table of Contents.

1	Click in the structure pane, which is on the left-hand side of your screen. Double-click the Content-CustomerGroup section.

The Component Editor appears.

2	Select the Properties tab.

3	Set the TocValueExp property by clicking the space to the right of TocValueExp. Choose the following value from the pull-down menu.

[customers.customName]

The Table of Contents is now set to display the customer names that are retrieved from the database. You can now find and go to the orders for each customer.

4	Press Apply and close the Component Editor.

5	Again in the structure pane, double click on Content-OrderGroup section to open the Component Editor.

6	Select the Properties tab.

7	Next to TocValueExp, type the following value.

"Order " & [orders.orderID]
You can also click on the 3-dot Expression Builder button to the right of the typing area. The Expression Builder helps you construct the expression.

8	Press Apply and close the Component Editor.

9	Choose File→Save to save changes to the report design.


Lesson 10. Run the report

Now you can run and view the report to test your design.

Students of Actuate might write a method at this point. This involves writing Actuate Basic code. For this example, you do not need to write any code. Other students may also perform debugging now. For information on debugging, see Chapter 12, "Debugging," in Programming with Actuate.

1	Choose Report→Build and Run

The Requester dialog box appears. This is where you type parameters that affect the running of the report, such as a range of dates.

2	The example report requires no parameters. Choose OK.

Status messages appear in the status line of the application window as Actuate prepares to run the report. Actuate writes and compiles Actuate Basic code based on the choices you made in the Design Editor.

When Actuate writes and compiles, factory processes generate the report for viewing.

3	The status line of the application window indicates when compiling is complete.

The Factory window appears. The page numbers climb as the factory runs the report. Actuate uses the query to retrieve data from the database. Actuate creates the frames and controls to display that data on the pages of your report.

4	The report appears in the Viewer as soon as the first page is generated. The first page will not, however, display the calculated sums next to "Total Sales Forecast" until the report generation is finished.

5	Once the generation is finished, page ahead one or two pages and then back to page one to update page one with the final information.
The calculated sums next to Total Sales Forecast now appear.

The report in the viewer is named MYREPORT.ROI. The .ROI extension indicates the report is a report object instance.

6	There are two places in the Design Editor you can look if your report doesn't appear as in the example shown.

First, examine your query statement.

1	Click inside the structure pane, on the left-hand side, to make it active.

2	Choose View→Query

3	When the dialog appears, choose OK.

4	Click anywhere inside the Query Editor to make it active.

5	Choose Report→Verify SQL. The Verify SQL button examines your SQL statement and tells you if it is valid or not.

6	Close the Query Editor window.

Second, examine your report design.

1	Choose Report→Verify Design.

2	Choose Full Check.

The status line at the bottom of the Design Editor explains whether or not the design is valid.

More information

To get a feel for Actuate Basic code, see "About the Method Editor"Chapter 3, "The Developer Workbench environment,"About the Method Editor and Programming with Actuate.


Lesson 11. View the finished report

In this procedure, you will see the active viewing features of the report.

Note that with the arrival of the generated report, the menu items at the top of the Developers Workbench have changed. You will work with these menu items as long as the MYREPORT.ROI file is open.

To view the finished report, perform the following procedures. To view these procedures in order, use the Browse button (>>) in the Help window's toolbar.

View the Online Help

Hyperlink

Hyperlinked table of contents

Search

See also

View the Online Help
Hyperlink
Hyperlinked table of contents
Search


View the Online Help

1	Position the mouse cursor on the date to the right of Needed / Forecast and press the right mouse button.

The context menu appears.

2	Choose Help.

A popup Help window appears.

In this report, following is some context-sensitive help to let users work effectively with your report.


Hyperlink

1	Go to page 3 by pressing the Go To Page button in your toolbar.

If this toolbar is not visible, choose View→Toolbars→Viewer.

2	Click on the company name, Advanced Engineering, at the top of the page. Because this company name has a hyperlink, the hand cursor to indicate hyperlink appears.

3	The hyperlink returns you to the second page, which is the start of information about that customer.

You can use this hyperlink on any customer name on any page of the report. Each hyperlink jumps to the first page of information for that customer.

The hyperlink shown here was implemented in the library components you added to the report.

You can add a hyperlink to almost any component by typing an expression in the component's LinkExp property.

For more information about hyperlink syntax, see  Programming for report viewing events in Programming with Actuate.


Hyperlinked table of contents

1	Choose View→Table of Contents. Or, you can click the Table of Contents button, that sits just above the selector arrow icon.

The Table of Contents window appears. Double-click the items in the window to jump to pages in the report.

Note that the Table of Contents contains two companies that contain Signal in their names. This will be important when you begin to Search, below.

2	Close the Table of Contents window.

The Table of Contents is generated when you build your report. The items in the Table of Contents window are detailed according to the Group components you have placed in your report design.

3	Using the Next Page button on the toolbar, page forward to page 2 of your report.


Search

1	Choose Search→Find. You can also press the binoculars icon in the toolbar.

The Search dialog box appears.

2	In the report, select the company name. The company name is Advanced Engineering.

You are specifying the object on which to search. The purpose of this step is to specify the object--the company name--not the value, which is Advanced Engineering.

3	In the Search dialog box, choose Add Selection.

4	In the Value column, type Signal*. You are replacing the previous entry of Advanced Engineering Inc.

This step lets you specify you want to search for all company names that begin with Signal.

5	Choose Search.

In the Results tab, the list of fields that contain the search criteria, Signal*, appears.

6	Click on the item in the list in the Results tab. The first page of information for that company name appears in BYFR.ROI.

7	You may then save this search criteria into a file, for later use. To save your search criteria, select Save As. You may then name and save your search criteria in a file with a report object search (.ROS) extension.

The Search facility is part of every Actuate report. For more information about creating search criteria, searching, and saving your search criteria into a file for use in another application, see Searching for and exporting report data in Using Reports.

More information

Although you did not do any programming to create this example report, you dragged and dropped a pre-built CustomerPageHeader frame from the library. This library component contains a hyperlink, which was created by programming.


Lesson 12. Print the report

Finally, you may want to print the finished report on paper.

1	Choose File→Print.

The Print dialog box appears.

2	Choose OK.


Lesson 13. Save as an HTML report

Save your .ROI file as HTML.

1	Choose Save As→HTML file.

2	Name your file with an .HTML extension.

3	Open your Internet browser.

4	Choose File→Open File and specify the file name of your .HTML file.

5	Choose Open. Specify the file name.

The report displays in your browser.

For more information on building an HTML report, see Building HTML reports.


Look at other examples

The example report you just finished building is one of many example reports supplied with the Developer Workbench. You will find all the example reports in Actuate\Devwb\Examples. Each report and its associated files, such as specialized databases and text files, reside in individual folders within the Examples folder.

The reports demonstrate design features and techniques. The steps for creating the reports are described in the text (.TXT) files in the example report folders.


A quick look at programming with Actuate Basic

You've just created a simple report without writing code. When you build and run your report, Actuate's factory processes translate your report design into Actuate Basic code and then into a viewable, printable document.

For more advanced reports, you'll want to write Actuate Basic code yourself. Actuate Basic handles situations where:

•	You need to take control of the normal report-generation process.

•	You need to add application-specific logic

•	You want your report to respond to user-triggered events when users view the report.

For complete information about programming in Actuate Basic, see Programming with Actuate.


Concepts

The following topics are available. To view the topics in order, use the Browse button (>>) in the Help window's toolbar.

•	Overview of the report design process

•	Overview of how Actuate builds a report

•	About components

•	About Actuate's object-oriented design


Overview of the report design process

The following paragraphs summarize the tasks involved in creating a report design. You do not necessarily have to perform the steps in the order in which they are presented here. You can perform most of these tasks through the visual interface provided by the Design Editor, which is introduced in About the Design Editor.

Setting up the report project

Start the Developer Workbench. Start a new report design or open an existing design. Include other designs or component libraries in the project.For information on developing an HTML report, see Building HTML reports.

Specifying data

Specify the source of information for the report. Set up the database connection and write the query. For more information about specifying data, see Query data streams.

Creating sections

Use sections to create the logical structure of the information in the report. For example, a section might group rows by company in a grouped report. For more information about sections, see Working with sections.

Creating frames and controls

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

Designing the page layouts

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

Setting properties

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

Programming methods (optional)

Write Actuate Basic procedures to modify the behavior of a component. For more information about methods, see Chapter 3, "Writing and using procedures," in Programming with Actuate.

Running the report

Generate code that implements your report design, compile the code, and run the report. For more information about running reports, see Using Reports.

Debugging the report

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

Viewing the report

Look at the report and test your design. After viewing, you can go back to the previous steps to fix errors or make improvements. For more information about viewing reports, see About the Viewer.


Overview of how Actuate builds a report

When you create and save a report design, you save the design in a report object design file, or .ROD. You then run the report to view current data in a finished version of the report. This section describes what happens internally as Actuate takes the report from the design stage to the finished report. The finished report, an .ROI or .HTML file, contains data and can be viewed or printed.

The following illustration shows the report-building process and the files that Actuate creates after each action.

Each step, except for compiling, corresponds to an item in the Report menu. You can, but do not have to, execute each step separately. For example, choosing Report→Build/Run/View executes all the steps shown in the illustration, from generate code to view.

The following topics describe the steps in more detail.

Generating and compiling code

Running the report executable (.ROX)

See also

Generating and compiling code
Running the report executable (.ROX)


Generating and compiling code

When you run the report, Actuate automatically writes Actuate Basic code and saves it in a Basic source (.BAS) file. The Basic source file contains Actuate Basic code, including class declarations, that corresponds to the information in the report design (.ROD) file.

After Actuate generates code, it compiles the Basic source file and creates an executable file, or .ROX. The executable is the file you run to create the finished report (.ROI or .HTML) for viewing or printing.

Tip

You can view the Basic source file in any word processor or text editor. Looking at the generated code is a good way to learn Actuate Basic and understand how Actuate creates reports. You cannot, however, compile the code any place other than in Actuate.

See also

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


How to generate code for a report design

Choose Report→Generate Code.

Actuate writes new Actuate Basic code based on the current version of your report design and saves it in a new Basic source (.BAS) file.


How to generate and compile code for a report design

Choose Report→Build.

Actuate writes new Actuate Basic code on the current version of your report design, saves it in a new Basic source (.BAS) file, then compiles the source file into an executable (.ROX) file.


Running the report executable (.ROX)

When you run the executable file, Actuate performs the following actions.

1	Builds the report. Some of the tasks Actuate performs include

•	Instantiating classes

•	Retrieving data from specified sources

•	Starts the factory and generation status window

2	Creates a report object instance (.ROI) file, which is made up of objects that store the finished report's structure and data. Or, the processes create an HTML file, which contains the objects that store the HTML report's structure and data.

Tip

When you create an HTML report, you can also keep the .ROI by overriding a method. For instructions on how to do this, see Building HTML reports.

3	Opens the Viewer window, which displays the .ROI file.

See also

How to run the report executable (.ROX)
How to run reports from the command line


How to run the report executable (.ROX)

Choose Report→Run or Report→Build/Run/View.

If you choose Report→Run, Actuate runs an existing report executable to create a report object instance (.ROI) or HTML file, for viewing.

If you choose Report→Build/Run/View, Actuate goes through the entire report-building process, that is, it generates the Actuate Basic code, compiles the code into an executable, then runs the executable to create the report for viewing.


How to run reports from the command line

The designer.exe command starts the Developer Workbench and opens the forecast report design.  The syntax for this command is

designer [-b] [file1 file2...filen] [-f filename.log]

The [-b] option causes the Developer Workbench to rebuild the report design file and exit. Without the [-b] option, the Developer Workbench starts and then opens the specified report design file.

The [-f filename.log] option causes a log file to be built. This log file contains the Developer Workbench processing information for the rebuilt reports. If you do not specify a log file is to be built, messages are sent to the command line window.

To use the designer command, type the command in a command window.

In this example, the report design FORECAST.ROD is in the current directory.

c:\Actuate\devwb\bin> designer forecast.rod

If the report is not in the current directory, you need to specify the path name, such as:

c:\Actuate\devwb\bin> designer ..\examples\forecast\forecast.rod.

In the above two examples, the command rebuilds the FORECAST.ROD and creates the files FORECAST.BAS and FORECAST.ROX. Because the
[-f filename.log] option is not included, errors in the code generation phase or the compilation phase are displayed in the command prompt window.

Developers can also use this executable code to convert report designs to the current release of Actuate software. For specific information on this conversion, see the Migrating Actuate Reports from Release 2 to Release 3 document.

For more in-depth information on factory processes, see The report-generation process,in Programming with Actuate.


About components

Components are the building blocks of a report design. Some of the components provided by Actuate include numeric controls, page layouts, and graphic components such as lines and rectangles. Components are represented as icons in the Design Editor's component palette. You can also see components in the structure and layout panes of the Design Editor. Components can be organized in libraries to make them easier to reuse and maintain.

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

You assemble components in a report design to perform a wide variety of reporting tasks. The Design Editor's structure pane shows a diagram of the relationships among all the components in your report design. For more information about the structure pane, see About the structure pane.

See also

Component relationships in a typical report


Component relationships in a typical report

The following illustration shows the relationships among components in a typical grouped report. In this report, order items are grouped by order number, and orders are grouped by customer name. For more information about grouped reports, see What is a grouped report?

This illustration shows the Design Editor's structure pane.

The component relationships determine how each component is used. For example, there are ten frame components in this example, but each one is used in a different way because of its relationship with other components.

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


About Actuate's object-oriented design

The Actuate reporting system is based on object-oriented programming, which is a programming technique that uses objects, not algorithms, as its fundamental building blocks. Whenever you build a report design with Actuate, you are writing an object-oriented program, whether or not you actually type the code yourself.

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

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

See also

About object-oriented programming
About the Actuate Foundation Classes


About object-oriented programming

To understand object orientation in Actuate, you need to understand three key concepts of object-oriented programming.

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

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

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

See also

About classes
About objects
The relationship between classes and objects
About inheritance


About classes

A class is a specification, or template, for creating objects. This specification is written in programming code and stored in a class library. In Actuate, classes are written in Actuate Basic.

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

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


About objects

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

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


The relationship between classes and objects

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

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

Similarly, a class specifies the characteristics that all objects instantiated from that class have. A text control class, for example, can specify a border style, a font, and an expression that determines the control's value. When you run the report, many text control objects can be instantiated from that one class. Each text control object may have a different value, but all follow the class specification regarding where that value comes from and how it is formatted.

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


About inheritance

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

The following illustration shows inheritance.

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

Benefits of inheritance

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

•	Easy maintenance

•	Reusable code

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

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

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


About the Actuate Foundation Classes

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

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

See also

Extending the AFC architecture


Extending the AFC architecture

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

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

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


Presenting data in crosstabs

The following topics are available. To view the topics in order, use the Browse button (>>) in the Help window's toolbar.

•	About crosstab reports

•	About designing crosstab reports

•	Laying out a crosstab report

•	Adding optional features to a crosstab report

•	Comprehensive crosstab example report


About crosstab reports

A crosstab, or cross tabulation, is an Actuate report that displays data in a spreadsheet format, using rows and columns. A crosstab could also be described as just a grouped report that follows certain guidelines. In a crosstab, every cell contains the results of a calculation of data. Because of all the calculations involved in a crosstab, the format is useful for viewing summaries of data.

The following illustration shows the parts of a simple Actuate crosstab report. This illustration is the CROSSTAB.ROI file, found in the Examples directory of the Developer Workbench.

This crosstab report performs a two-dimensional analysis of the data.

At the top of the report is the title frame of the report. The title frame is from the library. This title frame displays the title and column headers.

The columns, across the top, are the sales and dollar amounts of the products, the dynamic RAM, static RAM and controllers. The other dimension, moving down, are the rows. Rows are cities, which are regions and their sales representatives.

Each cell, or intersection of a row and column, displays a calculated value that represents both dimensions. The cell in the upper left corner of this report shows the dollar sales amounts for dynamic RAM for Diane Murphy in the Boston office.

In the illustration, the cells along the right edge of the report show totals for each row. The cells along the bottom of the report show totals for each column. The cell in the lower right corner shows the total number of the items sold in each geographic region.

By grouping the rows, you can show more levels of summary data. For example, you could include another office in New York state and then group the sales offices by state group and display totals for each state, with a grand total of all product lines at the end of the report.

Adding a state group, a process in which you create a three-level crosstab, is discussed in Designing a crosstab report with three group sections.


About designing crosstab reports

To design a crosstab report, perform three basic tasks.

1	Specify the rows and columns for your crosstab. To specify each of these, work with the columns from your database.

2	Add group sections.

3	Lay out the crosstab report.

First, decide which single database column you want to use to specify the columns of your crosstab. Then, specify which rows will be in your crosstab.

The column from the database that specifies columns for the crosstab is called the column key. The columns from your database items that specify rows in your crosstab are called the row keys.

In the Multichip Technology example shown in About crosstab reports, the product items are the column key. In the example, the sales rep group and the city group are the row keys. To design a crosstab report with three group sections, see Designing a crosstab report with three group sections. For more information about row and column keys, see About row keys and About the column key.

After you decide on the row and column keys, add a group section for each row key. For more information about how to use group sections in a crosstab report, see Using row keys as group sections in a crosstab report.

Finally, you use the Design Editor to lay out and format row and column labels, cells, totals, and gridlines. For more information about how to lay out a crosstab report, see Laying out a crosstab report.

See also

About row keys
About the column key
Using row keys as group sections in a crosstab report


About row keys

A row key is the database column that specifies a row or group of rows in a crosstab report. Use more than one row key if you want to group the rows. The following shows a crosstab with two row keys.


About the column key

A column key is a database column that specifies what will be tabulated in the columns of your crosstab report. Because each crosstab report has a fixed number of columns, you choose column keys that have a limited, predictable number of items in them. In this example, we're choosing the product items ([items.category]) as the column key.

The "Sales by Office and Salesrep" title and column labels reside in the library and are not part of the column key or any of the calculations.

Because you specify the columns in advance, the columns and their labels are static. However, when you run the report, the database from which you are receiving data may have changed, and there may be more column key values than you predicted.

To look at a simpler example, if you designed a crosstab with "year" as the column key and it previously displayed the five years from 1991 to 1995, you might have more column key values than you predicted. You wouldn't see a column with the heading "1996" but you would see totals on the right and at the bottom reflecting data from 1996.

Be sure, therefore, that your data stream restricts the data to only those values for which you have columns in the crosstab. The following illustration shows what might happen in one row of cells if database information changes after the columns are laid out.

To avoid these incorrect totals, write your SQL query to include a "Where" clause in which the "year" is restricted to the years 1991 through 1995. This way, the data stream selects only rows with dates from 1991 to 1995.


Using row keys as group sections in a crosstab report

By using multiple group sections in a crosstab report, you can show many levels of introductory and summary data. Each group section in a crosstab report corresponds to one of the row keys. Because there is no limit on the number of row keys, there can be many group sections in the report. You will always have at least one group section, because you must have at least one row key.

For most group sections, you typically use the Before and PageHeader slots to display the group label before the group, and you use the After and PageFooter slots to display totals and footers for the group.

The following illustration shows how groups of cells in a crosstab with two row keys, "city" and "salesrep," correspond to group section components in the structure pane of the Design Editor.

See also

About the innermost group section in a crosstab
Designing a crosstab report with three group sections


About the innermost group section in a crosstab

The innermost group section of a crosstab report corresponds to the innermost rows of cells in your report. If your report contains only one group section, it is considered the innermost for the purposes of this chapter.

You handle the innermost group section differently than you handle the other levels of group sections. With the innermost group section, you do not usually use the Connection slot (unless you have a highly complex report with a separate data stream for the innermost group).

With an innermost group section you also do not use its Before, PageHeader, PageFooter, After or Subpage slots. These slots interfere with the normal row pattern that readers expect to see in a crosstab.

In the innermost group section, you use controls to display the row label and row totals, as shown in the following illustration.

For more information about how to design titles and totals in the innermost group section, see How to design a crosstab row label and How to design a crosstab row total.


Designing a crosstab report with three group sections

The following illustration shows the example crosstab report of sales with three row keys, three group sections, and one column key. The state row key and its corresponding state group have been added to the earlier example. The row keys are now sales rep, city, and state. The totals are now

•	Row totals for the innermost group, which is the sales rep group

•	Column totals for the next-level group, which is the offices, or city group

•	Column totals for the outermost group, the state group

•	Column totals for the whole report. Column totals are not a group section.

Refer to the structure pane diagram in the next illustration to see where components were placed to design this report.


Laying out a crosstab report

To design your crosstab report, you perform the following basic procedures in order. For each procedure in this list, there is a corresponding section with detailed, step-by-step instructions.

1	Create a group section for each row key in your structure pane.

2	Add the group labels.

3	Design the column labels.

4	Design the row labels.

5	Design the cells.

6	Design a row total.

7	Design column totals.

8	Design any optional features, such as a report title.

The instructions in this chapter assume that you know how to use the Design Editor to perform basic tasks such as placing components, sizing components, and setting properties. If you are not familiar with these procedures, see Using the Design Editor.

These instructions describe how to build a typical crosstab report like the one in the earlier illustrations. For an example of how to build a more complex crosstab, see Adding optional features to a crosstab report.

The following diagram illustrates most of the components and slots you use to design each part of a crosstab report.

See also

How to lay out a crosstab report


How to lay out a crosstab report

The steps needed to create a crosstab report are the following. They are covered in the sections that follow.

•	Add a group section

•	Add group labels

•	Add crosstab column labels

•	Add a crosstab row label

•	Design the cells

•	Design the row totals

•	Design the column totals

See also

How to add group sections to a crosstab report
How to add group labels to a crosstab report
How to design crosstab column labels
How to design a crosstab row label
How to design crosstab cells
How to design a crosstab row total
How to design crosstab column totals


How to add group sections to a crosstab report

1	Place a group section in the report design in the structure pane for each of the row keys. To do this, drag-and-drop a Group component into the appropriate Content slot.

For more information about how to place a group section, see Placing a group section in a report design.

2	Set each group section's Key property. The Key property contains a database column name that specifies one of the row keys.

Note that the nesting of the group sections displays for you where the outermost group section is in relation to the innermost group section. The key property, contained in each group section, reflects the set over which you are calculating. For example, in the offices group section, which is the innermost section in the earlier examples, the key property groups rows based on the value in offices.city.

If your report has just one row key, skip the next procedure, How to add group labels to a crosstab report. Instead, go directly to How to design crosstab column labels.


How to add group labels to a crosstab report

1	Place a frame in the Before slot of the outermost group section and size the frame to the desired height. If you wish to name the group, use the Prompt for Name option available on the context menu.

2	Place a data control in the frame.

If you use the Field List to place the control, skip step 3. For more information about the Field List, see Placing data controls in a frame.

3	Set the control's ValueExp property to be the same as that contained in the Group section's key. Find the Group section's key in the Group section's Properties dialog box.

4	Repeat steps 1 through 3 for each group section except the innermost.

You will design a label for the innermost group section later, in How to design a crosstab row label.


How to design crosstab column labels

To design crosstab column labels, skip down to step 2 of the following procedure if

•	You already placed a frame in the Before slot of each group section, or

•	While performing the previous procedure How to add group labels to a crosstab report, you placed a frame in the Before slot

You'll need to start at step 1 in the procedure if your report contains only one group section.

In step 1 of this procedure, you will place a frame in the Before slot of either the report or a group section. The slot you choose affects where the column labels appear in the report. The following illustration shows the results of placing the column labels in each of the possible slots in a report with two row keys.

1	Place a frame in the Before slot of the report or of a group section, and size the frame to the desired height.

2	Add a control for the first column heading, and size the control to the desired column width.

3	Set the control's ValueExp property to the column key you want to appear above the column. If you used a label control, set the control's Text property to text, a literal string, that is the value of the category key. The Text property may contain "State," for example, if the group's category key is the state.

4	If you want to draw gridlines around the column headings, set the control's Border property and choose one of the Pen styles.

For more information about the Border property, see Drawing a border around a frame or control.

5	Repeat steps 2 and 3 to place additional controls for each column heading.

You can copy or subclass the original control to speed up the process. For more information about copying and subclassing components, see Copying, subclassing and referencing components.

6	If you want the column headings to repeat at the top of each page if the report or section continues for more than one page, perform the following steps.

•	Ctrl + Shift + drag the frame from the Before slot to the PageHeader slot of the same report or group section.

•	Select Create a reference to the component.


How to design a crosstab row label

1	Place a frame in the Content slot of the innermost group section, and size the frame to the desired height of one crosstab row.

2	Place a data control at the left side of the frame, and size it to the same height as the frame.

3	Set the control's ValueExp property to specify the row label. You can use the name of the column that specifies the row key. If the report has multiple row keys, use the last row key in the list.


How to design crosstab cells

1	Add a data control to the right of the previous control in the crosstab row frame.

2	Size the new control to the height of the frame and the same column width as its column label in the Before frame.

3	Set the control's ValueExp property to an expression that computes the value of the cell and selects those values that belong in this column.

To compute the value, use an aggregate function. To select values, use a Where clause. For example:

Sum( [sales] ) Where( [invoice.region] = "Western" )

For more information about aggregate expressions, see Computing aggregates in a value expression.

4	To draw gridlines between the cells in the viewable report (not in the Design Editor), set the control's Border property and Pen property to the lines you wish.

5	Use the context menu to choose the various aligning functions. Align, Layers and the other choices let you line up each cell inside each frame.

For more information about the Border property, see Drawing a border around a frame or control.

6	Repeat steps 1 through 4 to add controls for the rest of the columns in the crosstab.

When you repeat step 1, you can copy or subclass the original control to speed up the process. For more information about copying and subclassing components, see Copying, subclassing and referencing components.


How to design a crosstab row total

1	Add a data control to the right of all the cell controls in the crosstab row frame.

2	Size the new control and set its border style as you did for the other controls.

3	Set the control's ValueExp property to the same aggregate expression you used in the cells, but omit the Where clause. For example,

Sum( [sales] )


How to design crosstab column totals

1	Ctrl + Shift + drag the crosstab row frame from the Content slot of the innermost group section to the After slot of the component that contains the group section. That is, drag the frame to one of the following slots:

•	If the report has multiple row keys, drag the frame to the After slot of the group section one nesting level up.

•	If the report has only one row key, drag the frame to the After slot of the report.

2	Select Create a subclass of the component.

3	Delete the first control in the frame (the row label).

4	To add column totals to additional group sections, repeat steps 1 and 2, dropping the frame in the After slot of each additional group section.


Adding optional features to a crosstab report

The step-by-step procedures in this section describe how to design the essential features of a typical crosstab report. You can also add other features to the report, just as you can any other report design. You can add any feature to a crosstab report that does not interfere with the essential features already described. For example, you can add more controls to the frames to display extra information, or you can customize the page layout by adding a company logo or page number. As with any report, you can write Actuate Basic code to modify any aspect of a crosstab report.

The following illustration shows a different type of crosstab report, an expense report that compares actual and planned expenditures. Instead of showing one value per column, it divides each column into several related categories. Each cell includes several controls instead of just one. Each control shows a different calculation.


Comprehensive crosstab example report

This section shows details of the example crosstab report that is provided with Actuate software. To see this crosstab report online, open the example crosstab report that was installed along with your Developer Workbench software. This report design uses the ODBC data source Crosstab Data.  The database file is included, but you must set up the ODBC data source to access it.

The following illustration shows the finished crosstab report as it appears in the Viewer.

The following illustration shows the database tables and the query used in this report.

Items.category is the column key and offices.city and salesreps.last are the row keys.

The following illustration shows the label controls in the ReportTitleFrame as they appear in the layout pane of the Design Editor. The text in each control shows the setting of each control's Text property.

Note

In the following illustrations, Display Sample Data is turned on and Outline Components is turned off. These settings are located on the Design Editor tab of the Options dialog box.

The following illustration shows the text control in the OfficesFrame. This control's ValueExp property is set to [offices.city], the first row key in the query.

The following illustration shows the controls in the SalesrepsFrame. The first control is a text control that uses the second row key ([salesreps.last]) to show the salesreps' first and last names at the left of each row of cells. The remaining controls are currency controls and integer controls that show the calculated values in the cells. Each cell contains two controls: a currency control that shows the dollar amount of sales and an integer control that shows the number of units sold.

Controls	Setting of ValueExp properties
Row label	[salesreps.last] & ", " & [salesreps.first]
Cell 1	Sum([items.quantity] * [items.pricequote]) Where ([items.category] = "Dynamic Ram") Sum([items.quantity]) Where ([items.category] = "Dynamic Ram")
Cell 2	Sum([items.quantity] * [items.pricequote]) Where ([items.category] = "Static Ram") Sum([items.quantity]) Where ([items.category] = "Static Ram")
Cell 3	Sum([items.quantity] * [items.pricequote]) Where ([items.category] = "Controller") Sum([items.quantity]) Where ([items.category] = "Controller")
Row total	Sum([items.quantity] * [items.pricequote]) Sum([items.quantity])

The OfficeTotalFrame and the GrandTotalFrame both inherit from the SalesrepsFrame, so their controls use the same expressions. In the OfficeTotalFrame, the text control's ValueExp property is set to
[offices.city] & " Office Total". In the GrandTotalFrame, the text control is replaced with a label control that displays the words Grand Total.


Working with reports in the enterprise environment

The following topics are available. To view the topics in order, use the Browse button (>>) in the Help window's toolbar.

•	About the enterprise reporting environment

•	What is the Report Encyclopedia?

•	Connecting to the Report Encyclopedia

•	Working with folders and files in the Report Encyclopedia

•	What to do in the event of a system failure


About the enterprise reporting environment

In an enterprise environment, corporations need a way to design, publish, and distribute reports on a regular basis. Reporting is moving from the mainframe applications and data into networked environments. These include client/server deployment, data warehousing, the internet, intranet, and extranets.

Online reporting provides a highly searchable and easily updated alternative to traditional reporting. In that environment, thousands of users may be accessing information and updating data, so conserving network bandwidth and managing database loads to provide scalability is a critical issue.

You can store, view, print, and generate new reports on either a client or server machine. To perform these tasks on a client or stand alone machine, you can use the Developer Workbench, End User Desktop, Administrator Desktop or a web browser with the Actuate LRX installed. To perform these tasks on a server, your computer must be connected to a server running Actuate Report Server.


What is the Report Encyclopedia?

The Report Encyclopedia is a shared repository that contains all the items the Report Server manages. Users in a enterprise environment distribute and share report files by storing them in the Report Encyclopedia.

See also

Report Encyclopedia features
Organization of a Report Encyclopedia


Report Encyclopedia features

The following are the key features the Report Encyclopedia provides:

Feature	Lets you ...
Familiar file management system	Create and work with hierarchical folders to organize report files.
Multilevel security	Limit report generation and viewing to authorized users. You can assign different privileges on a file or user basis.
Autoversioning	Group related report files to maintain different versions of reports that run on a regular schedule.
Flexible scheduling	Generate new reports at specified times. You can set a report to run once or on a regular basis.
Automatic notification and distribution	Place completed reports in specified folders and send notices to users.
Access using web browsers	View Report Encyclopedia contents over the World Wide Web


Organization of a Report Encyclopedia

The Report Encyclopedia consists of volumes. A volume is a collection of Encyclopedia items managed by a Report Server. Administrators create volumes to group parts of a large Encyclopedia into convenient and manageable clusters. Within each volume are items such as folders, report files, and printers. The following illustration shows an example of the organization of a Report Encyclopedia.


Connecting to the Report Encyclopedia

To connect to and explore a Report Encyclopedia, use either the Navigator or a web browser. For information on connecting to the Report Encyclopedia using a web browser, see Working with reports in the enterprise environment.

Using the Navigator, you connect to a Report Encyclopedia by specifying the volume (machine name) whose items you want to access. You have access to a volume if the following two requirements are met:

1	Your machine is connected to a server running Actuate Report Server.

2	You have an assigned user name and password for the volume. The user name and password are set up by the Report Server administrator.

The Navigator can log in to only one volume at a time.

See also

How to connect to a Report Encyclopedia
Solving login problems
Using multiple Navigator windows
Understanding the Navigator window


How to connect to a Report Encyclopedia

1	 Choose the Navigator toolbar button.

The Report Encyclopedia Login dialog box appears.

2	Type your user name as assigned by your system administrator.

3	Type your password as assigned by your system administrator.

4	Type the name of the volume of the Report Encyclopedia in which you wish to access reports. The volume name is the name of the computer running the Report Server. For a list of volume names, contact your server administrator.

5	Choose OK.

The Navigator window appears, displaying the contents of the volume you selected, as shown in the following example illustration.


Solving login problems

If you get the message "Log in Failed" when connecting to the Report Encyclopedia, contact your system administrator to verify the following information.

1	Confirm that you are using the correct user name, password, and volume information. If you are, go to step 2.

2	Check that the Report Server and the server on which it is installed are running. If both are running, go to step 3.

3	Check that your computer has network access to the server.


Using multiple Navigator windows

You can log in to multiple volumes by opening multiple Navigator windows. Another useful strategy is to open multiple Navigator windows to have multiple views of the same volume.

The following illustration shows items for two different users on the same volume.


Understanding the Navigator window

You use the Navigator to access and work with items in the Report Encyclopedia. If you are a Windows 95 user, you will find that the Navigator features and interface resemble that of the Windows Explorer.

Like the Explorer window, the Navigator window is divided into two panes. The left pane displays the hierarchy of items in a volume in the Report Encyclopedia. The right pane displays the contents of an item selected in the left pane. You can change the size of either pane by moving the splitter bar that divides the window.


Working with folders and files in the Report Encyclopedia

As you would expect of a file management interface, the Navigator provides features you can use to manage the Report Encyclopedia. The following are some of the common tasks you can perform.

•	View the hierarchy of folders and files.

•	Search for files.

•	Inspect the properties of folders and files.

•	Add, move, copy, delete, and rename folders and files. Your ability to do these tasks depends on the privileges you have been assigned.

•	Control user access to folders and files you create or add.

To execute these tasks, use the context menus associated with the report items, or choose menu items from the menu bar. You can also drag and drop to move and copy folders or folder contents.

See also

Accessing folders and files in the Report Encyclopedia
Understanding types of Report Encyclopedia folders
Understanding the types of Report Encyclopedia files
Using file versions
Viewing the hierarchy of items in the Report Encyclopedia
Changing the appearance and order of items in a Report Encyclopedia folder
Getting information about Report Encyclopedia items
Searching for folders and files in the Report Encyclopedia
Creating a new folder in the Report Encyclopedia
Copying files to the Report Encyclopedia
Copying and moving files within the Report Encyclopedia
Copying files from the Report Encyclopedia
Setting file dependencies in the Report Encyclopedia
Deleting Report Encyclopedia folders and files
Assigning privileges for Report Encyclopedia folders and files


Accessing folders and files in the Report Encyclopedia

One of the key requirements in the enterprise environment is security. The Report Encyclopedia limits access to folders and files. Access is granted by:

1	The Administrator

2	The owner, or creator, of a specific folder or file

When you connect to a Report Encyclopedia volume, the items you see are those which you have been granted read privilege. For more information about privileges, see Assigning privileges for Report Encyclopedia folders and files.


Understanding types of Report Encyclopedia folders

As a user, the following are types of folders you can access:

•	Encyclopedia home folder, that can be accessed by all users

•	Item folders, which contain report files and/or other item folders

•	Printers folder, which lists the network printers you can use

•	Requests folder, which contains information about report requests you submit

The following illustration shows the Report Encyclopedia home folder and the types of folders you work with in the Report Encyclopedia.

See also

Item folders in the Report Encyclopedia
Printers folder in the Report Encyclopedia
Requests folder in the Report Encyclopedia


Item folders in the Report Encyclopedia

There are two types of item folders you can access:

•	Folders owned by other users, for which you have been granted read privilege.

•	Your personal folder, if the administrator created one. The purpose of the personal folder is to provide each user with a private location that other users cannot access. A user owns his or her personal folder and controls if and how other users can access its contents.


Printers folder in the Report Encyclopedia

The Printers folder lists the network printers available to Report Encyclopedia users. You can inspect and change the properties of each printer to suit your printing requirements. For information about setting printer properties, see Setting printer properties in the Report Encyclopedia.


Requests folder in the Report Encyclopedia

The Requests folder is a system folder, which you access to find the status of report generation requests. If you are using Actuate client software such as the Actuate End User Desktop, you can view scheduled requests and create requests. For information about creating report requests, see Creating a request to run a report in the Report Encyclopedia.

The Requests folder contains three subfolders: Scheduled, Active, and Completed:

•	The Scheduled folder shows requests you scheduled to run at a later date and time

•	The Active folder shows requests you scheduled that are currently in the process queue

•	The Completed folder shows requests that have been processed. These requests are requests you submitted, or requests for reports that other users have asked be sent to you.

If you are using the Actuate Viewer, you see only the Completed folder and requests that have been processed.

The following illustration shows the Scheduled folder containing one scheduled report request.


Understanding the types of Report Encyclopedia files

As you browse the contents of folders in the Report Encyclopedia, you are likely to see a variety of file types, each with a specific function. File names and their associated types are listed in the right pane of the Navigator window, as the following illustration shows.

Understanding the different types of files and their functions helps you better manage and use files in the Report Encyclopedia. For example, if you copy a report document (.ROI) file from your local machine to your home folder in the Report Encyclopedia, you might also want to copy the associated report executable (.ROX) file to allow other users to run it to generate a report document with the latest data.

The following are the file types you might see in the Report Encyclopedia:

•	Report document (.ROI) files

•	Executable (.ROX) files

•	Parameter values (.ROV) files

•	Design (.ROD) files

•	Source (.BAS) files

•	Library (.ROL) files

See also

Report document (.ROI) files
HTML report document (.ROW) files
Executable (.ROX) files
Parameter values (.ROV) files
Search definition (.ROS) files
Design (.ROD) files
Basic Source (.BAS) files
Library (.ROL) files


 Report document (.ROI) files

Report documents are the finished reports you view and print. Use the Developer Workbench, End User Desktop, or Administrator Desktop to create report document files. These can be viewed in the client/server environment using the Viewer. Actuate reports can be viewed with a web browser using the Actuate LRX (Live Report Extension).


 HTML report document (.ROW) files

HTML report documents are created in the Report Encyclopedia when you run report executables that generate HTML reports. Use the Developer Workbench, End User Desktop, or Administrator Desktop to create HTML report files. An HTML report document is used only in the Report Encyclopedia. An HTML report document contains HTML files and other related files such as graphics files. When you view an HTML report document, the Report Server displays the HTML files and graphics in your web browser. You do not need the Actuate LRX to view an HTML report in your web browser.


 Executable (.ROX) files

Executables are files you run to generate report documents with current data. Use the Developer Workbench to create report executables. For information about running executables, see Running a report in the Report Encyclopedia.


 Parameter values (.ROV) files

Parameter values files store parameter values specified for a specific report executable. Use the Requester in the Developer Workbench, End User Desktop, and Administrator Desktop to create parameter values files. The values in a parameter values file typically filter the data that appears in a report document. You run a parameter values file to generate a report with a specified set of criteria. For more information about parameter values, see Specifying report parameters.


Search definition (.ROS) files

Save and use searches stored in search definition (.ROS) files on an Actuate report document. A search definition file contains search criteria, data to display, extract options, and report document structure information. For more information about search definition files, see Using search definition files.


 Design (.ROD) files

Design files contain components that specify the format and content of a finished report. Use the Developer Workbench to create report designs. Report developers might store design files in the Report Encyclopedia as backups or for sharing with other developers. You can open and edit a design file only on a client machine. You do not need access to design files to run, view, or print reports.


 Basic Source (.BAS) files

Source files contain Actuate Basic code associated with a specific report design. Use the Developer Workbench to create source files. Report developers might store source files in the Report Encyclopedia as backups or for sharing with other developers. You can open and edit a source file only on a client machine. You do not need access to source files to run, view, or print reports.


 Library (.ROL) files

Library files contain reusable report components. Use the Developer Workbench to create library files. Library files are typically included with different report design files. Report developers might store library files in the Report Encyclopedia as backups or for sharing with other developers. You can open and edit a library file only on a client machine. You do not need access to library files to run, view, or print reports.


Using file versions

The Report Encyclopedia provides an autoversioning feature that lets you maintain different versions of a report. You can, for example, generate multiple reports from a report executable or parameter values file, and save each report as a different version. This capability is useful if you generate reports regularly and want to retain previous copies of the report. You set the versioning feature when you run a report executable. For information about running a report executable, see Running a report in the Report Encyclopedia.


Viewing the hierarchy of items in the Report Encyclopedia

When you first start the Navigator, the window displays the top-level folders in the Report Encyclopedia volume. To expand and collapse the levels, click the plus (+) and minus (-) signs.

See also

How to view the hierarchy of items in the Report Encyclopedia


How to view the hierarchy of items in the Report Encyclopedia

1	Click an item on the left side of the window to display its contents on the right.

2	Click the plus (+) sign to display more levels.


Changing the appearance and order of items in a Report Encyclopedia folder

By default, all contents of a selected folder appear in the right pane of the Navigator window and are arranged in alphabetical order. You can, however, choose the file types and sort the items in a number of ways. The following illustration shows all files sorted by name.

See also

How to change the appearance and order of items in a folder


How to change the appearance and order of items in a folder

1	Choose the View menu.

2	Choose the types of files you want to view.

3	Choose one of the sort options.


Getting information about Report Encyclopedia items

The Report Encyclopedia maintains a lot of useful information about each item it contains. For example, for any given file, you can check its version name, its owner, the files it depends on, users with privileges to the file, and so on. Using this information, you can better manage your home folder and analyze information in other folders.

Information about an item is displayed two ways: An abbreviated version appears in the right pane of the Navigator for any item selected in the left pane, or you can use the context menu to bring up the property dialog box.

See also

How to inspect the properties of a Report Encyclopedia item


How to inspect the properties of a Report Encyclopedia item

1	Select the item whose properties you want to see.

2	Press the right mouse button and choose Properties from the context menu.

The Properties dialog box for the item appears. This dialog box displays different information depending on the type of item. The Requests folders, for example, are managed by the system, so you'll see only general information. If files are highly customized by users, so you'll see more information about them.

The following illustration shows the Properties dialog box for a report document.


Searching for folders and files in the Report Encyclopedia

You can search for Report Encyclopedia folders or files using any combination of the following criteria:

•	File or folder name, including wildcard characters

•	Location, including or excluding subfolders

•	Creator of the file or folder

•	Date of creation

•	Users who modified the file or folder

•	Date of modification

•	Item type, for example, folder or any report file type

•	File version

•	Content of comments

•	File or folder size

See also

How to find a file or folder in the Report Encyclopedia


How to find a file or folder in the Report Encyclopedia

1	 Choose the Search Encyclopedia toolbar button.

The Search dialog box appears.

2	In the Named box, type all or part of the folder or file's name.

You can use any of the standard wildcard characters. If you do not know the name of a file or want to refine the search, choose the Users & Dates or Advanced tabs.

3	In the Look in box, type the location or select an item in the Navigator Window where Actuate should begin its search.

Tip

To search the entire Report Encyclopedia, type / (forward slash) or select the Encyclopedia or volume icon in the left pane of the Navigator window.

4	Choose Find Now to start the search.

Actuate displays the results in the bottom section of the Search dialog box. From the results section, you can view report documents and use the file's context menu to perform other operations.


Creating a new folder in the Report Encyclopedia

You can create folders in your home folder and in other folders for which you have been assigned the write privilege. For a folder, the administrator or other users with grant privilege can assign the write privilege.

See also

How to create a new folder in the Report Encyclopedia


How to create a new folder in the Report Encyclopedia

1	Select the folder that will contain the new folder.

2	Press the right mouse button and choose New Folder from the context menu, as shown in the following illustration.

A new folder appears. The default name is New Folder.

3	Enter the name of the new folder.

4	To make the folder available to other users, assign privileges to specific users.

For information about assigning privileges on items you create, see Assigning privileges for Report Encyclopedia folders and files.

If you do not assign privileges, users have the default privileges the administrator assigned to your privilege template. For information on assigning privileges and privilege templates, see Using default privileges.


Copying files to the Report Encyclopedia

You can copy files into your home folder or any folder for which you have been granted the write privilege by the administrator or by another user. You can copy files from a local machine, a network file server, or from another Report Encyclopedia folder.

The Report Encyclopedia recognizes and interacts with Actuate report files. For a list and description of files that the Report Encyclopedia can use, see Understanding the types of Report Encyclopedia files.

See also

How to copy a file from a local or server machine to the Report Encyclopedia


How to copy a file from a local or server machine to the Report Encyclopedia

There are two ways to copy a file from a local or server machine to the Report Encyclopedia. You can use drag and drop, main menu or context menu commands. The following steps describe how to copy a file using context menu commands.

1	Select the folder that will contain the copied file.

2	Press the right mouse button and choose New Report Item from the context menu. You can also choose File→New Encyclopedia Item→Report Item from the main menu.

The Open dialog box appears.

3	Select the file to copy, then choose Open.

The file name and description of the copied file appears in the right pane of the Navigator.

Once you copy a file to the Report Encyclopedia, do the following:

•	Set the file dependencies, if appropriate. For information on setting file dependencies, see Setting file dependencies in the Report Encyclopedia.

•	Assign privileges to users, if you want others to access the file. If you ignore this option, users have the default privileges the administrator assigned to them. For information about assigning privileges on items you create, see Assigning privileges for Report Encyclopedia folders and files.


Copying and moving files within the Report Encyclopedia

When you copy or move a file from one Report Encyclopedia folder to another, all the original file's properties--including privileges--apply to the file that is copied or moved.

See also

How to copy a file from one folder to another in the Report Encyclopedia
How to move a file from one folder to another in the Report Encyclopedia


How to copy a file from one folder to another in the Report Encyclopedia

1	Press Ctrl and select the file to copy.

2	Drag the file to the destination folder.


How to move a file from one folder to another in the Report Encyclopedia

1	Select the file to copy.

2	Drag the file to the destination folder.


Copying files from the Report Encyclopedia

You can copy report files from the Report Encyclopedia to a local machine or network file server. If you copy a report document and you plan to open it on your local machine, make sure you copy the associated report executable as well.

See also

How to copy files from the Report Encyclopedia to a local system or network file server


How to copy files from the Report Encyclopedia to a local system or network file server

1	Open the Windows Explorer or File Manager.

2	Drag the file from the Navigator window to the destination folder in Explorer or File Manager.


Setting file dependencies in the Report Encyclopedia

Some report files depend on the existence of others. In order for certain operations to execute successfully, dependent files must be able to access the files they depend on,. The most common example is the association between a report document and a report executable. When you open a report for viewing or printing, Actuate runs the report executable from which the report was generated.

If you try to delete an executable from the Report Encyclopedia, Actuate displays a dialog box that specifies the files that are dependent on the executable, and asks if you want to delete the executable and its dependent files.

Types of file dependencies

The following table lists the dependencies among file types.

This file ...	Depends on ...
Report document	Report executable
Report parameter values	Report executable

See also

When the Report Server sets up file dependencies
When you need to set up file dependencies
How to set file dependencies in the Report Encyclopedia


When the Report Server sets up file dependencies

The dependency between a document and an executable is set automatically when you run an executable in the Report Encyclopedia. Similarly, the dependency between a parameter values file and an executable is set automatically when you create and save a parameter values file in the Report Encyclopedia.


When you need to set up file dependencies

If you copy a report document from a local system to the Report Encyclopedia, you need to take the following steps:

1	Copy the report to the Report Encyclopedia.

2	Copy the associated executable.

3	Set up the dependency between the files. For instructions, see "How to set file dependencies in the Report Encyclopedia" in the next section.

If you omit steps 2 and 3, you will not be able to open the report. The alternative is to bundle the executable with the report. Then, all you need to do is copy the report to the Report Encyclopedia. For information about bundling an executable with a report, see Distributing a report from a client system.


How to set file dependencies in the Report Encyclopedia

1	Select the file whose dependencies you want to set. For example, a report document depends on the executable. To set the dependency, select the report document.

2	Press the right mouse button and select Properties from the context menu.

The Properties dialog box appears with the General page open.

3	Choose the Dependency tab to display the Dependency page, shown in the following illustration.

4	Choose Add.

The Encyclopedia Browser appears.

5	Find and select the file that the dependent file requires, then choose OK.

The selected file appears in the File Depends On list.

6	If the dependent file depends on additional files, repeat steps 4 and 5 until you have selected all the files.

7	Choose OK.


Deleting Report Encyclopedia folders and files

You can only delete folders and files you create or for which you have been assigned the delete privilege. The delete privilege is assigned by the administrator or another user. Typically, the only folders and files you will delete will be in your home folder.

See also

How to delete a Report Encyclopedia folder or file


How to delete a Report Encyclopedia folder or file

1	Select the folder or file to delete. You need delete privileges to the selected item. If you delete a folder, items in the folder are deleted as well.

2	Press the right mouse button and choose Delete from the context menu.

If you delete a file, Actuate removes the file immediately unless another file depends on the file you want to delete. If there is a dependent file, Actuate displays a dialog box that specifies the files that are dependent on the file to delete, and asks if you want to delete the file and its dependent files. For more information about file dependencies, see Setting file dependencies in the Report Encyclopedia.


Assigning privileges for Report Encyclopedia folders and files

You can assign privileges for folders and files you create and for those to which you have been assigned the grant privilege by another user. Privileges indicate the operations users can perform on folders and files. For example, the read privilege for a file means users can view or print a file, but cannot change the file or delete it. Unless users have read or visible privilege on a folder or file, they do not see the folder or file in the Report Encyclopedia.

See also

Types of privileges
Assigning different privileges to different users
Assigning privileges to groups of users
Using default privileges
Summary of how the Report Server assigns privileges to items you create
How to assign privileges for a folder or file


Types of privileges

The following table lists the privileges you can assign to folders and files you create. Each row describes a single privilege and summarizes what that privilege means for different item types. Report Encyclopedia privileges are not additive. For example, if a user has write privilege on an item, that user does not automatically have read privilege on the item. The user must also have read privilege on the item or it is not visible.

The visible privilege lets you access as different users when you view the Report Encyclopedia from a web browser. For example, if you try to view a report document, or view its properties, and you only have the visible privilege for the document, the Report Server displays the Login dialog and lets you change your login to a user with different privileges.

Privilege	Item type	Meaning
Visible	Folder	Users can view the folder's contents.
	All other types	Users can see the object but they cannot run or view contents or view the object's properties.  If user is accessing the Report Encyclopedia with a Web browser, any attempt at viewing contents or properties brings up a dialog that lets them log into the Report Server as a user with the appropriate privilege.
Read	Report document	Users can view the report document.
	Report parameter values	Users can run the associated report executable if they also have read and execute privilege on the report document.
	All other types	Users can examine the item's properties and view or print the item's contents. If the item is a folder, users can see what it contains.
Write	Folder	Users can create new items in the folder, copy or move items into it, or rename it. Users can move the folder to a different containing folder if they have read and write privileges on the destination folder.
	All other types	Users can rename the item. Users can move the item to a different containing folder if they have read and write privileges on the destination folder.
Delete	Folder	Users can delete the folder if they have delete privilege on all the items in the folder.
	All other types	Users can delete the item.
Execute	Report executable, report parameter value	Users can schedule a new request for the item.  In addition, users must have read and write privileges to (1) the folder where the generated report document will be stored and (2) an existing report document if it will be versioned or replaced by the new report document. By default, the generated report document is placed in the same directory as the report executable.
Grant	All types	Users can grant any privilege on the item, including the grant privilege, to other users.


Assigning different privileges to different users

For each folder or file you create, you can assign different privileges to different users. For example, you might want to allow your team members to view a sales report you generated, as well as run the associated report executable. In this case, you would grant to your team members the read and write privileges on the report document, and grant read and execute privileges on the associated report executable.

You might want to allow members of another team only to view the report. In this case, you grant to those users only the read privilege on the report document and the associated report executable. You need to also assign the read privilege on the associated report executable because Actuate runs the report executable each time you open the report document for viewing or printing.

The following illustrates the above scenario. DAdams, JSalinger, and LThompson are your team members.


Assigning privileges to groups of users

A quicker way to assign the same folder or file privileges to a group of users is to assign privileges to a role. Roles are created by the administrator to group users that might require the same privileges on items. Using roles lets you assign and maintain privileges more consistently and with less effort.

For example, the administrator might create a role called Sales that groups all the sales representatives, and a role called R&D that groups all the engineers.

The following illustration shows how different privileges are granted to roles. If you compare the following illustration with the previous one, you will see the convenience of assigning privileges to roles--instead of selecting six users for each file, you select two roles for each file.

Who can create roles to group users?

Only the administrator can create roles. Contact the administrator if you want to know which users are included in the different roles, or if you need additional roles.


Using default privileges

Typically, you assign privileges on an item only if you want to make sure certain users have particular access to it. If you do not set privileges on an item you create, the Report Server applies the default privileges specified in your privilege template.

What is a privilege template?

Every user has a privilege template that specifies the privileges that other users have to items he or she creates. The default privilege template assigns the full set of privileges to the creator of the item and the administrator, and no privileges to other users.

Who can modify the privilege template?

Only the administrator can modify a user's privilege template. Contact the administrator if you want different defaults for your privilege template. For example, if you want your manager or your assistant to always have read and write privileges to items you create, ask the administrator to change your manager's or your assistant's privileges to your items accordingly.

The following illustration shows an example of a privilege template for a user, LThompson. In the example, the privilege template assigns all privileges to the administrator, read and write privileges to user BCarter, and the read privilege to user DAdams. These privileges apply to all items created by LThompson.


Summary of how the Report Server assigns privileges to items you create

When you create a folder or file in the Report Encyclopedia, the Report Server assigns privileges to those items in the following order:

1	The privileges you explicitly grant to other users. You need grant privilege on the object to change privileges on the object.

2	The privileges specified in your privilege template. Only the administrator can change your privilege template.

The following conceptual diagram summarizes how the Report Server assigns privileges to items you create.


How to assign privileges for a folder or file

1	Select the folder or file for which you want to set privileges.

2	Press the right mouse button and choose Properties from the context menu.

The Properties dialog box for the item appears.

3	Choose the Privileges tab.

The Privileges page displays the list of users and roles from which you can select to assign file or folder privileges. Users and roles are created by the administrator.

4	Select a user or role. To select multiple users or roles, press Ctrl as you click each name.

5	Select the privileges to assign to the selected user(s) or role(s).

6	Choose Apply to save the setting.

7	Repeat steps 4 through 6 until you have assigned privileges to all the users or roles to whom you want to give file or folder access.

8	When you have finished assigning privileges on the folder or file, choose OK.


What to do in the event of a system failure

If the Report Encyclopedia becomes unavailable--because of a machine or network connection failure--the information in the Report Encyclopedia is automatically restored to its last consistent state when the Report Server is restarted. Operations in progress at the time of the crash are backed out of the Report Encyclopedia.

For example, if you were in the process of copying a file to the Report Encyclopedia, that file might not have been copied. Or, if you had just submitted a request to run a report, that request might not exist in the Scheduled folder. When the Report Encyclopedia is available again, you should check the items you were working on prior to the crash to see if you need to perform a task again.

If reports were being generated when the Report Server failed, the Report Server restarts the generation process automatically. You do not need to take any crash recovery steps.

If you encounter any other problems after taking the crash recovery steps, contact the Report Server administrator.


Customizing the Developer Workbench environment

The following topics are available. To view the topics in order, use the Browse button (>>) in the Help window's toolbar.

•	Customizing component palettes

•	Customizing units of measurement

•	Moving and closing toolbars and palettes

•	Changing tool display options


Customizing component palettes

You can modify the component palettes that the Developer Workbench supplies. You can make the following changes to the main component palette as well as to each of the individual component palettes:

•	Add buttons

•	Change the location of buttons

•	Change the class that is associated with a button

•	Save a palette representation

•	Read a previously saved palette representation

These features enable you to customize the palettes to suit your individual needs. You can, for example, combine the various palettes into one palette that only contains the Actuate Foundation classes you frequently use. Or, you can replace some of the Actuate Foundation classes with custom classes you prefer to use.

In order to modify an individual component palette, the palette needs to be opened first. At any time, while customizing the component palettes, you can restore the palettes and the classes associated with the buttons to their default values.

See also

Customizing the palette layout
Customizing the class association of a palette
Saving and reusing class associations of palettes


Customizing the palette layout

You can change the position of a button within the palette by pressing the Shift key while dragging the button with the mouse and dropping the button in the new location.

See also

How to add a button to a palette
How to restore the default palette layout


How to add a button to a palette

1	Position the mouse pointer over the palette you want to modify.

2	Press the right mouse button.

3	Choose Customize Button Layout.

4	From the Available buttons list, drag-and-drop the button(s) you wish to add to the Toolbar buttons list. To add separators between buttons, select Separator from the Available buttons list.

5	Repeat step 4 until the Toolbar buttons list shows all the buttons and separators you want on the palette.

6	When you have finished modifying the palette, choose Close to save your changes.

You can undo changes at any time. To revert to the version of the palette in effect before this dialog box was opened, choose Reset.


How to restore the default palette layout

1	Position the mouse pointer over the palette you want to restore.

2	Press the right mouse button.

3	Choose Default Button Layout.

To restore the default button layout for all palettes at once, follow the previous steps with the mouse pointer positioned over the main component palette.


Customizing the class association of a palette

You can change the class that is associated with each button on a palette to use custom classes that are better suited to your work environment. You can also add custom classes to your palettes by adding buttons and associating these newly created buttons with your own frequently used classes. Choosing custom classes directly through the component palette saves time when designing reports, because you do not have to choose these classes through the library.

For example, you can add your own currency control, and have that control be the base control for currency columns in your database. When you create a control from the palette or drag a column of type currency from the Field List, Actuate uses your custom currency control instead of the default AFC currency control.

See also

How to change the class associated with a button on a palette
How to restore the default class association of a button on a palette


How to change the class associated with a button on a palette

1	Position the mouse pointer over any one of the palettes.

2	Press the right mouse button.

3	Choose Change Classes.

The Options dialog box appears. You can also access this dialog box by choosing View→Options, then selecting the Palette tab.

4	From the Palette Button Identifier list, select the component you want to modify.

5	If you want to change the default image associated with this component, select the desired image from the image list. You can select only images supplied with the application.

6	Under Full Class Name, enter the class name you want to associate with this component. When you add your own class name and this class name does not have a global scope, you need to specify the qualified class name, for example, ReportApp::OrderFrame::OrderIDControl.

You can also use the Browse (...) button to display a list of global classes from which you can select a class.

7	When you have finished modifying the class or classes, choose OK.


How to restore the default class association of a button on a palette

1	Position the mouse pointer over any button in one of the component palettes.

2	Press the right mouse button.

3	Choose Default Class Representation.


Saving and reusing class associations of palettes

After associating classes with buttons on the component palettes, you can save the configuration to an Actuate Palette Representation file, an .APR file. This .APR file can be used by others in your work group to duplicate the palette representation. You can create different representations for a variety of recurring tasks. By saving each of the representations to an .APR file, you can restore them later by reading the appropriate .APR file.

See also

How to save a palette representation to file
How to apply a previously defined palette class representation


How to save a palette representation to file

1	Position the mouse pointer over any one of the palettes.

2	Press the right mouse button.

3	Choose Change Classes.

4	Choose To File.

5	In File Name, type the name of the file to which to save your class associations.

6	Choose Save, then OK.

Your class association is saved to a Palette Representation (.APR) file.


How to apply a previously defined palette class representation

1	Position the mouse pointer over any one of the palettes.

2	Press the right mouse button.

3	Choose Change Classes.

4	Choose From File.

5	Select the Actuate palette representation (.APR) file from the list, or enter the file name you want to use. Choose Open, then OK.


Customizing units of measurement

You can choose the unit of measurement to work with when resizing and positioning components with properties like size, position, and so forth. This option makes it possible for you to work with familiar units.

When specifying the units of measurement, you can also specify some of the display options. You can, for example, choose to add a unit suffix, such as "cm," after the numeric value. You can also specify the number of digits the application displays after the decimal point.

See also

Setting the default unit of measurement
Customizing unit suffixes


Setting the default unit of measurement

By default, Actuate uses and displays twips as the unit of measurement when you enter values for properties such as size and position. You can, however, assign a different unit as the default unit of measurement for data entry and display. For internal use, Actuate converts the new default unit to twips.

You can assign one of the following units of measurement that Actuate recognizes.

•	Twips, the internal unit Actuate Basic uses

•	Points. 1 point equals 1/72 inch, 1 twip equals 1/20 point

•	Inches

•	Millimeters, 1mm equals .1 cm

•	Centimeters, 1 inch equals 2.54 cm

See also

How to set units of measurement


How to set units of measurement

1	Choose View→Options, then select the Units tab.

2	From the Display Unit list, select the unit of measurement.

3	If you want to display a unit suffix after the value, specify in Display Suffix the suffix to display.

For example, if you selected inches as the display unit and you want to display the abbreviation for inches, "in," after the unit value, type "in" in the Display Suffix field. For example, Actuate displays 2.23 in for the value 2.23. To display a space between the value and the suffix, enter a space before the suffix.

4	Under Decimals, specify the number of digits to display after the decimal point.

This option is for display only, and does not affect the mathematical precision Actuate uses in its calculations.


Customizing unit suffixes

The default unit of measurement determines the unit that Actuate displays by default when you enter numeric values for properties such as size and position. You can, however, explicitly specify a different unit for Actuate to display when you enter a value. For example, even if the default unit of measurement is set to inches, Actuate accepts data entered in centimeters if you add the suffix cm after the value.

By default, Actuate recognizes certain suffix strings, as the following table shows.

Unit	Default recognition string
Twips	tw
Points	pt, pts
Inches	in, "
Millimeters	mm
Centimeters	cm

You can, however, specify other strings for Actuate to recognize. You can, for example, specify c and m to allow unit recognition for centimeters and millimeters, respectively. Keep in mind that the application searches for the first match. If you specify m for metric as well as millimeters, you may get unpredictable results.

See also

How to specify the custom unit suffixes


How to specify the custom unit suffixes

1	Choose View→Options, then select the Units tab.

2	From the Recognize list, select the unit you want the application to recognize.

3	Under by, specify the string Actuate will use to recognize the unit. You only need to specify a recognition string if it differs from Actuate's default strings.

4	Repeat steps 2 and 3 until you have specified unique strings for all units you want Actuate to recognize.


Moving and closing toolbars and palettes

You can change the position of any of the toolbars or palettes by dragging them with the mouse from one part of the application window to another. You can close one, several, or all of the toolbars and palettes.

See also

Comparison of floating and docked toolbars


Comparison of floating and docked toolbars

You can let each toolbar or palette float in the active area of the application window, or you can attach it to an edge of the application window. When a toolbar or palette is attached to the edge of the window, it is docked.

You can open, close, and move a floating palette or toolbar independently from the application window. However, when you close the application window, the toolbar or palette disappears.

When a toolbar or palette is docked at an edge of the application window, it stays with that edge as you move, resize, close, and reopen the window.

The following illustrations show two ways you might arrange the toolbars and palettes. The first illustration shows toolbars docked at the top and bottom edges of the window and the main component palette docked at the left edge.

In the next illustration, both toolbars have been closed. One of the component palettes is floating to make adding components easier.

See also

How to move a toolbar or palette
How to close a toolbar
How to display a toolbar or palette


How to move a toolbar or palette

1	Position the mouse pointer in the background or on the edge of a toolbar or palette.

2	Drag the toolbar or palette to a new location.

A guideline appears to let you observe the path of the palette. When you move from a horizontal to a vertical window edge or vice versa, the guideline changes orientation. When you dock a toolbar on a vertical window edge, the drop-down list boxes that come from the toolbar are removed.

3	To attach the toolbar or palette to a window edge, release the mouse button when the guideline is partly outside and partly inside the blank area of the window.

4	To create a floating toolbar or palette, release the mouse button when the guideline is entirely inside or outside the blank area of the window, or when the guideline is at right angles to the edge of the window.


How to close a toolbar

1	Choose View→Toolbars.

A cascading menu appears.

2	Deselect the name of the toolbar.

How to close a palette

Palettes are not listed in the Toolbars menu.

1	Deselect the icon on the main component palette, or

2	Choose the close button on the palette.


How to display a toolbar or palette

1	Choose View→Toolbars.

A cascading menu appears.

2	Choose the toolbar or palette you want to open.


Changing tool display options

You can modify the way information appears. For example, you can customize the Design Editor to display long or short component names, show or hide empty slots, or display or hide gridlines.

See also

How to change tool display options


How to change tool display options

1	Choose View→Options.

The Options dialog box appears.

2	Click the appropriate tab. For example, to hide gridlines, click the Design Editor tab.

3	Make selections in the dialog box. Choose OK.


Query data streams

The following topics are available. To view the topics in order, use the Browse button (>>) in the Help window's toolbar.

•	How reports get data

•	About database connections

•	Defining database connections

•	About data streams

•	About sorting data

•	About queries

•	Writing queries

•	Query by Example (QBE) syntax

•	Using stored procedures


How reports get data

Before a report can present data, it must obtain that data. The following diagram shows how data flows to an Actuate report that uses a query data stream.

Item	Description
Data source	Stores data. A database is the most common place to get data, but a database is not the only option. For information about other ways to get data, see  Types of data streams.
Connection	Cable or other communication device and communication software that provide the communication link with the database. For more information about connections, see  About database connections.
Connection component	Stores the information that the report needs to connect to the database. For more information about connections, see  About database connections.
Data source component	Using the connection, selects data from the data source and puts the data into a data row. This chapter concentrates on one type of data source component called a query data source. For more information about query data sources, see  About query data source components.
Data row	A set of variables containing the data from the data source. The format of this row is defined by the data row component in the report design. For more information about data rows, see  About data rows.
Filter(s)	(Optional) One or more filters perform additional steps to put the data into the form required by the report. Each filter passes a data row on to the next filter in the data stream. If there are no filters, the data row from the data source component is passed directly to the report. For more information about filters, see  About data filters.
Report	The report receives data and displays it. The report must contain at least one report section component. For more information about report sections, see About report sections.


About database connections

A connection is a communication link with a database. An Actuate report design almost always contains at least one connection component, which is a component that establishes and maintains the connection. Every report that gets its data from a database must have at least one connection component and one data row component. A report may, however receive data from something other than a database, such as a flat file. Accessing a flat file may not require a connection component, but it probably will require at least a data source component and a data row component.

Actuate provides connection components for Microsoft SQL, Sybase, Oracle, Informix, Progress, DB2 and ODBC database connections. An Actuate report can contain connection components from different types of databases.

The connection component stores database-specific information needed to log on to the database server, such as server name, user name, and password. Each of these items is a property of the connection component. For example, the user name is set in the UserName property. For more information about properties, see Setting properties of components.

See also

Purpose of the connection


Purpose of the connection

The database connection serves two purposes:

•	When you build a query, the Query Editor uses the connection to get lists of tables and columns from which you choose. If you are working with stored procedures, you need the connection to access the database that contains the procedures.

•	When you run the report, the query uses the connection to get data for your report.


Defining database connections

In most report designs, you must define a database connection. There are two types of reports for which you do not need to define a database connection:

•	A report that shares a connection with another report. For more information about sharing a connection, see Sharing connections between report sections.

•	A report that does not get data from a database. For this type of report, you may need to write a custom data stream. Accessing a flat file of data, for example, requires that you work with a custom data stream. For information on accessing data in a flat file, see Accessing data from a flat file.

For more information about custom data streams, see also Programming with Actuate.

See also

How to define a database connection
About ODBC connections


How to define a database connection

1	Drag-and-drop a connection component from the component palette to a Connection slot.

For information about which Connection slot to choose, see Chapter 8, "The report generation process," in Programming with Actuate.

In the dialog box that appears, select the type of connection you require.

2	In the structure pane, double-click the connection component.

The Component Editor appears.

3	Type the connection properties required by your database server, as shown in the following table.

Connection type	Required connection properties	Optional connection properties
DB2	Name of data source DLL path User Name	Password may be required, depending on your user account.
Informix	User name Database environment (the database and/or server name)	Password may be required depending on your user account.
MS SQL	User name	Server name. If not supplied, Actuate defaults to locally defined server. Password may be required depending on your user account.
ODBC	Name of data source	Connection string User name and password may be required depending on which driver you are using. An ODBC connection allows you to work with available ODBC stored procedures, including those from PeopleSoft.
Oracle	User name Host string	Password may be required depending on your user account.
Progress	DatabaseList string DLL path Startup Parameters	User name and password may be required, depending on your user account.
Sybase	User name Server name	Password may be required depending on your user account.  A Sybase ctlib connection allows you to work with available Sybase stored procedures.

For details about the connection properties of a particular connection type, see your DBMS documentation.

If you do not supply the required connection properties by setting them in the connection component, the Database Login dialog box appears when Actuate needs to connect to the database. You or the report user types the connection properties at that time.


About ODBC connections

ODBC connections use two special connection properties, the data source name and connection string.

Before using an ODBC connection, you must create an ODBC data source using the ODBC administrator utility supplied with your ODBC driver software. See your ODBC documentation for information about how to set up the data source. Specify the name of this data source in the DataSource property of the connection component.

The connection string includes any other information needed to connect. The contents of this string depends on the driver you are using with your ODBC data source. For example, the connection string could include the name of an Excel file. See your ODBC driver documentation for information about the connection string for the driver you are using. Specify the connection string in the ConnectionString property field.


About data streams

A data stream is a group of components that provide the data for your report. The data stream selects data from a data source, such as a database or flat file. The data stream then puts the data into the data row structure required by the report.

A data stream is made up of several types of components. Every data stream has a data source component and a data row component. Additional, optional components include filters, memory buffers, and intermediate data rows.

You can use more than one data stream in a report design by adding more report sections. For more information about report sections, see About report sections.

See also

Types of data streams
About query data source components
About data rows
About data filters
About stored procedures


Types of data streams

Actuate reports can use data streams to get data from any source, not just relational databases. For the purposes of this discussion, data streams fall into three categories:

•	Query data stream--Uses a query data source component to obtain data from a relational database using a SQL query. The rest of this chapter discusses query data streams in detail.

•	Stored procedure--Uses a stored procedure component and data row component to obtain data through stored procedures from the database. For more information about stored procedures, see About stored procedures.

•	Custom data stream--Works with data stored in any format, not just relational databases. For example, use a custom data stream if you want to read data from a flat file or spreadsheet. For information on accessing data in a flat file, see Accessing data from a flat file.

•	You can also create custom data streams by programming in Actuate Basic. For more information about custom data streams, see Customizing examples in Programming with Actuate.


About query data source components

A query data stream always includes at least two components, a query data source and a data row. You can see these components in the structure pane of the Design Editor when you are building a report.

The query data source component contains a SQL query, which it uses to retrieve data from the database. Use the Query Editor to write the query. For more information about writing queries, see  About queries.

See also

Adding a query data source to a report design
How to add a query data source component to a report design


Adding a query data source to a report design

In a report design, the query data source component contains the query. Before you write the query, you must add a query data source component to the report design.

If you start a new report design by using the New Report Wizard, Actuate adds the data stream components to the report design, including the query data source component.

When you begin a new report design using a blank report design, or if you wish to work with stored procedures rather than the Query Editor, you add data stream components by dragging and dropping them. For information on working with a data stream with stored procedures, see About stored procedures and Using stored procedures.


How to add a query data source component to a report design

In this procedure, you add query data source and data row components from the data palette in the Design Editor. You can also use a prebuilt query data source or data row from a library or from another report design. For more information about the different ways to add components to a report, see Sources from which you can drag components.

1	Make sure the report design contains a database connection if one is required. For more information about connections, see  Defining database connections.

2	Drag-and-drop a query data source component from the component palette to the report section's DataSource slot. If you are working with stored procedures, drag-and-drop a stored procedures component from the data palette instead. For more information, see  How to design a report with stored procedures.

3	Drag-and-drop a data row component from the component palette to the query data source component's DataRow slot.


About data rows

In Actuate, a data row is a component that stores the output of a data source component or filter. The data row is a set of data values stored in variables. The list of variables defines the data that you can include in the report.

When you run the report, the data source component instantiates a set of data row objects that contain the data retrieved from the database. For more information about objects and instantiation, see About Actuate's object-oriented design.

When you write a query using the Query Editor, Actuate adds variables to the data row, depending on which database columns you select. When you write a custom data stream, you must write your own data row. With stored procedures, the query is already written. With stored procedures, select the procedure and then add parameters as the stored procedure allows.

As you read Actuate documentation and work with the Actuate reporting system, keep in mind the difference between the data row component and the data row objects. A data row component is a class you work with when you are designing a report. A data row object is an instance of that class that is instantiated to hold the data coming from the data source when you run the report.

In sum, each report has one data row component, but as you run the report, it can process thousands of data row objects--or none, if no rows match the query.


About data filters

A data filter is a component that can compute new values, perform custom lookups, select rows, and sort and join data. After the data source component has returned a data row, the data may pass through a series of filters before being delivered to the report. You create filters to perform additional steps that could not be accomplished by the query data source component alone. For more information about filters, see Programming with Actuate.


About stored procedures

A stored procedure is a set of prepackaged SQL statements, each of which performs a specific task. A stored procedure is stored in the database and it can be selected by name using the Stored Procedure Data Source Builder in the Design Editor.

In Building Reports, the automated features are the focus when discussing stored procedures. Actuate's stored procedure features enable you to log in to the database and bring up a list of names of stored procedures in a browser dialog box for Sybase and ODBC databases. PeopleSoft databases are supported through the ODBC drivers. For more information on stored procedures, see Using stored procedures.

The Actuate Developer Workbench can call stored procedures from Oracle as well as Sybase, ODBC and PeopleSoft. You may work with stored procedures from Oracle by overriding methods to modify the SQL statement and work directly with Actuate Basic code. For information on overriding methods to work with stored procedures, see Using stored procedures in SQL databases in Programming with Actuate.


About sorting data

In reports, the rows of data can be organized in a particular order. For example, in a sales report, you might sort orders alphabetically by customer name. The customers, in turn, might be sorted by city. The set of column or field names that determines sort order is called the sort key.

There are several ways to sort data, depending on the type of data stream your report uses.

See also

Sorting data with a query data stream
Sorting data with a custom data stream


Sorting data with a query data stream

If your report uses a query data stream, use one of the following techniques to sort data.

•	In a grouped report or crosstab, use group sections to specify the sort key. For more information about group sections, see  About group sections.

•	In any other type of report, use the Query Editor, accessible from the Data Source Editor on the toolbar, to specify the sort key. For more information about using the Query Editor to sort data, see  Sorting data with the Query Editor.


Sorting data with a custom data stream

If your report does not use a query data stream, it must use a custom data stream. When you write the custom data stream, include code to sort the data if necessary. For example, you might use a sort filter. For more information about writing a custom data stream, see Programming with Actuate.


About queries

A query is a SQL SELECT statement that specifies which data to retrieve from the database. When you use the Developer Workbench, you don't need a detailed understanding of the SQL language, because you can use the Query Editor to graphically select tables, columns, and other query options. Actuate writes the SQL SELECT statements automatically as you make selections in the Query Editor. However, a familiarity with SQL will help you write better queries. If you have never written a SQL query or used a query building tool, refer to your SQL or DBMS documentation.

See also

About SQL SELECT statements
Comparison of Where and Having conditions


About SQL SELECT statements

SELECT is a statement in SQL, a language commonly used for database applications. The SELECT statement specifies which data you want to retrieve from the database. The SQL SELECT statement is divided into parts called clauses. The following diagram shows how you create each clause graphically in the Query Editor.

Your action in Query Editor	Text Actuate writes in SELECT
Specify tables	From clause
Create joins	Part of the Where clause
Select columns	Select clause
Put conditions on row retrieval	Where clause
Sort data	Order By clause
Summarize data	Group By clause
Put conditions on aggregate rows	Having clause

For more information about how to perform these actions in the Query Editor, see Writing queries.


Comparison of Where and Having conditions

You can impose two kinds of conditions as part of a query:

•	Conditions on row retrieval. Specify these conditions in the Where clause. In the Query Editor, use the Conditions page to specify these conditions.

•	Conditions on aggregate rows. Specify these conditions in the Having clause. In the Query Editor, use the Having page to specify these conditions.

When a query runs, it follows these steps to apply conditions:

1	The query first retrieves all rows that meet the row retrieval conditions. For example, the query could select salary numbers for all departments in a specific company.

2	The query then groups those rows, as specified in the Group By clause, and creates aggregate rows that summarize the groups. For example, the query could combine the salary numbers by department and create rows containing the average salary for each department.

3	Finally, the query applies the second set of conditions to the aggregate rows it created. For example, the query could select those departments with an average salary greater than the company average.

When you want to select data based on values in individual rows in the database, use row retrieval (Where) conditions. When you want to select data based on values, such as total order amounts, that are not known until after the query creates aggregate rows, use aggregate row (Having) conditions.


Writing queries

The Developer Workbench provides a graphical tool called the Query Editor, which you can use to write queries using a simple point-and-click interface. To write a query using the Query Editor, perform the following procedures in order. For each procedure in this list, there is a corresponding section with detailed, step-by-step instructions.

Required procedures

1	Opening the Query Editor.

2	Selecting tables.

3	Selecting columns.

4	Specifying computed columns.

Optional procedures

1	Creating joins.

2	Putting conditions on row retrieval (Where).

3	Sorting data with the Query Editor (Order By, Group By).

4	Summarizing data.

5	Putting conditions on aggregate rows (Having).

6	Viewing the SELECT statement.

See also

Opening the Query Editor
Selecting tables
Working with table and view synonyms
Selecting columns
Specifying computed columns
Creating joins
Putting conditions on row retrieval (Where)
Sorting data with the Query Editor
Summarizing data
Putting conditions on aggregate rows (Having)
Viewing the SELECT statement


Opening the Query Editor

For the Query Editor to work, Actuate must be able to establish a database connection. If you do not already have an open database connection when you start the Query Editor, Actuate attempts to connect to a database using the connection properties defined in the connection component.

If the connection component does not contain the necessary information, Actuate will not be able to connect. The Database Login dialog box appears so that you can supply the necessary information.

For more information about defining a connection, see  Defining database connections.

See also

How to open the Query Editor
Customizing the Query Editor display


How to open the Query Editor

1	Choose View→Data Source.

If the Query menu item is unavailable, click in the structure pane and try again.

If Actuate is able to connect to the database, the Query Editor and Database Browser appear. If Actuate is unable to connect to the database, the Database Login dialog box appears.

2	In the Database Login dialog box, type the required information and choose OK.

Some of the fields in the dialog box might already be filled in, depending on whether these values were set in the connection component. For more information about defining connection properties, see  Defining database connections.


Customizing the Query Editor display

To lengthen or shorten the column names displayed in the Query Editor pages, choose View→Column Qualifiers, and then choose one of the following:

•	Full Name--displays the database, schema, table, and column name. For example, sales.dbo.customers.phone.

•	Table and Column--Displays the table and column name. For example, customers.phone.

•	Column Only--displays the column name only. For example, phone. This choice helps fit the display on smaller or lower-resolution screens, but some of the column names from different tables might be duplicates.


Selecting tables

Begin writing the query by selecting which database tables contain the information you want in your report. The Database Browser shows a graphical representation of all the tables to which you have access.

The Database Browser can display views, system tables and table and view synonyms, as well, depending on which DBMS you are using.

As you select tables, Actuate automatically writes the From clause of the SQL SELECT statement.

For more information on working with a database that includes table and view synonyms, see Working with table and view synonyms.

See also

Using the same table multiple times
How to select tables
Modifying table properties in a query
How to modify a table in a query


Using the same table multiple times

You can add the same table to the query more than once. For example, you might want to use a table of address data to obtain both a Ship To address and a Bill To address in the same data row, or use a table of physician data to obtain both the referring physician and treating physician for a health care claim form.

When you add a table that already exists in the query, a dialog box appears in which you can specify an alias, or additional name, for the table. If you do not specify an alias, Actuate uses a default alias.


How to select tables

1	Select the Tables and Joins tab.

2	Click the plus icons in the Database Browser until the tables you want appear.

3	Drag-and-drop one or more tables from the Database Browser to the Tables and Joins page.

In the following illustration, the Tables and Joins page is in the lower pane of the Query Editor.

4	If you drop a table more than once, the Alias Name dialog box appears. If you wish to change the default alias provided by Actuate, type a new name in the Alias field.

5	To delete a table from the Tables and Joins page, select the table and press the Delete key.


Modifying table properties in a query

After you add a table to a query, you might want to change some of its properties. For example, you can change the database name, owner name, and table name. This is useful if you have several databases with different names, different data, but the same table structure, and you want to be able to easily move the query from one database to another.

You can also indicate how specific you want table and column references to be in the SQL code that Actuate writes. For example, if you have several schemas with identical structures, as described earlier, you might not want to use fully qualified references.


How to modify a table in a query

1	In the Tables and Joins page of the Query Editor, double-click the table.

The Table Properties dialog box appears.

2	To change the table name, select or type new names in DB, Owner, and Table.

3	To specify the format you want Actuate to use when referring to tables in the SQL SELECT statement, select one of the options under Generate.

For information about the Alias field, see  Using the same table multiple times.


Working with table and view synonyms

Actuate supports Oracle synonyms for tables and views.

Table and view synonyms in databases are usually created for the following two purposes:

•	To provide a more meaningful name for a table or view than that already given as the base name. If a database was developed in a foreign country, for example, you may wish to rename the tables and views in your native language.

•	Table and view synonyms shield applications from any changes in the base table name that might occur over the life of a database.

Table and view synonyms give you the option of viewing and working with the base names of a table or view and its dependencies or the table or view synonym and its dependencies. Because synonyms act as aliases, synonyms enable you to work with tables and views without knowing the specific location of those tables and views.

When a synonym for a table or view is developed, the synonym remains connected to the original associated files.

See also

How to view table synonyms


How to view table synonyms

1	In View→Options, go to the Query Editor tab.

2	Under the Tables and Views column, choose one of the following by clicking on the button associated with the choice.

•	Show Tables and Views

•	Show Tables only

•	Show Views Only

The default is Show Tables and Views.

3	Under the Names column, choose one of the following by clicking on the button associated with the choice.

•	Base name

•	Synonyms

•	Base names and synonyms

The default is Show Base names.

4	If you select Show System Objects, the database objects that were not built by the user appear.

The base name is the name of a database object, which could be a table or a view. Its original base name was created when the table or view was first created inside the database.

Views and tables may have multiple synonyms that were created in the database. Because Actuate is a read-only application when it works with databases, you cannot create new synonyms with Actuate.

When Actuate accesses a database, all objects available to the user are accessed. The DB Browser and the Options-Query Editor page then determine what is displayed, based on your choices.

Once you make choices in the dialog box, it is useful to view the DB Browser with the Query Editor, to see how different choices affect the displayed lists. The Query Editor works with a table or view synonym in the same way that it works with a table or view base name. The only difference is the name of the table and view.

In the DB Browser, the text at the right of the synonym explains on which object the synonym was defined.


Selecting columns

You can write a query to retrieve all columns or only some of the columns from each table. You can also make the order of the columns in the data row different from their order in the database. As you select columns, Actuate automatically writes the Select clause of the SQL SELECT statement and declares variables in the data row.

See also

How to select columns


How to select columns

1	Select the Tables and Joins tab.

2	Choose the Move page up button.

The Tables and Joins page appears in the upper pane of the Query Editor.

3	In the lower pane, select the Columns tab.

4	Select columns using one of the following methods.

•	In Column Name, use the drop-down list to select the column you want.

•	Drag-and-drop the columns from the Tables and Joins page to Column Name.

You can select multiple columns and drag them all at the same time. To select all columns, drag the asterisk (*). This will select all the columns in the table at the time you run the report, which may not be the same as the columns listed now in the Query Editor.

5	To change the order of the columns:

•	In the Columns page, select the column name.

•	Choose the up arrow or down arrow.

6	To change the Actuate Basic data type of the column in the report's data row:

•	Double-click the column name.

The Column Properties dialog box appears. The DB Type field displays the data type of the column in the database.

•	In Basic Type, select the Actuate Basic data type you want.

7	To delete a column from the Columns page, select the column name and press Shift + Delete.


Specifying computed columns

Instead of using a single column from the database, you can specify a computation. This computation can involve one or more columns. For example, to make the query return the extended price for an item in a sales order, you might use the computation [items.price] * [items.quantity].

See also

How to specify a computed column


How to specify a computed column

1	Select the Columns tab.

2	In Column Name, type a name for the computed column.

3	In Formula, type the expression that computes the value of the column.

To get help writing this expression, choose the Builder button to open the Expression Builder.

If you are planning to use aggregate rows in the query, use one of the aggregate functions Sum( ), Min( ), Max( ), Ave( ), First( ), Last( ), or Count( ). For more information about aggregate functions, see Computing aggregates in a value expression.


Creating joins

When you select more than one table, Actuate automatically creates joins to link related tables if it can determine the columns on which the tables are joined. A join is a SQL query operation that combines records from two tables and returns them in a result set based on the values in the join fields. For example, customer and order tables could be joined on a common field such as customer ID. The result set would contain combined customer and order records where the customer IDs are equal.

Without a join operation, you would have to assume that the data in the tables is in the correct order. If the data were not in order, the result set might contain a customer from one table and an order from another. This would give an inaccurate picture of what one customer is ordering.

To decide where joins should occur, Actuate applies these criteria in order:

1	The relationship information, if available, in the data dictionary of a database

2	Primary and foreign keys

3	Matching column names and types

For more information about joins, primary keys, and foreign keys, refer to your DBMS documentation.

The joins Actuate creates automatically may not match the actual structure of your database schema. If you need to find out about the joins in your database, ask your database administrator for a schema diagram.

You can also establish joins using the Query Editor. The types of join you can create depend on your DBMS. The Actuate Query Editor supports the following types of joins.

Type of join	Description
Inner join	Returns records from two tables where the values of the joined fields have a specified relationship, such as equal to or greater than.
Left outer join	Returns records from the leftmost table even if there are no matching values in the other table.
Right outer join	Returns records from the rightmost table even if there are no matching values in the other table.

As you create joins, Actuate automatically begins writing the Where clause of the SQL SELECT statement.

Note

You may create a SQL statement and work with a database without using any joins. A report that simply reports a straight stream of data, with no complications, may not require a join.

See also

How to create a join
How to delete a join


How to create a join

1	Select the Tables and Joins tab.

2	Drag the primary key column name from a table and drop it on the foreign key column name in another table.

3	If your primary key requires more than one column to establish a unique value, repeat step 2 to drop additional column names on the same foreign key.

For example, in a database of parts from several manufacturers, the part ID alone might not be unique. Several manufacturers might use the same number. You would need to use both the part ID and manufacturer name to establish a unique key.

4	To change the type of join, double-click the join operator icon.

The Join Properties dialog box appears.

5	To change the join operator, select an operator in the drop-down list box.

6	To specify a left or right outer join instead of an equi-join, select one of the options in Type of Join.


How to delete a join

1	Select the Tables and Joins tab.

2	Select the join line or join operator.

3	Press Delete.


Putting conditions on row retrieval (Where)

You can specify conditions that must be met by the rows in the database. For example, rather than retrieving information about all customers, you can retrieve information about customers in a certain state. As you put conditions on row retrieval, Actuate automatically adds them to the Where clause of the SQL SELECT statement.

For more information about conditions, see Comparison of Where and Having conditions.

There are two methods for putting conditions on row retrieval. You can use either or both of the following methods in a single query.

•	Using a simple QBE (Query by Example) expression syntax. When you specify more than one condition using the QBE syntax, all must be True for a particular row to be returned. That is, you can specify only AND conditions. You use QBE to place conditions on one column at a time.

•	Using SQL syntax. Use this syntax to specify an OR condition or to specify a condition that involves more than one column.

See also

How to put conditions on row retrieval


How to put conditions on row retrieval

1	Select the Tables and Joins tab.

2	Choose the Move page up button.

The Tables and Joins page appears in the upper pane of the Query Editor.

3	In the lower pane, select the Conditions tab.

4	Specify a column in one of the following ways.

•	Drag-and-drop any column from the Tables and Joins page to the Conditions page.

•	In the Conditions page, click under Column Name and select a column name from the drop-down list box.

5	Specify a condition in one of the following ways.

•	In Query Expression, type the conditions you want to apply, using the QBE expression syntax. For more information about this syntax, see  Query by Example (QBE) syntax.

To get help, choose the Expression Builder button to open the Expression Builder.

•	Type a SQL expression in the lower part of the page. This expression can include any valid SQL syntax, including nested SELECT statements.

•	To allow the user to enter a condition when they run the report, select Ad Hoc. For more information about ad hoc parameters, see Designing report parameters.

6	To add more conditions, repeat steps 4 and 5.

7	To delete a column from the Conditions page, select the column name and press Shift + Delete.


Sorting data with the Query Editor

You can change the order of the retrieved rows by specifying one or more columns to define a sort key.

If your report includes group sections, they determine the sort order. The sort keys in group sections take precedence over those specified using the Query Editor. Use the Query Editor to specify sorting in the following circumstances.

•	You are not using group sections.

•	You want to perform more sorting in addition to that which is performed by the group sections.

For an overview of sorting, see  About sorting data. For more information about group sections, see  Sorting data with group sections.

As you use the Query Editor to select columns for sorting, Actuate automatically adds them to the Order By clause of the SQL SELECT statement.

See also

How to sort data using the Query Editor


How to sort data using the Query Editor

1	Select the Order By tab.

2	From Available Columns, select one or more columns to be your sort key.

3	Choose the left arrow.

The column names appear in Order By.

4	To change the order of the columns in the sort key:

1	In Order By, select the column name.

2	Choose the up arrow or down arrow.

5	To sort a particular column in descending order, deselect Asc.

6	To delete a column from the Order By page, select the column name and press Shift + Delete.


Summarizing data

To summarize a group of retrieved data, you create an aggregate row. An aggregate row is a single row that combines the data from a group of rows that have one or more column values in common. For example, you can group all the rows for a particular customer and create one aggregate row that contains the total number and average dollar amount of all that customer's orders.

To create an aggregate row, you first specify aggregate expressions in the Columns page of the Query Editor, then specify column names in the Group By page.

As you write aggregate expressions, Actuate automatically adds them to the Select clause of the SQL SELECT statement. As you select columns for aggregate rows, Actuate automatically writes the Group By clause of the SQL SELECT statement.

A detailed discussion of aggregate rows is beyond the scope of this document. Refer to your SQL documentation for details about the Group By clause.

See also

How to summarize data


How to summarize data

1	Create columns that compute aggregate values by following the steps in  Specifying computed columns.

2	Select the Group By tab.

3	From Available Columns, select one or more columns to be the basis of your aggregate rows.

You must select all of the columns that appear in the Select clause of the query. That is, all the columns you dragged into the Columns page.

4	Choose the left arrow.

The column names appear in Group By.

5	To delete a column from the Group By page, select the column name and press Shift + Delete.


Putting conditions on aggregate rows (Having)

You can specify conditions that must be met by the aggregate rows. For example, rather than including aggregate rows for all customers, you can include only customers with total orders above $10,000. As you put conditions on aggregate rows, Actuate automatically writes the Having clause of the SQL SELECT statement.

For more information about how to specify aggregate rows, see  Summarizing data. For more information about conditions, see Comparison of Where and Having conditions.

There are two methods for putting conditions on aggregate rows. You can use either or both of the following methods in a single query.

•	Using a simple QBE (Query by Example) expression syntax

•	Using SQL syntax

When you specify more than one condition using the QBE syntax, all must be True for a particular row to be returned. That is, you can specify only AND conditions. To specify an OR condition, use the SQL syntax. To specify a condition that involves more than one aggregate row, use the SQL syntax.

See also

How to put conditions on aggregate rows


How to put conditions on aggregate rows

1	Select the Having tab.

2	Click under Column Name and select an aggregate name from the drop-down list box.

3	Specify a condition in one of the following ways.

•	In Query Expression, type the conditions you want to apply, using the QBE expression syntax. For more information about this syntax, see  Query by Example (QBE) syntax.

To get help, choose the Expressions Builder button to open the Expression Builder.

•	Type an SQL expression in the lower part of the page. This expression can include any valid SQL syntax, including nested SELECT statements.

4	To add more conditions, repeat steps 2 and 3.

5	To delete a column from the Having page, select the column name and press Shift + Delete.


Viewing the SELECT statement

Use the SQL page to look at the SQL SELECT statement. Actuate writes this statement automatically while you make choices in the other pages of the Query Editor. You can copy from the SQL page to the Clipboard.

See also

How to view the SELECT statement


How to view the SELECT statement

1	Select the SQL tab.

2	You can see the SQL SELECT that Actuate writes as you work with the Query Editor. You can select this text and copy it to the Clipboard.


Query by Example (QBE) syntax

Actuate provides a simple Query by Example (QBE) syntax that you use to write expressions that Actuate translates into SQL. The QBE syntax is useful only in reports that use a query data stream. Use the QBE syntax in the following situations:

•	To specify conditions on row retrieval in the Conditions page of the Query Editor

•	To specify conditions on aggregate rows in the Having page of the Query Editor

•	To specify values for ad hoc parameters in the Requester

In all three cases, Actuate reads the QBE expression and adds the corresponding SQL code to the query.

The QBE syntax is different from the syntax you use to specify search criteria in the Search dialog box when you are viewing a report. For information about that syntax, see the term search expression in the Glossary.

See also

Types of QBE expressions
Wildcard and literal characters in QBE strings
Handling blanks at the end of a string in QBE
Specifying null values in QBE


Types of QBE expressions

You can use QBE syntax to build four types of expressions.

•	A single value, such as 10.

•	A relational expression, such as  >50.

•	A range of values, such as 20-25.

•	A list of the above separated by commas, such as 10, >50, 20-25.

The following table gives examples for each type of QBE expression. The second column in the table shows which database column the expression applies to. For example, when you type a QBE expression in the Conditions page of the Query Editor, you first select a column name. The last column in the table shows the SQL syntax that Actuate adds to the Where clause of the query.

Type of expression	Database column	QBE expression	SQL
Single value	quantity	0	quantity = 0
Relational	quantity	>50	quantity > 50
	custState	!CA	custState <> 'CA%'
	custName	>P	custName > 'P%'
Range	price	10-20	price IS BETWEEN $10.00 AND $20.00
	orderDate	1/1/94 - 5/31/94	orderDate IS BETWEEN  1/1/94 AND 5/31/94
	custName	Ed - Kl	custName IS BETWEEN 'Ed%' AND 'Kl%'
List	custState	CA,OR,NV	custState LIKE 'CA%' OR custState LIKE 'OR%' OR custState LIKE 'NV%'
	empCode	1, 6-8	empCode = 1 OR empCode IS BETWEEN 6 AND 8

Actuate adds a percent character (%) to strings in QBE expressions, with the exception of ad hoc parameters. For a parameter defined in the Condition tab of the Query Editor, which is the case for an ad hoc parameter, the % character is not added to the end of the user input value. To create a wildcard search, include a % in the parameter's input value.

For more information about the percent character, see  Handling blanks at the end of a string in QBE.

The values in all types of QBE expressions must be of the correct data type. For example, you cannot use a string value for a numeric column. If Actuate cannot convert a value in a QBE expression to the data type required by the database column, the word <ERROR> appears in the SQL code.


Wildcard and literal characters in QBE strings

The following characters have special meanings in a string in a QBE expression.

Character	Meaning in QBE
_	Match any single character
%	Match any character or group of characters
[ ]	Match any one of the characters within brackets
\	Treat the next character literally, rather than treating it as a special character

The following table shows examples of how to use the wildcard and literal characters.

Example QBE syntax	Matches	Doesn't match
Sm_th	'Smith' 'Smoth'	'Smooth' 'Smth'
Smith%	'Smith' 'Smithsonian' 'Smith                '	'Smit'
Sm[aeiou]th	'Smith' 'Smath'	'Smooth' 'Smth'
Sm\[aeiou\]th	'Sm[aeiou]th'	'Smith'


Handling blanks at the end of a string in QBE

Actuate automatically adds a percent character (%) to the end of every string when it writes the SQL code. It does this to make sure blank characters at the end of strings in the database do not interfere with the matching process. The following table illustrates why this is necessary.

SQL syntax	Matches	Doesn't match
custName LIKE 'Smith'	'Smith'	'Smith                '
custName LIKE 'Smith%'	'Smith' 'Smith                '

If you do not want Actuate to add the percent character to the end of a string, enclose the string in single quotes in the QBE expression.


Specifying null values in QBE

You can use the keyword Null to specify an empty field in the database. The keyword is not case sensitive. The following table shows examples of using Null in a QBE expression.

Database column	QBE syntax	SQL
orderDate	Null	orderDate IS NULL
custID	!null	custID IS NOT NULL
For more information on how QBE syntax is used with different types of parameters, see Designing report parameters.


Using stored procedures

The Developer Workbench provides a specialized set of components and tools to work with stored procedures supplied by a database.

Actuate supports the automated stored procedure features for the following databases.

•	ODBC databases, including PeopleSoft

•	Sybase databases connected by Sybase ctlib drivers

The components and tools provided in the Developer Workbench are

•	Stored procedure component, located on the data toolbar

•	Stored Procedure Data Source Builder, which is a tool accessed after the stored procedure component has been placed in the data stream of a report. To access it, select the DataStream component. Then click the SQL button.

•	Stored Procedure Browser, accessed from the Stored Procedure Data Source Builder, context menu or from the stored procedure toolbar. You may choose a stored procedure from the list inside the Stored Procedure Browser.

•	Stored Procedure Name Editor, which lets you modify the name of the stored procedure, accessed from the stored procedure toolbar or the context menu. If the name is edited, be sure the stored procedure's parameter and result columns are consistent with the new name.

•	Stored procedure synchronization,which lets you know if the contents of a named stored procedure in your design is consistent with its definition in the database. This is accessed from the stored procedure toolbar or the context menu.

•	Sample Parameter Values dialog box, which lets you specify a sample input value for parameters, when allowed with a stored procedure, to help you define the boundaries of your report.

See also

About the components used in stored procedures
How to design a report with stored procedures
Working with the stored procedures dialog boxes
Working with data from stored procedures
Working with sample values for input parameters
About input and output parameters
About result sets
Accessing data from a flat file


About the components used in stored procedures

A report using stored procedures requires the set of components in a report that are common to every report design. For a description of the components required and the data stream involved in a report design, see Building your first report and How reports get data.

For information on how to build a report using stored procedures, see How to design a report with stored procedures.


How to design a report with stored procedures

To build a report that accesses and works with stored procedures from a database, do the following.

1	To set up the required stored procedures and other components, choose File→New.

2	In the New File dialog box, check New Stored Procedures Report. Press OK.

A report design appears, with basic stored procedure components inserted in the slots. Note that this design starts with an ODBC connection. To use a Sybase connection, you need to change the Connection class to AcSybaseConnection.

To change the default ODBC connection class to AcSybaseConnection, do the following:

1	Go to the Component Editor Class tab for the Connection component.

2	Type AcSybaseConnection in the place of AcODBCConnection.

3	Press Close.

3	Examine your new .ROD file in the Design Editor. You have the following components in place for a simple report. This list is ordered from the top of a report design in the structure (left-hand) pane.

•	NewReportApp component. AcReport is the superclass of this component.

•	Report component in the Content slot. AcReportSection is the superclass of this component.

•	Connection component in the connection slot. This component has the default superclass of AcODBCConnection.

•	The Stored Procedure Source component in the data stream slot. AcStoredProcedureSource is the superclass of this component.

•	The Data Row component in the data row slot. This component's superclass is AcDataRow.

•	Frames in the Before, After and Content slots.

•	A simple PageList component in the PageList slot. This component's superclass is AcSimplePageList.

4	In the DBConnection component Properties page, enter the DataSource, Password and UserName.

In the example, the DataSource is PeopleSoftHr700; the UserName is USHR, and the Password is ****.

5	Make the structure pane active. Select the SQL button on the toolbar.

6	Depending on your database connection, the Login dialog box may appear. If it appears, log in to the database that contains the stored procedures with which you want to work.

You are now ready to work with your report. For more information, see .Working with the stored procedures dialog boxes.


Working with the stored procedures dialog boxes

After your report design is set up in the Design Editor and you are logged in to your database, you may begin working with the stored procedures dialog boxes.

1	Make the structure pane active in the Design Editor.

To make the structure pane active, click the DataStream component in the structure pane.

2	Press the Stored Procedure Data Source Builder button. It is labeled SQL. This button is operative when the stored procedure component is already in the data stream slot.

3	Log in to the database, if requested. Type your user name and password.

The Stored Procedure Data Source Builder opens.

When the Stored Procedure Data Source Builder appears, with the Result Columns visible, so does the stored procedure toolbar.

4	In the Stored Procedure Data Source Builder dialog box, click the Procedures... button.

The Stored Procedure Browser appears with a list of available stored procedures.

5	In the Stored Procedure Browser, double-click the name of the stored procedure you wish to use.

The name of the stored procedure appears in the Name field of the Stored Procedure Data Source Builder dialog box.

The stored procedure you choose may or may not produce data in the Result Columns of the Stored Procedure Browser. In the example, the stored procedure produces results under Column Name in the Result Columns page. Some stored procedures are internal functions and may not return data to users.

The Description page lies behind the Parameters page in this dialog box. The Description page will be empty if description information or source text from the database is not available.

You are ready to work with the data in the stored procedures. For information on working with the data you have now placed in your report design, see Working with data from stored procedures.


Working with data from stored procedures

If you have built your report, accessed the stored procedures and selected a stored procedure, you can proceed with your report design. For information on setting up your Actuate report for stored procedures, see How to design a report with stored procedures.

1	Select the frame in the Content slot of your report design to make it active.

2	Click the Field List button.

Note that the Field List is only available if a frame is selected.

The list of controls available to you from the stored procedure are now available to drag-and-drop into the frame of your report design. You may click on a control in the Field List and drag it into a frame.

The list of controls available 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 the fields in the order defined in the stored procedure.

3	From the Field List, select and drag-and-drop each item you would like to appear into the Content frame.

Consult the designer of the stored procedure to find out the definition of the result column fields.

4	Arrange controls in the frames. In Before and After frames, place the column headers and controls for totals, as you wish.

5	Select Report→Build/Run/View.

Depending on the stored procedure, you may be asked to enter an input parameter as the Factory processes begin. In this example, 3 is the value of the input parameter.

6	View your report.

You may wish to check to see if the stored procedure you are using has changed since you first worked with it. For more information, see Synchronizing the stored procedure design.

See also

Working with different data types in stored procedures
Synchronizing the stored procedure design
Narrowing a search and matching patterns in stored procedures


Working with different data types in stored procedures

You can, by the way, use several different data types in your report that uses stored procedures. A report design can contain integers, real numbers, currency, text, and all other Actuate data types.


Synchronizing the stored procedure design

Stored procedures defined in your database may change between the time of the original report design and when you run them in a report.

You may check to see that the stored procedure design has remained constant by using the Synchronize procedure tool. To access the tool, do the following:

1	Open the context menu for the Stored Procedure Data Source Builder.

To open the context menu, place your cursor over the Stored Procedure Data Source Builder dialog box and right-click.

2	From the context menu, choose Synchronize Procedure With Schema. If the stored procedure definition is consistent, a message verifies the consistency.

If the design of the named stored procedure has become corrupt or has changed since you originally used it, a message appears. The information in the message enables accurate changes to a report design.

A list of procedures in a group may be too long. Shorten the list by narrowing your selection. Or, shorten the list by choosing a pattern. For more information, see Narrowing a search and matching patterns in stored procedures.


Narrowing a search and matching patterns in stored procedures

Subgroups of the stored procedures are available, as well as the full list of stored procedures. A feature in the Options dialog box, Stored Procedure Data Source Builder page lets you narrow the list of stored procedures. To work with this feature, do the following.

1	In the Stored Procedure Data Source Builder, select the Browse button to open the Stored Procedure Browser.

2	From the Browser, right-click to open the Stored Procedure Data Source Builder page of the Options dialog box.

The Stored Procedures Data Source Builder page of the Options dialog box is also visible if you choose View→Options→Stored Procedure Data Source Builder page.

In the Stored Procedure Data Source Builder page, specify if you wish to view and work with user procedures, system procedures, or both. If your database cannot distinguish between user procedures and system procedures, this feature may not appear to operate.

To view user procedures and system procedures, choose in the dialog box:

•	Show User Procedures

•	Show System Procedures

You may narrow your list of stored procedures. Lower on the dialog box, enter a search expression under Stored procedure pattern match.

The list of stored procedures showing in the Stored Procedure Browser is now limited to those with Salary somewhere in the name. To view the list of stored procedures, click the Procedures... button in the Stored Procedure Data Source Builder.

For information on search syntax, see the term search expression in the Glossary.


Working with sample values for input parameters

The Data Source Builder prompts users for parameter values if input parameters are required by the stored procedure.

To determine if parameters are used by the stored procedure, choose the Parameters tab in the Stored Procedure Data Source Builder dialog box.

If parameters are used or required, the following information is available in the Parameters tab of the Stored Procedure Data Source Builder dialog box:

•	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

•	Integer

•	Double

•	Date/Time

•	Currency

•	Text, which sometimes appears as String

If an input value for a stored procedure is needed to determine the result column, the Sample Parameter Values dialog appears.

1	In the Sample Parameter Values dialog box, enter a parameter, such as 3, in the Value column.

To later change the sample parameter values, you can manually bring up the Sample Parameter Value dialog.

From the Context menu of the Stored Procedure Data Source Builder dialog box, choose Parameter Sample Values.

Note

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 may determine the type of result set returned, based on the sample parameter value(s). Therefore, the type of input value used in the Actuate report design needs to be used when running the Actuate report, in order to return the same type of result set.

For information about result sets, see About result sets.


About input and output parameters

Some vendors' database systems, such as those from Sybase, do not provide information on whether a stored procedure parameter is an input or output type.

If this is the case, UNKNOWN may appear next to the parameter name in the Stored Procedure Data Source Builder's Parameter page, under Input/Output.

If UNKNOWN appears, the developer needs to designate input or output parameters in the Stored Procedure Data Source Builder.

In the Parameters page, the name of the field item from the stored procedure as well as its Actuate Type are listed.

To designate input or output parameter types for a stored procedure, do the following.

1	In the Stored Procedure Data Source Builder, choose a stored procedure.

2	Select the Parameters tab and view the data there.

3	In the Input/Output column, specify if a parameter is an input parameter, an output parameter or both.

The named field items you specify as input parameters appear in the Requester dialog box at run time.


About result sets

In each case, Actuate's automated features for stored procedures deliver a single result set. If the stored procedure returns multiple result sets, only the first result set is processed by the automated stored procedure features of Actuate. A stored procedure that delivers no result set, such as an Oracle stored procedure, is not supported by Actuate's automated stored procedure feature.

For information on deriving more complex result sets, see Using stored procedures in SQL databases in Programming with Actuate.


Accessing data from a flat file

Placing data from a flat file into an Actuate report is different than working with data from a database with which you connect using a Connection component, Data Source component and Data Row component.

There are several ways to place data from a flat file into your report. One method is to bypass the Connection component and tell the data stream to connect with the flat file.

To place data from a flat file into an Actuate report design, perform five major steps:

1	Set two variables in the DataStream component.

2	Within the DataInput variable of the DataStream component, set a parameter to contain the name of the flat file.

3	In the DataSource method editor, override three components.

4	In the Data Row's Variable's tab define the variables to pull in from the flat file.

5	Set up the report design to accommodate the frames and controls you wish to use.

See also

How to attach a flat file as the data source


How to attach a flat file as the data source

The steps that follow illustrate this method with an example report, the Penguin Ice Cream report.

The data in the flat file was created with a simple text editor. The data file details information on ice cream flavors, number of scoops sold in 1999, the color of the ice cream and the major ingredients.

Below you see the AcReport, or top-level, component and AcReport Section, which is the first Content component. You leave the Connection slot blank and you'll work with the Data Stream component.

1	In the Data Stream component, set two variables in the Variables tab, Channel and DataInputFile. These two variables specify the data stream.

2	In the DataInput File, which is set to String, set a parameter that contains the flat file name. To specify the parameter, select the DataInputFile line.

3	Click the Builder (3-dot) button that appears.

4	In Parameter Attributes specify the data input file. In this example, the flat file name is PenguinFlatFile.txt.  This is the flat file text containing your data.

In the previous steps you have specified the data input file to be used as data. Next, you will override three methods and specify the rows from the flat file you are fetching.

In the DataStream Method Editor, override three methods:

•	Start

•	Fetch

•	Finish

Note that in Fetch, you specify you are fetching flavor, quantity, color and ingreds.  These are items you define in the Variables tab.

1	First, override the Start method.

2	Then, override the Fetch method.

3	Last, override the Finish method.

4	In the Datarow component's Variable tab, define the four variables you wish to pull in from the flat file.  Your data rows should match the items you specified in the Fetch overridden method: color, flavor, ingredients and quantity.

5	The file PenguinFlatFile.txt, which resides in the directory with this .ROD, is set up to contain 4 fields of data.  Each is separated by commas, as shown in the illustration preceding the steps of this example.

When you run the report, the flat text file is called, the data is retrieved, and the report is created.


The Developer Workbench environment

The following topics are available. To view the topics in order, use the Browse button (>>) in the Help window's toolbar.

•	About the application window

•	About the tools

•	About the Design Editor

•	About the Query Editor and stored procedures

•	About the Method Editor

•	About the Expression Builder

•	About the Viewer

•	About the toolbars and palettes

•	About context menus

These topics provide a high-level overview of the Developer Workbench. The rest of the online help provides more details about how to use the Developer Workbench.


About the application window

When you start the Developer Workbench, the application window opens. This window contains the menu bar, toolbars, and palettes. The following illustration shows the application window as it appears when you start the Developer Workbench for the first time. If your application window has been customized, it might not look exactly like this illustration.


About the tools

In the Developer Workbench, you work with tools. Each tool is a window that you use to build a particular part of the report design. The main tools are described in the following table.

Tool	Task
Design Editor	Specify the overall structure, location and appearance of a report and its components.
Query Editor	Write or modify a query to provide data for the report. For stored procedures, the Stored Procedure Data Source Builder, rather than the Query Editor, lets you access a set of stored procedures in the database.
Method Editor	Write Actuate Basic code by overriding methods.
Expression Builder	Point and click to construct mathematical and conditional expressions
Viewer	View the finished report after you run it to see the results of your report design
Navigator	If you are running in a client/server environment, you can place the report design (.ROD) or report executable (.ROX) in the Report Encyclopedia so that other users can access your report.

See also

About the Design Editor
About the Design Editor's helper tools
About the Query Editor and stored procedures
About the Method Editor
About the Expression Builder
About the Viewer
About the Navigator


About the Design Editor

The following illustration shows the Design Editor, one of the main tools in the Developer Workbench. You use the Design Editor to specify the structure and appearance of a report or a report component. Most of the later sections in this guide discuss specific tasks you perform using the Design Editor. For example, Designing page layouts, explains how to use the Design Editor to modify page layouts.

The Design Editor window is split into two panes. The left pane shows the structure of the report design, and the right pane shows the layout. You can drag the splitter bar to show or hide either pane.

See also

About the structure pane
About the layout pane
Understanding the meaning of the Design Editor display


About the structure pane

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

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

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

Components from included modules

When a component name appears in gray in the structure pane, it indicates that the component is defined in another module, and your design is using the component by referring to that module. You cannot modify these components from the report edit view. You can edit them only from within the source module. Components whose names appear in black are declared in the current report design module (the main report design (.ROD) file of your project). For more information about referring to components in included modules, see Referencing components.


About the layout pane

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

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


Understanding the meaning of the Design Editor display

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

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

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

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


About the Design Editor's helper tools

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

With this Helper...	You can....
1 Field List	Place components that display data in a report design. The Field List shows variables in the data row available for use in a particular part of the report. To activate the Field List, a frame must be selected.
2 Scratch Pad	Temporarily store components as you move them from place to place.
3 Library Browser	View components in a library, publish components, or drag-and-drop components to the Design Editor. This browser displays any library file included in your project.
4 Project Browser	View the files included in your report design, move components from file to file, or  drag-and-drop components to the Design Editor. This browser shows a subset of the components shown in the Globals Browser (5), organized by file.
5 Globals Browser	View the components from all files included in your report application or drag-and-drop components to the Design Editor. This browser shows the same components as the Project Browser (4), organized alphabetically, without showing which file contains each component.
6 Component Editor	View and modify a component's properties, methods, class information, and variables.
7 Stored Procedure Browser	View the list of stored procedures available in the database you have defined in the Stored Procedure Builder. Activate the Stored Procedure Browser from the browse button on the Stored Procedure Builder dialog box.

You can adjust the settings of the Project Browser and Globals Browser. To do so, do the following:

1	Right click over a blank area of the Project Browser.

2	Choose Settings.

3	In Browser Options, choose from the Types Filter, Members Filter and Misc. Filter shown. The default condition is Classes only.

4	Click Ok.

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

Helper	More information
Field List	Placing data controls in a frame.For an example of use, see Add controls to display retrieved data
Scratch Pad	About the Scratch Pad
Library Browser	For an overview, see Working with component libraries. For an example of use, see Lesson 5. Add frames to the group sections
Component Editor	About the Component Editor
Stored Procedure Browser	For more information about data streams and stored procedures, see Using stored procedures

See also

About the Component Editor


About the Component Editor

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

Using Component Editor pages and tabs

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

Page	Task	For more information
Properties	View or set properties, such as font size or background color. Also lets you access the Expression Builder.	Setting properties of components
Methods	View, override, or add methods using the Method Editor.	About the Method Editor. Also, Programming with Actuate
Variables	Add new variables or make a variable a property or parameter.	Programming with Actuate
Class	View or modify class information, such as class name, superclass, and scope.	Programming with Actuate


About the Query Editor and stored procedures

You use the Query Editor to specify a query, which is a statement that specifies which data from the database to include in the report. When you open the Query Editor, the Database Browser accompanies it, as shown in the illustration below. The Query Editor is a central tool in the Developer Workbench. For more information about the Database Browser, see About the Database Browser.If you are using stored procedures provided by a database, you place the stored procedure component in the report design's data stream slot. The stored procedure component requires that you then work with the Stored Procedure Data Source Builder, rather than the Query Editor. For more information on stored procedures, see About the Stored Procedure Data Source Builder. See also Using stored procedures.

For more details about using the Query Editor, see Query data streams.

See also

Using Query Editor pages and tabs
About the Database Browser
About the Stored Procedure Data Source Builder


Using Query Editor pages and tabs

The Query Editor is made up of seven pages, each of which is used for a particular task. To display a page, choose the appropriate tab. To change the display in the upper pane, choose a tab in the lower pane, then choose the Move page up button.

Page	Task	For more information
Tables and Joins	Select tables and specify the joins between the tables	Selecting tables and Creating joins
Columns	Select columns or define computed columns	Selecting columns
Conditions	Specify criteria for which rows the query retrieves from the database	Putting conditions on row retrieval (Where)
Order By	Specify how rows are sorted	Sorting data with the Query Editor
Group By	Specify aggregate rows, which total data from a group of rows	Summarizing data
Having	Specify criteria for selecting specific aggregate rows	Putting conditions on aggregate rows (Having)
SQL	View the SQL SELECT statement	Viewing the SELECT statement


About the Database Browser

The following illustration shows the Database Browser, the Query Editor's helper window. The Database Browser displays a diagram of the available databases, tables, and columns managed by the DBMS server to which Actuate is connected. To specify which tables you want in the query,
drag-and-drop tables from the Database Browser to the Query Editor. The following illustration shows how the Database Browser appears when connected to a Microsoft Access server. The display may be different when connected to other types of servers.


About the Stored Procedure Data Source Builder

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

You may also type parameters into the Sample Parameter Values dialog box if the stored procedures and the database that you are accessing allow parameters. If you use parameters, the Requester dialog box prompts users for more information at run time.


About the Method Editor

The following illustration shows the Method Editor, one of the main tools in the Developer Workbench. Access the Method Editor from the View menu or from within the Component Editor. Use the Method Editor to write Actuate Basic code in methods. A method is a function or procedure that is associated with a component.

By default, the list of methods displayed in the Method Editor is a list of methods that you are likely to override. To see all methods, you must select the Filter button and choose among the selections in the dialog box that appears.

The list of methods displayed in the Method Editor changes whenever you select a different component. The title bar gives the name of the component for which information is currently displayed.

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

For more information about how to program methods, see Writing and using procedures in Programming with Actuate.


About the Expression Builder

The following illustration shows the Expression Builder, which you use to construct conditional and mathematical expressions.

The Expression Builder is used to construct the following types of expressions in a report design.

•	Actuate Basic value expressions for properties in the Properties page of the Component Editor

•	Query by Example (QBE) expressions to place conditions on rows in the Conditions and Having pages of the Query Editor

•	SQL expressions for calculated columns in the Columns page of the Query Editor

The choices offered in the Expression Builder vary depending on which type of expression you are working with. For example, when you write an expression for the Columns page of the Query Editor, the constant Null is available. This constant is not valid in a property value expression, so it is not displayed when you are writing this type of expression.

For more information about QBE expressions and the Columns page, see Query by Example (QBE) syntax and Selecting columns. For more information about Actuate Basic expressions, see Programming with Actuate.

See also

Example expressions
How to write an expression using the Expression Builder


Example expressions

The following table shows examples of expressions you can write using the Expression Builder.

Expression	Where used	Description
"Order " & [orders.ordID]	ValueExp property of text control	Actuate Basic expression that displays order number for each order
> 100	Conditions page of Query Editor	QBE expression that retrieves only rows in which the value of the selected column is greater than 100
items.priceQuote * items.quantity	Columns page of Query Editor	SQL expression that specifies a computed column that retrieves the extended order amount

In the SQL expression, the column name does not have to be enclosed in brackets.


How to write an expression using the Expression Builder

1	To open the Expression Builder, choose the Builder button.

The Builder button appears whenever the Expression Builder is accessible. For example, when you select a control's ValueExp property in the Properties page of the Component Editor, the Builder button appears.

2	In the Expression box, build the expression as follows:

•	Type the expression.

•	Choose an element from below the Expression box. Choose Insert.

3	When the expression is finished, choose OK.


About the Viewer

The following illustration shows the Viewer, one of the main tools in the Developer Workbench. You use the Viewer to look at the results when you run a report. The Viewer provides active viewing features, such as hyperlinks and saved searching. For more information about how to use the Viewer, see Using Reports.


About the Navigator

If you work in a client/server reporting environment, the Navigator is the tool for distributing and accessing report files in the Report Encyclopedia. The Report Encyclopedia is a file management system, similar to the Windows 95 Explorer, that provides access to files on a report server.

As a developer of report designs, you can use the Report Encyclopedia to store your report designs or report executables in a central location so that others can modify or run the reports. If you are part of a report development team, you can use the Report Encyclopedia to store shared files, such as libraries of components or Basic source files.

For more information about using the Navigator and Report Encyclopedia, see Using Reports.

For more information about viewing your HTML report in a Web browser, see Building HTML reports.


About the toolbars and palettes

The main application window contains a main toolbar, a format toolbar, several tool-specific toolbars, and a component palette. You can choose to display all, none, or any combination of these items through the menu options in View→Toolbars. The following illustration shows the application window with the main toolbar, format toolbar, and Component palette open.

For information about how to reconfigure the toolbars and palettes, see  Moving and closing toolbars and palettes.

See also

The main toolbar
The formatting toolbar
The tool-specific toolbars
The component palettes


The main toolbar

The main toolbar provides quick access to common tasks, such as creating a new file, opening a file, and saving a file. The buttons on the main toolbar are enabled or disabled depending on what is open and where the cursor focus is. The cursor focus could be in the structure pane, the Query Editor, the .ROD file, the .ROI file, or other parts of the Developer Workbench. See the illustration of the main toolbar, below.

To discover the purpose of each button, position the mouse cursor over the button and wait for the tool tip to appear. If the main toolbar disappears, look at View→Toolbars→Main, to see that "Main" is checked.


The formatting toolbar

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

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


The tool-specific toolbars

The following tools have their own toolbars: Viewer, Query Editor, Debugger, Stored Procedures and Navigator.

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


The component palettes

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

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

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

You may make the main component palette visible and invisible by choosing View→Toolbars→Palettes→Palette. The main palette is visible when "Palette" is checked.

After you display a palette by choosing the appropriate button in the main palette, you can use the pushpin button to keep the palette open while you work. Otherwise, when you choose a button in another palette, the first palette closes. You can move or dock a palette just as you can a toolbar. For information about moving toolbars and palettes, see  Moving and closing toolbars and palettes.

You can also customize the palette buttons and layout. For information about customizing palettes, see  Customizing component palettes.


About context menus

Many tools in the Developer Workbench provide context menus. A context menu is a menu that contains commonly used commands associated with a particular item, such as a component or dialog box.

See also

How to display a context menu


How to display a context menu

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

2	Press the right mouse button.

Following is an illustration of one of many context menus.


Query Editor Property Sheet - Join Properties

1	To change the join operator, select the operator you wish in the drop-down list box.

2	To specify a left or right inner join instead of an regular-join, select one of the options in Type of Join.


Structure View Options dialog box

Display Options

These options affect the text to the right of icons in the structure pane.

•	Slot name is the name of the slot, such as Content.

•	Component name is the unique identifying name of the component (its class name), such as Frame1.

Filtering Options

•	Empty Properties displays slots. Use this setting if you prefer using slots, which give you a hint about where things can go, rather than dropping components directly into the layout or onto the component icon in the structure.

•	Visual Components displays components that also appear in the layout pane, such as frames and controls.

•	Inherited Components displays inherited components.

Prompt for Name

Gives you an opportunity to type a name for each component as you add it to the design. Use this setting to make the report design more readable and to provide orientation cues as you work. Turn off this setting to let Actuate supply automatic, numbered labels. Using Actuate's automatic labels makes the process of adding a component faster. You can go back and type more descriptive names later.

Defaults

Choose the Defaults button to return all selections in this dialog box to their default values.


Layout Editor Settings dialog box

Show Empty Slots

Displays slots. Use this setting if you prefer using slots, which give you a hint about where things can go, rather than dropping components directly into the layout or onto the component icon in the structure.

Show Group Sections

Shows a gray bar for each group section.

Display Sample Data

Displays sample data in the layout. Use this setting when you want the layout to look more like a real report. You must also type the sample data in the SampleValue property of each component. If deselected, the value expression from the ValueExp property is displayed.

Prompt for New Name

Gives you an opportunity to type a name for each component as you add it to the design. Use this setting to make the report design more readable and to provide orientation cues as you work. Turn off this setting to let Actuate supply automatic, numbered labels. Using Actuate's automatic labels makes the process of adding a component faster. You can go back and type more descriptive names later.

Snap to Grid

Automatically aligns components to the grid as you place them in the report.

1	Select Snap to Grid.

2	Type values in Horizontal and Vertical to specify the size and shape of each grid square.

3	(Optional) Select the units of measurement. The size of the snap to grid can be different from the size of the displayed grid, but the units of measurement are the same.

Display Gridlines

Displays vertical and horizontal guidelines in the layout. These gridlines do not affect the placement of components. They are simply a visual cue to help you place components.

1	Select Display Gridlines.

2	Type values in Horizontal and Vertical to specify the size and shape of each grid square

3	(Optional) Select a unit of measurement (inches, centimeters, points, or twips).


Parameter Attributes dialog box

The following illustration shows most of the fields in this dialog box. The Alias and Group fields are described in more detail after the illustration.

Alias

You can write a prompt for the parameter that means more than the parameter name. For example, for a parameter named State, you might write a prompt like "Customer state:"

Use the Alias field of the Parameter Attributes dialog box to type the prompt you want to appear in the Requester dialog box when the user runs the report.

Group

You can also display related parameters in named groups. For example, you might have a group called Font that contains variables for text color and size.

Use the Group field of the Parameter Attributes dialog box to create groups using the following procedure.

1	Choose View→Parameter.

The Parameter Editor appears.

2	Select the parameter you want to place in a group.

3	Choose Modify.

The Parameter Attributes dialog box appears.

4	In Group, type a new group name or select an existing group name. Choose OK.

5	To place additional parameters in the same group, repeat steps 2 through 4.


Use As dialog box

The Use As dialog box appears when you place a component on an icon in the structure pane. For example, to add a frame to a group section, drag and drop the frame component on the group section icon in the structure pane.

The Use As dialog box appears, in which you specify how you want the frame to be used in the section. The choices listed in this dialog box are the same as the names of the group section's slots. Move the highlight in the Use As dialog box to the name of the slot you want to use and choose OK.


Query Editor Property Sheet - Column Properties

Use this dialog box to change the Actuate Basic data type of the column in the report's data row. The data type of the column in the data row does not have to be the same as the data type of the column in the database. However, it must be a compatible type.

1	Double-click the column name. The Column Properties dialog box appears.

2	The DB Type field displays the data type of the column in the database.

3	In Basic Type, select the Actuate Basic data type.


Open dialog box

Select the drive and directory of the file you want to open.

File Name

Enter the filename. You can specify the path with the filename.

Files of type

To change the list of displayed files, select the file type.

Drives and directories

Select the drive and directory where you want to store the document.

Types of files you can open

.ROD (report object design) file

A file that contains a report design. An .ROD file is created when you save a report design. Open an .ROD file to edit an existing report design.

.ROI (report object instance) file

A file that contains the viewable report. An .ROI file is created when you run a report. Open an .ROI file to view a finished report.

.ROL (report object library) file

A file that contains published components. An .ROL file is created using the File -New menu command in the Developer Workbench. Open an .ROL file to edit the library.

A component library (.ROL) is a file that contains components which can be used in one or more report designs. Component libraries provide one of the most useful ways to reuse components. The person who designs the components publishes them, or saves them, in a library file. Other users can include the library file in their designs and place the components from that file in report designs just as they would place components from the component palette.

.HTML file

A file that contains a report viewable in a web browser. Three .HTML files can be created when you run an HTML report: index.html; report.html and TOC.html. To create an .HTML file, use the Report Wizard to create an HTML report.


Database Login dialog box

Type the connection properties required by your database server, as shown in the following table.

Connection type	Required  connection  properties	Optional connection properties
DB2	DllPath DataSource User Name	Password may be required depending on your user account.
Informix	DllPath Database Environment UserName	Password may be required depending on your user account.
MS SQL	User name	Server name. If not supplied, Actuate  defaults to locally-defined server. Password may be required depending on your user account.
Oracle	User name Host string	Password may be required depending on your user account.
ODBC	Name of data  source	Connection string User name and password may be required depending on which driver you are using.
Progress	Database List DllPath StartUp Parameters User Name	Password may be required depending on your user account.
Sybase	User name Server name	Password may be required depending on your user account.
SybaseDBLib	CsDllPath CtDllPath ServerName UserName	Password may be required depending on your user account.
For details about the connection properties of a particular connection type, see your DBMS documentation.

If you do not supply the required connection properties by setting them in the connection component, the Database Login dialog box will appear whenever Actuate needs to connect to the database, and you or the user will have to type the connection properties at that time.


Welcome dialog box

This Welcome dialog offers some quick-start options each time you use the Developer Workbench. Click one of the four quick-start options to:

•	Start the Report Object Design Wizard. The Report Object Design Wizard guides you in setting up a new report design. You'll establish a connection to the database, choose tables and fields for your data, and set a page layout.

•	Open the tutorial "Building Your First Report." This online help gives a new user step-by-step guidance in creating a report.

•	Read more about the design process. For a quick summary of the report design process, click this option. From the summary page, you can browse the online help topics for each part of the report design process.

•	Open a sample Report Object Design. The sample reports that were installed with the Developer Workbench provide good examples of how you can use the application for your own report designs. Included are sample reports that illustrate graphs, crosstab reports, detail reports, and summary reports.


Name Space View Options dialog box

Specify which types of symbols you want to view in the Browser.

Types Filter

•	Select Classes to show components and internal classes.

•	Select Type Aliases to show Actuate Foundation Class data types that are not part of Actuate Basic. In other words, this selection displays data types that were declared with the Typedef statement.

•	Select Structures to show global structures (records). In other words, this selection displays structures that were declared with the Type...End Type statement.

Members Filter

•	Select Functions to show functions, including global functions and member functions within each class.

•	Select Variables to show variables, including global variables and variables that are part of a structure or class.

•	Select Constants to show global constants defined in the Actuate Foundation Classes.

Misc. Filter

•	Select AFC Symbols to show symbols defined in the Actuate Foundation Classes. When AFC Symbols is not selected, the Browser shows only items defined by the developer.

•	Select Inherited Symbols to show symbols inherited from superclasses. When Inherited Symbols is not selected, each class shows only items defined in that class.

Defaults

Choose the Defaults button to return all settings in this dialog box to the default values.


Save As Dialog Box

Save the active file with a new name, location, or file format.

File Name

Type a new filename. To save a file with an existing filename, select the name in the list or type the current name. When you choose the OK button, Actuate asks if you want to overwrite the existing file.

Save File As Type

Actuate can save documents in several file formats. The list of formats depends on the type of file you are working with.

Select .ROD to save a file that contains a report design. Select .ROL to save a file that contains published components for reuse by other users.

Drives and directories

Select the drive and directory where you want to store the document.


Single Structure Reference dialog box

Shows detailed information about a slot and the contents of that slot. This dialog box applies to slots that can contain only one component at a time. A slot is a location in the Design Editor that indicates where you can place a component. You can use this dialog box to get information about an empty slot or a slot that contains a component.

Container Component

Displays the class name of the component that contains the selected slot.

Relationship Definition

•	Name displays the name of the slot.

•	Defined By displays the name of the class in which this slot is defined. A slot is really a visual representation of a component reference property. Like any property, a component reference property is defined in a class.

•	Reference To displays a class name that tells which types of components can be placed in this slot. Any component derived from the displayed class can be placed in this slot.

Contents

Displays information about the current contents of the slot. The slot can be empty, or it can contain one component.

•	Name shows the fully qualified class name of the component, if the slot contains one. You can type a new name to place a different component in the slot. Use this method when it is more convenient than dragging and dropping a component.

•	Set in Module shows the name of the file in which the relationship between the container component and the component in the slot is defined. This helps you find out whether the relationship is inherited or locally defined.

•	Set in Component shows the name of the class in which the relationship is defined.

•	Description shows an explanation of all the previous information in the dialog box. Actuate automatically generates the description.

Drop

Removes the content component from the report design. Locally defined components are deleted. Inherited components are simply ignored.

Subclass

Declares a subclass of the content component. You can subclass only inherited components, not locally defined components.

Default

Returns the slot to its original state before you made modifications. If the slot contains a locally defined component, the component is deleted. If you dropped an inherited component from the slot earlier, Default undoes the Drop operation and returns the inherited component to the slot.


Design Properties dialog box

File Name

Shows the name of the file for which you are modifying properties.

Target Report Name

Shows the name of the report component. Use the drop-down list to select a new report component from any module included in your design. This is the only way to delete the report component and replace it with another.

Read Only

Select to prevent yourself from accidentally modifying this design file.

Design Comment

Type a description of the design, a revision history, or any other comment. There is no limit on the length of comment text. You can reopen this dialog box to view the comments or add to them at a later date.


Structure Reference List dialog box

Shows detailed information about a slot and the contents of that slot. This dialog box applies to slots that can contain several components simultaneously. A slot is a location in the Design Editor that indicates where you can place a component. You can use this dialog box to get information about an empty slot or a slot that contains one or more components.

Container Component

Displays the class name of the component that contains the selected slot.

Relationship Definition

•	Name displays the name of the slot.

•	Defined By displays the name of the class in which this slot is defined. A slot is really a visual representation of a component reference property. Like any property, a component reference property is defined in a class.

•	Reference To displays a class name that tells which types of components can be placed in this slot. Any component derived from the displayed class can be placed in this slot.

Contents

Displays information about the current contents of the slot.

•	Set in Module shows the name of the file in which the relationship between the container component and the slot is defined. This helps you find out whether the relationship is inherited or locally defined.

•	Set in Component shows the name of the class in which the relationship is defined.

•	References shows the names of all the components that are currently in the slot. The order of components in the list is the order in which they will appear when the report runs. You can reorder the components by selecting one and choosing the up or down arrow button to the left of the References list.

•	Dropped Inherited References shows the names of inherited components you have removed from the design using the Drop button.

Default

Returns the slot to its original state before you made modifications. If the slot contains locally defined components, the components are deleted. If you dropped inherited components from the slot earlier, Default undoes the Drop operation and returns the inherited components to the slot.

Resync

Updates the slot with new information from the module from which it inherits. For example, in a report design that is a subclass of another report design, use Resync to pick up changes in the master design. The Resync operation might add or delete components.

Subclass

Declares a subclass of an inherited component. Select the name of an inherited class in the References list, then choose Subclass. The new class name replaces the inherited class name in the References list. The superclass name moves to the Dropped Inherited References list.

Drop

Removes a component from the References list. Select a component name in the References list and choose Drop. The component reference is removed from the report design. The component no longer appears in the Design Editor. If the component is inherited, its name moves to the Dropped Inherited References list.

Add

Places another component in the References list. This is equivalent to dragging and dropping a component to the slot. A dialog box appears in which you select the desired component.

Restore

Adds a previously dropped component to the References list. Select a component name from the Dropped Inherited References list and choose Restore. The Restore button applies only to inherited components.


New File dialog box

Report Wizard

Starts the Report Design Wizard, a dialog box with several tabbed pages in which you make selections. Use the Report Design Wizard to get a head start on a tabular or grouped report with a query data source. The wizard gives you more of a head start than the Report Quick Start selection.

Subclass a Design

Starts a new report design that inherits everything from another report design. Opens the Open Base Report Design dialog box, in which you select the .ROD file you want to use as the basis for your new report. Use this method to create a slightly customized version of another design.

Based on Components

Includes a library file in a new report design, so you can use published components as the basis of the new report. Opens the Open Component Library dialog box, in which you select the library (.ROL) file.

Blank Report Design

Starts a new report design that contains no components.

Component Library

Starts a new component library (.ROL file) and displays it in the Library Browser. Use this method to publish new components in a new library.


New Class dialog box

Class Name

Type a name for the new class.

Super Class

(Optional) Specify which class you want to derive from. Type the fully qualified class name. If you do not specify anything in Super Class, the new class is a base class.

Nested in Class

(Optional) Specify in which class you want to nest the new class declaration. Type the fully qualified class name.

Global in Module

Select the file in which you want to store the definition of the class.

Please Enter ROX path dialog box

changed to Load Executable dialog.


Load Executable dialog box

This dialog box appears when you open a report for viewing (.ROI file) and Actuate can not find the corresponding .ROX file. For example, the file may have been moved to another directory.

File Name

Enter the filename. You can specify the path with the filename.

Files of type

To change the list of displayed files, select the file type.

Drives and directories

Select the drive and directory where you want to store the document.


Parameter Editor

The Parameter Editor displays the parameters in a report design. The default values of the parameters, if any, are displayed to the right of the parameters. You can modify or add default values by typing in these fields in the Parameter Editor.

A parameter is a variable that passes data into a report when the report runs. You define parameters as part of the report design to let the user enter criteria when they run the report. For example, you can let the user specify a range of dates for the report. When the user runs a report, the Requester dialog box appears and prompts the user to type values for the parameters you have defined.

You can also create parameters that do not appear in the Requester. Use these parameters when you want to supply a value programmatically at runtime without allowing user input.

Apply

Makes the changes you have specified in the Parameter Editor effective in the report design.

Add

Defines a new parameter. A dialog box appears in which you specify the characteristics of the new parameter.

Delete

Removes a parameter from the report design. Select a parameter name, then choose Delete.

Modify

Changes the definition of a parameter. Select a parameter name, then choose Modify. The Parameter Attributes dialog box appears, in which you change the characteristics of the parameter.


Move Class dialog box

Changes the scope, or name space, of a class. Also moves any other classes that are within the name space of the class being moved. The Globals Browser shows which classes are within another class's name space.

Class Name

Select the class you want to move.

Nested in Class

Select the class in whose name space you want to nest the class.

Global in Module

Choose a file name to give the class a global scope in that module. The class definition is saved in the selected file.

Deep Move

Moves the component and all the other components it contains (as shown in the structure pane of the Design Editor) to the new name space.


Publish Class dialog Box

To publish a component means to place it in a file for reuse.

Class Name

Select the class you want to publish.

Publish to Module

Select the file in which you want to publish the component. You can select an .ROL or .ROD file. In most cases, components are published in .ROL (library) files.


Class Variable dialog box

Define the characteristics of a new variable or modify an existing variable.

Name

Type a name for the new variable. The name must follow Actuate Basic naming rules, including the following.

•	Can contain only letters, numbers, and underscore characters

•	Must not contain space characters

•	Must not duplicate another variable name in the same scope

•	Must not be an Actuate Basic reserved word

Type

Select an Actuate Basic data type, or enter the name of a user-defined type, such as a  structure or class name.

Storage

Select one of the following values.

•	Instance (per object) specifies that the variable can have a different value for each object in the generated report (.ROI file). For example, the value of a text control is set by an instance variable, because the value is different for each instance of the text control.

•	Static (shared by all objects) specifies that the variable has one value at runtime.

Visibility

Select one of the following values. Some values might be unavailable, depending on the selections you made in Data Type and Storage Type.

•	Property specifies that the variable is a property. The new property appears in the Properties page of the Component Editor.

•	Required Property specifies that the variable is a property. The new property appears in the Properties page of the Component Editor, and Actuate prompts for a value whenever you place a component of this type in the report design.

•	Private specifies that the variable appears in the Variables page of the class in which it is declared, but not in the Variables page of subclasses. Make a variable private if you intend to use it only in the class where it is declared and do not want to clutter the Variables page of the subclasses.

•	Public specifies that the 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 specifies that the variable is a parameter. Actuate prompts the user for a value when the user runs the report. To specify the characteristics of the parameter, choose the Builder button.

Builder button (...)

Displays the Parameter Attributes dialog box, in which you set the characteristics of a parameter variable. The Builder button is enabled when you choose Parameter in the Visibility list box.

Column

Displays the name of the database column that corresponds to the variable. This information appears only when the variable is part of a data row that is associated with a query data source component.


Add Method dialog box

Name

Type a name for the new method. The name must follow Actuate Basic naming rules, including the following.

•	Can contain only letters, numbers, and underscore characters

•	Must not contain space characters

•	Must not duplicate another method name in the same scope

•	Must not be an Actuate Basic reserved word

Type

(Optional) Enter a data type for the return value of the method. The data type can be an Actuate Basic data type or a user-defined type. If omitted, the method is a Sub, which has no return value.


Choose Included Module dialog box

1	Select the name of the file you want to view in the Library Browser.

2	Choose OK.


Module Properties dialog box

View or specify information about a module (file) in the Browser.

File Name

Shows the name of the file to which the information in the dialog box applies.

File Type

Displays the type of the file, such as design or library.

Read Only

Select to prevent yourself from accidentally modifying this file.

Comment

Type a description of the module, a revision history, or any other comment. There is no limit on the length of comment text. You can reopen this dialog box to view the comments or add to them at a later date.


Property Parameter Info dialog box

Define the characteristics of a parameter that provides a value for a component property.

Name

Type a new parameter name or accept the default name. The name must follow Actuate Basic naming rules, including the following.

•	Can contain only letters, numbers, and underscore characters

•	Must not contain space characters

•	Must not duplicate another variable name in the same scope

•	Must not be an Actuate Basic reserved word

Scope

Like other variables, parameters have scope. The scope of a parameter is the portion of the report design from which the parameter can be referenced.

•	Global specifies that you can reference the parameter from anywhere in the report design.

•	Local specifies that you can reference the parameter only from other places within its scope.

For example, a local variable that sets the font color in a control could be referenced in method code in that control, but not in another control.


Factory Status dialog box

Shows progress information as Actuate runs a report. While this dialog box is displayed, Actuate uses the query to get data from the database and creates the frames and controls to display that data on the pages of your report.

File

Displays the file name of the report you are running.

State

Displays progress messages from Actuate.

Page

Shows which page of the report is being generated.

Run

Starts running the report, beginning from page 1 of the report. You can use this button either after opening an .ROX (executable) file or after using the Halt button.

Halt

Stops running the report. The partially-run report is not viewable.


Edit OLE Container dialog box

See also "Using objects from other applications," in Programming with Actuate.

Edit

Opens the OLE server application so you can modify the OLE item in the container. For example, if the OLE item is a Microsoft Word document, Edit opens Microsoft Word.

Drop

Removes the OLE item from the currently selected container component. The container remains in the report design, but it is empty.

Create local copy

This selection is available only for a container component that displays an inherited OLE item. That is, the container is a subclass of another container, and both use the same OLE item. This selection makes a copy of the OLE item, so that you can make local changes without affecting the original OLE item in the superclass.

Create

Adds an OLE item to the container component. If the container already contains an OLE item, that item is dropped and the new item replaces it.


Input box

This is a custom dialog box. The title, prompt, and default value were all set through the Actuate Basic InputBox function by the report developer. Because this dialog box was not developed by Actuate, this help topic can not supply specific instructions.


Goto Line dialog box

Type a number to indicate which line of code you wish to view. The selected line will scroll to the top of the window.


Choose Included Basic File dialog box

Select the file you want to remove from the report design project. Your report design includes several Basic files, and Actuate can only remove one at a time.


Print dialog box

Printer

Displays the name of the printer to which the print job will be sent.

Print Range

•	Select All Pages to print the whole report.

•	Select Current Page to print the page that is displayed in the Viewer at the moment.

•	Select Ranges of to specify particular sets of pages. Follow the instructions that appear on the dialog box.

Copies

Type the number of sets of printed output you want.

Print Quality

Select a dpi setting to specify the printing resolution. The higher the number, the finer the resolution, and the higher the print quality.

Reverse Order

Prints the highest-numbered page first, then proceeds backwards, ending with page 1.

Print to File

Sends the output of the print job to a file on disk instead of to a printer.

Collate Copies

Prints multiple copies in sets that are ready to distribute. If this setting is not selected, the print job will produce the specified number of copies of the first page, then copies of the second page, and so on.

Setup

Opens a dialog box in which you change the attributes of the printer or select a different printer.


Message window

See also Generating and compiling code and the chapter on Debugging in the Programming with Actuate.

This window displays messages from Actuate. You need not take any action in response to this window. However, if you see messages about errors you would like to correct, you can use the following technique to display the source of the error so you can fix it easily.

1	Double-click the error message in the message window.

Actuate opens the appropriate window and shows you where you need to fix the error. For example, if you set a property to an invalid value, the Properties page appears.

2	To fix the next error, press F4.

3	To fix the previous error, press F3.

The message window displays two kinds of messages, consistency check messages and compiler messages.

•	Consistency check messages are displayed while Actuate checks your design. Actuate performs a consistency check when you choose Report→Verify Design.

•	Compiler messages are displayed while Actuate is compiling the underlying Actuate Basic code for the report.

When you run a report or generate code for a report, Actuate automatically writes Actuate Basic code and saves it in a .BAS file. The .BAS file contains code, including class declarations, that corresponds to the design information in the report design.

After Actuate generates code, it compiles the .BAS file and creates an executable file, or .ROX. The message window displays messages during this operation.


Save Modified Modules dialog box

You made changes to one or more modules (files) included in the report design. Use this dialog box to specify which changes you want to save before you close the design. The name of one modified module is displayed in the dialog box prompt.

Yes

Saves changes to the module named in the prompt. If other modules have been modified, Actuate will display this dialog box again to ask you for confirmation before saving each additional module.

Yes All

Saves changes to the module named in the prompt and all other changed modules without prompting you for further confirmation.

No

Discards changes to the named module. If other modules have been modified, Actuate will display this dialog box again.


Rename dialog box

Type a new name for the component and choose OK. The name must follow the naming rules described in the "Introduction to programming with Actuate Basic" in Programming with Actuate.

Take the scope of the component (class) into account. Classes with global scope must have unique names. Classes with nested scope need not have unique names because they are hidden within the scope of the enclosing class.


Choose Connection dialog box

Select the name of the database connection you want to use. The currently selected query data stream is used in more than one place in your report design, and it is associated with different connection components. To perform the command you have requested, Actuate must log on to a database server by using one of these connections. Actuate can only open one connection at a time.


Add List Use dialog box

Type a class name. The class must be defined in a module that is included in the report design project.

Use this dialog box to place another component in the References list of the Structure Reference List dialog box. Using this dialog box is equivalent to dragging and dropping a component to the report design.


Select Component dialog box

Choose which type of component you want to add to the report design.

This dialog box appears when you add a component for which there are several varieties. The dialog box lists class names that correspond to the component varieties. For details about these classes, see Actuate Foundation Class Reference.


Query List dialog box

Select which query you want to view. Your report design contains more than one query, and the Query Editor can only display one query at a time.

If you select a particular query data source component in the structure pane before you open the Query Editor, the Query Editor displays the query in the selected component. The Query List dialog box is displayed only when the currently selected component is not a query data source.


Help Directories dialog box

Type the directory path where the required help file is installed.

If you have moved Actuate directories since you installed the product, you may wish to edit your AUTOEXEC.BAT file to add the current Actuate help directory to your PATH.


Component Properties dialog box

Type values for all properties displayed. The properties displayed in this dialog box are required for the type of component you are adding to the report design. Each property determines one attribute of the component's appearance or behavior.  For details about the specific properties listed, see Actuate Foundation Class Reference.


Variable Filtering dialog box

Specify which variables you want to view.

Visibility

•	Select Local variables only to show variables declared in the currently selected component.

•	Select Plus public inherited variables to show variables declared in the currently selected component and public variables declared in its ancestor classes. Only variables declared as Public are included with this selection. A public variable is intended to appear in the Variables page of a class and its subclasses.

•	Select All variables to show public and private variables defined in the currently selected component and its ancestor classes. A private variable is normally intended to be used only in the class in which it is declared, so it does not normally appear in the Variables page of a subclass.

Kind of Variable

•	Select Regular Variables to show variables that Actuate needs when generating the report. For example, the PageCount variable in the Book class stores the current page number, which Actuate updates continuously as it generates the report.

•	Select Parameter Variables to show variables for which you supply a value when you run the report.

•	Select Property Variables to show variables that define the attributes of the selected component. For example, all controls have property variables such as BackgroundColor and Position that define their  appearance. Property variables appear in the Properties page of the Component Editor.


Method Filtering dialog box

Only local methods

Displays methods declared in the currently selected component.

Include inherited methods you can override

Displays methods declared in the currently selected component and its ancestor classes. Of the methods from ancestor classes, only those that are designed to be overridden are shown. Such methods give you the flexibility to safely customize parts of the report generation or report viewing process. For example, methods that have an "On" prefix let you add code that executes after an event occurs.

Include inherited methods you can call

Displays methods declared in the currently selected component and its ancestor classes. Of the methods from ancestor classes, only those that are designed to be called, not overridden, are shown. Such methods typically provide a defined service or information about an object. For example, data adapter classes provide methods such as SeekTo( ), SeekBy( ), SeekToEnd( ), and Rewind( ) that you can call to access retrieved data. You can, but typically do not, override this type of method.

Show all methods

Displays all methods of the currently selected component, including local and inherited methods, whether or not they were designed to be overridden.


Class Name dialog box

Type a new name for the component and choose OK. The name must follow the naming rules.

Take the scope of the component (class) into account. Classes with global scope must have unique names. Classes with nested scope need not have unique names because they are hidden within the scope of the enclosing class.


Using Go To

Type the page number you want and choose OK.

If you happen to be familiar with the page layout of the report or you are working from a printout to access particular report screens, you might want to move directly to a specific page.


Color dialog box

Set the color of the component.

Color|Solid

The patch of color in the left half of this box shows the currently selected color. The patch in the right half shows the closest solid color. Double-click the solid color to make it the current color.

Hue

Hue is the actual color, for example, red, yellow, or purple. Hue refers to the color without regard to saturation or brightness.

Sat(uration)

Saturation refers to how much gray is in the color. The Saturation field shows the saturation from 0 (medium gray) to 240 (pure color). Saturation affects how clear the color is. Luminosity affects how bright the color is.

Lum(inosity)

Luminosity is the brightness of a color. The Luminosity field shows the luminosity from 0 (black) to 240 (white). The column to the right of the color field shows the range of luminosity for the current color. Slide the arrow to the right of the column up or down to adjust the luminosity. When you change the luminosity, the Red/Green/Blue color values also change.

Red/Green/Blue

The values in these fields show the balance of red, green, and blue in the current color. This is sometimes called the RGB color.


Convert dialog box

Convert an embedded object to a different file format.

Current Type

Displays the type of object that you are converting or activating.

Object Type

Select the type of object to which you want to convert the file.

Convert To

Converts the selected embedded object to the type of information selected in the Object Type box.

Activate As

Opens the embedded object in the type selected in the Object Type box, but returns the object to Current Type after editing.

Display As Icon

Displays the selected embedded object as an icon.

Change Icon

Changes the icon that represents the embedded object. This button appears only if you select the Display As Icon check box.

Result

Describes the result of the selected options.


Insert Object dialog box

Insert an object into the report.

Create New

Create and embed a new object.

Object Type

Select the type of object you want to embed.

Create from File

Insert an existing object.

File

Type the name of the file you want to insert. To search for the file, choose Browse.

Browse

Search for the file you want to insert.

Link

Check Link to create a link to the file. If you do not select this option, the object will be embedded.

Insert Control

Insert an .OCX control.

Object Type

Select the control to insert.

Add Control

Add an .OCX control to the system. Choose this option if the control you want does not appear in the Object Type box.


Options dialog box

Set properties for the Design Editor, units of measurement, palettes. Also specify default libraries and database objects displayed in the Query Editor.

•	Editor page

•	Units page

•	Palette page

•	Libraries page

•	Query Editor page

See also

Design Editor page of Options dialog box
Units page of Options dialog box
Palette page of Options dialog box
Libraries page of Options dialog box
Query Editor page of Options dialog box


Design Editor page of Options dialog box

Display Options

•	Show Empty Slots. Check to display all potential containers for components. In the structure pane, an empty slot appears as a gray box in the hierarchy and shows you where you can drop components. In the layout pane, an empty slot appears in the title bar of the section, and all possible slots in the report design are displayed.

•	Show Group Sections. Check to display group sections in the layout pane. A group section title bar appears in the layout pane at the top of the first component of the group.

•	Display Sample Data. Check to display components like labels and images with sample contents in the layout pane. If this option is unchecked, components appear empty.

•	Outline Components. Check to display components with a rectangular outline.

Name Options

•	Slot Names Only. In the Design Editor, you can choose to display only the names of the slots, such as Before, After, PageHeader, PageFooter, and so on. You cannot change slot names.

•	Component Names Only. You can choose to display only the names of the components (empty slots will appear with slot names). Component names, like ReportTitle or OfficeGroupTotals in the sample detail.rod, are unique, and are assigned during the design process.

•	Both Slot and Component Names. Check to display both slot and component names in the Design Editor.

Grid Options

•	Snap to Grid. Check to automatically align components in the layout pane to a grid as you place each component. Set the horizontal and vertical units for the grid. Select a unit of measure in the Unit Recognition area of the Units page to set the preferred units of measurement for the grid.

•	Display Gridlines. Check to display gridlines in the layout pane. Set the horizontal and vertical units for the grid. Select a unit of measure in the Unit Display area of the Units page to set the preferred units of measurement for displaying gridlines. Display gridlines do not affect placement of components. They are simply a visual cue to help you place components.

Miscellaneous Options

•	Prompt for New Name. Check this option and the Design Editor will prompt you to name each component as you create it. Component names must be unique in this report and among its shared report object libraries.

•	Save Design Before Building. Check this option to save the report design before building the report.


Units page of Options dialog box

Set how measurement, size values, and position are displayed in the Developer Workbench.

Unit Display

•	From the combo box, choose a system of measurement for displaying units. The choices in the list depend on your system localization settings.

•	In the Display Suffix box, type a suffix for display (optional). If you choose centimeters as a system of measurement, you could type "cm" in the Suffix box.

•	In the Precision box, type the number of places to the right of the decimal point that should be displayed for fractional sizes.

For instance, if you choose centimeters as the system of measurement and type "cm" in the Suffix box. A size of eight-and-one-half centimeters in the Properties page of a component would be displayed as "8.5 cm."

Unit Recognition

Set other systems of measurement that should be recognized. For instance, if Unit Display is set to centimeters and you enter 1.5 in or 1.5" as the size of a page margin because Actuate recognizes that the suffix both suffixes refers to inches of measurement. Other strings that are recognized include tw for twip, pt and pts for points, mm for millimeters, and cm for centimeters. You can specify additional strings to recognize.

•	From the combo box, choose a system of measurement. Choices depend on your system localization settings.

•	In the text box, type the symbols and strings that correspond to the selected measurement. Separate multiple entries in the text box with a space between each.


Palette page of Options dialog box

Palette Button Identifier

Change the class that is associated with a button on a palette. You can add frequently-used Actuate Foundation classes or custom classes from a component library (.ROL file) to your palette to save time when designing reports.

Choose a class from the list of available palette component classes in the combo box, and select a palette icon for the class in the scroll box to the right. When you make changes to your palette, you can save the changes into an Actuate palette representation (.APR) file for future use.

FullClassName

Type the FullClassName for the palette component class that should be associated with this button. If you add a custom class name that does not have a global association, you need to specify the qualified class name.

Save and Revert options

•	The Default button returns the palette and icon arrangement to their original state.

•	The From File button reads in an Actuate palette representation (.APR) file in which you have saved a set palettes.

•	The To File button saves the current palette and icon arrangement to an Actuate palette representation (.APR) file.


Libraries page of Options dialog box

Specify the Actuate libraries that are automatically added to report designs.


Query Editor page of Options dialog box

Specify the database objects that appear in the Query Editor's Database Browser window. You can show or hide the views and tables in a database.

Object name pattern matching

Enter a wildcard expression to view a subset of database objects.

For example, enter total* to show database objects that start with total.


Customize Toolbar dialog box

Modify component palettes. Add or remove buttons that appear in the palette.

Reset changes the buttons on the palette to the default configuration.


Working with frames and controls

The following topics are available. To view the topics in order, use the Browse button (>>) in the Help window's toolbar.

•	About frames

•	About controls

•	Placing a frame in a report design

•	Placing controls in a report design

•	Specifying a display value for a control

•	Formatting data in a control

•	Formatting frames and controls

•	Working with OLE controls


About frames

A frame is a rectangular container for controls. When you run the report and view or print it, what you see is a collection of frames and controls. By placing a set of related controls in a frame, you can manipulate the controls as a group. For example, you can move a frame from one place to another in a report design or publish it in a component library for reuse in other designs.

The following illustration shows a simple frame. This frame contains eight controls, including the horizontal line behind the image.

See also

How frames relate to data rows


How frames relate to data rows

You can create frames that do not display data from the data stream. These frames contain only static controls such as images and labels. However, most frames display data from the data rows provided by the data stream. Each frame is associated with one type of data row. For more information about data rows, see  About data rows.

When you place a frame in a report section, Actuate automatically associates the frame with that report's data row. For example, in the following illustration, Actuate associates Data Row 1 with Frame 1 and Data Row 2 with Frame 2.

See also

Using a frame from a component library


Using a frame from a component library

When you place a frame from a component library in a report, keep in mind that the frame was probably designed to work with a particular data row. Make certain that the data row in the report has all the variables needed. For example, a library frame may display data from database columns called customers.Lname and customers.Fname. The data row in the report must include variables for at least those two columns. It can also contain other variables.

For more information about data rows, see  About data rows.


About controls

A control is a component that displays data, graphics, or other information. Controls are the most visible building blocks in a report. When you run a report and view or print it, all the information you see is displayed by controls.

See also

How controls relate to data rows


How controls relate to data rows

Data controls can display data from one or more variables in the data row. Data controls include text, integer, floating point, currency, and date/time controls.

A data control can display data from more than one data row variable, combined in an expression that is evaluated to provide the value of the control. For example, to display the total amount for an item in an order, you might multiply the number of items by the price per item and display the result in a currency control. The number of items would come from one variable in the data row, and the price per item would come from another variable.

The label, drawing, and image controls do not interact with the data row. These controls are sometimes referred to as static controls.

Note

You can place the following types of image controls in your Actuate report:

•	JPEG

•	BMP

•	GIF

JPEG images can be viewed by the Actuate Viewer, the Administrator Desktop, the End User Desktop, the LRX and Active X. GIF images cannot be viewed by these products. HTML reports can display GIF images in a web browser, however.

For more information about data rows, see  About data rows. For more information about displaying data in a control, see Specifying a display value for a control.


Placing a frame in a report design

To place a frame in a report design, drag-and-drop the frame icon from the Design Editor's component palette to a section's Content, Before, After, PageHeader, or PageFooter slot. You can also place a frame in another frame.

The following illustration shows a group section component that contains two frames in Before and PageHeader slots. The arrow shows how you would place a third frame in the section.

You can also use prebuilt frames from a library or from another report design. For more information about the different ways to add frames to a report, see Placing components in a report design.

The following illustration shows the Design Editor after a frame is placed in the Content slot of a group section. The frame appears as an icon in the structure pane and as a rectangular area in the layout pane. Keep in mind that these are two views of the same frame, not two different frames.


Placing controls in a report design

In general, you place a control in a frame or directly on a page. Controls that display data from the data stream's data row must, however, be placed in a frame. This section concentrates on placing controls in frames. For more information about placing controls on pages, seeDesigning page layouts.

You can drag-and-drop a control from the Design Editor's component palette to a frame's Content slot or directly into the frame in the layout pane. You can also draw the control instead of simply dropping it. For a description of these methods of adding controls, see Placing components in a report design.

Actuate provides a shortcut for placing data controls from the data stream in a frame. By using the Field List, you place the data controls and associate them with data in one operation. For more information about how to place data controls using the Field List, see Placing data controls in a frame.

The following illustration shows a frame in which image, label, and text controls have been placed.

See also

Placing data controls in a frame


Placing data controls in a frame

The Field List is a helper window that you use along with the Design Editor. Use the Field List to add data controls to a report design. The Field List shows all the data row variables available for use in a particular frame. Variables that store values from database columns are displayed as the database column name, as shown in the following illustration. You can drag-and-drop data row variables from the Field List to the frame to add one or more controls that will contain data from those variables.

The report section that contains the frame also contains a data row component. This data row determines which variables appear in the Field List. For example, in the following illustration, the Field List would show variables from Data Row 1 for Frame 1 and from Data Row 2 for Frame 2.

How to place controls and bind them to data

To place controls and automatically bind them to data, use the Field List. Before working with the Field List, you must define a data row that contains variables. If you open the Field List before the data row exists, there will be nothing for the Field List to display.

When you write a query using the Query Editor, Actuate creates the data row for you based on your choices in the Query Editor. If you do not use the Query Editor, you must define your own data row. For more information about the Query Editor, see About queries. For more information about writing your own data row, see Programming with Actuate.

1	Select the frame in which you want to place a data control.

2	Choose View→Field List.

The Field List appears.

3	Drag-and-drop one or more variables from the Field List to the selected frame in the layout pane.


Specifying a display value for a control

You can associate controls with several kinds of data values. To specify the value a control displays, set the control's ValueExp property. Set this property either indirectly through the Field List or directly by typing a value expression in the Properties page of the Component Editor.

ValueExp can be thought of as having two purposes:

1	Determines how to set the value of the control from the data row by providing an expression to do so.

2	Determines if the control takes one or multiple rows, if ValueType is an AutoValueControl.

The rest of this section discusses value expressions in detail. For more information about the Properties page, see Setting properties of components.

Control value expressions can include anything that is allowed in an Actuate Basic expression, as well as some additional items. Value expressions can include the following.

•	Actuate Basic function calls

•	Actuate Basic statements, operators, symbols, and keywords

•	Variables and constants

•	Method calls

•	Data row variables or database columns

•	References to the values of other controls

•	Aggregate values computed over a set of data rows

For example, the following value expression computes the percentage of credit remaining to a customer.

100 - ([customer.balance] / [customer.limit] * 100)

To get help writing a value expression, choose the Builder button next to the ValueExp property. The Expression Builder appears. For more information about how to use the Expression Builder, see About the Expression Builder.

See also

Specifying single and multiple values in controls
Null values in control value expressions
Displaying data from a single column in a control
Displaying data from several columns in a control
Referencing data row variables or functions
Using a method or function in a value expression
Displaying a value that is not from the data row
Referencing controls in a value expression
Computing aggregates in a value expression


Specifying single and multiple values in controls

The processes in the Developer Workbench assume that most controls you create operate with a single value, for example, a name or a number. A graph, however, takes multiple values from data rows and places them into one control. A one-pass aggregate expression, such as a sum, minimum or maximum, also places multiple values in the control.

In the ValueExp, the default condition for the ValueType property is AutoValueControl. It lets the Developer Workbench make the assumptions regarding single values and multiple values in the ValueExp.

You may wish, for example, to write code to compute an aggregate such as a standard deviation. In this case, you may leave the ValueExp blank, because your computations are in Actuate Basic. This is because the expression in ValueExp is effectively ignored.

See also

Setting the ValueType property


Setting the ValueType property

To cause Actuate to assign a required multiple value to a control when the ValueExp is blank, do the following:

Set the ValueType property on the control to Summary Control.

Note that the BuildFromRow() method returns one of three values: RejectedRow, FinishedBuilding, or ContinueBuilding. For information on BuildFromRow(), see The report generation process in Programming with Actuate.

Setting the value in ValueType to Summary Control causes the BuildFromRow() method to be called multiple times, each with a different row.

Setting the value in ValueType to PerRowControl operates similarly to SummaryControl. It, however, requests that the BuildFromRow() method be called only once.

Developers can, therefore:

•	Let the control take one or multiple rows with the ValueType set at AutoValueControl and

•	Determine how to set the value of the control from the data row by overriding the OnRow() method to provide code that sets the control's value.

For more information about the generation of data rows, see The report generation process in Programming with Actuate.


Null values in control value expressions

Relational databases provide a special value called Null, which indicates that the field contains no data. Actuate Basic processes a control's value expression containing Null in the same way that Visual Basic processes Null. The control is calculated appropriately in the finished report. To test for Null values, use the IsNull( ) function. For more information about Null and IsNull( ), see Computing aggregates in a value expression and Actuate Basic Language Reference.


Displaying data from a single column in a control

To make a control display data from a single column in the data row, you will probably find it easiest to use the Field List. For more information about how to use the Field List, see Placing data controls in a frame. Instead of using the Field List, you can select the column from the drop-down list box in the control's ValueExp property, or type the name of the column in brackets, using the following format.

[<table>.<column>]

For example:

[customers.FirstName]

The table name is one of the tables in your query. If you gave the table an alias, use the alias name. The name must be exactly the same as what you used in the query. If the column name is unique, you can omit the table name.

The column is one of the columns from the table. The column must be one of the columns selected by the query.


Displaying data from several columns in a control

You can combine data from several columns in one control by setting the control's ValueExp property to an expression that includes several column names. This type of control is called a calculated control. For example:

[items.quantity] * [items.pricequote]

[customer.limit] - [customer.balance]

[customer.fname] & " " & [customer.lname]


Referencing data row variables or functions

You can use bracket notation to include a data row variable or function in a value expression. This is useful if you create your own data row, add extra variables to a data row created by the Query Editor, or add a function to a data row. Instead of the table and column name, use the variable or function name. For example, to reference a data row variable, enclose its name in brackets, as shown in the following example.

[customer_fname]

You can also use this notation for structures or objects in the data row. For example, suppose the data row includes a structured data type called Address that includes such variables as FullName, Street, and City. To reference one of these variables, use brackets and dot notation, as shown in the following example.

[Address.FullName]

You can use the same dot notation to refer to members of objects if the data row contains object reference variables.

In a data row that contains customer invoice data, you could include a function to tell how much of the invoice total is overdue. To reference that function in a value expression, enclose the function name in brackets, as shown in the following example.

[Amount30DaysLate]

When you use the bracket notation in a value expression, Actuate first checks to see whether the name inside the brackets is a database column. Therefore, if the data row variable or function name is the same as a column alias, the column will be used instead.

For more information about customizing the data row and referring to objects, see Programming with Actuate.


Using a method or function in a value expression

A control's value expression can include calls to methods and functions. The methods and functions can be defined in the Actuate Foundation Classes, in Actuate Basic, or in code you write. For example, the following expression computes a discount based on a user-defined method, ComputeDiscount.

ComputeDiscount( [customer.id], [order.total_amount] )

The following expression uses an AFC method to display the page number.

PageNo$( )

The following expression uses an Actuate Basic function to display the current date.

Date$( )


Displaying a value that is not from the data row

Some controls are not associated with data from the data row. Label controls can only display static text. Data controls, such as integer controls, are often associated with columns from the data row, but they can also display values that are not derived from the data row. For example, you can use an integer control to display a page number.

For a label control, use the Text property to specify the text you want to display, such as a column heading. You can also use an expression that produces a text value.

To specify a non-data value for a numeric or text control, type a literal value or an expression in the control's ValueExp property. The value expression can be anything that produces a value of the correct type, such as an arithmetic expression, a parameter that the user supplies when they run the report, an Actuate Basic function, or a method.

See also

Letting the user enter a value for a control


Letting the user enter a value for a control

To let the user enter a value for the control, include a parameter name in the value expression you assign to a control's ValueExp property. For example, the following expression includes the parameter BiggestOrder.

BiggestOrder - [order.extension]

The user who runs the report supplies a value for each parameter you use in the report design. For more information about parameters, see Designing report parameters.


Referencing controls in a value expression

When writing the value expression for a control, you can use the values of other controls in the same frame. To refer to another control, include its class name in the value expression. For example, the following expression uses the values of three controls to calculate the total amount of an order.

Subtotal - Discount + Tax

Subtotal, Discount, and Tax are the class names of controls in the same frame as the control that uses this expression. You can not refer to controls in other frames.


Computing aggregates in a value expression

If you want to summarize data for a set of data rows, use one of the seven aggregate functions in a control's value expression. These functions are also used in other kinds of expressions, such as to specify computed columns in the Query Editor. The following table summarizes the aggregate functions.

Aggregate function	Description	Examples
Max(<valueExp>)	Returns the highest value found for valueExp in the set of data rows. Max ignores rows where the valueExp is NULL.	Max([order.totalAmt])
Min(<valueExp>)	Returns the lowest value found for valueExp in the set of data rows. Min ignores rows where the valueExp is NULL.	Min([customer.limit] - [customer.balance])
Sum(<valueExp)	Returns the total of valueExp for all data rows. Sum ignores rows where the valueExp is NULL.	Sum([items.quantity] * [items.price]). Sum(1, 2, NULL)=3
Ave(<valueExp>)	Returns the average value of valueExp over all data rows. Ave ignores rows where the valueExp is NULL.	Ave([salesperson.ytd_sales]) Ave(2, 6, NULL)=4
First(<valueExp>)	Returns the value of valueExp in the first data row. First returns NULL if the value of valueExp in the first data row is NULL.	First([customer.name])
Last(<valueExp>)	Returns the value of valueExp in the last data row. Last returns NULL if the value of the valueExp in the first data row is NULL.	Last([order.shipDate])
Count( )	Returns the number of data rows. Count returns the count of rows, including rows with columns with NULL values in them. Count() is similar to the Count(*) used by some databases, which is also a row count.	Count( ). Count() can show you if you are using the Distinct clause correctly. If your data is ordered correctly, Count()Distinct() calculates correctly.

The ValueExp parameter is any valid value expression. Each aggregate function has a default value. This default value is used if no data rows are processed by the function. Max( ), Min( ), Ave( ), First( ), and Last( ) default to Null. Sum( ) and Count( ) default to 0.

See also

Comparison of running and lookahead aggregates
Specifying lookahead aggregates
Selecting specific rows to include in an aggregate
Using the Distinct clause in a value expression
How to order data for the Distinct clause
How to use the Distinct clause with two report sections
Using the Where clause in a value expression


Comparison of running and lookahead aggregates

You can compute two types of aggregates in a control's value expression. Running (or one-pass) aggregates are computed while the report is being built. Lookahead (or two-pass) aggregates are computed before the report is built.

A lookahead aggregate is useful when you want to know the total before you build the report. For example, you might want to use the total to compute a value to be displayed for each row. The syntax for a lookahead aggregate is as follows.

AggregateFunction(<valueExp>)
[Where(<Condition>) ]
{ Group By(<GroupSectionKey>) | Overall }

Unlike lookahead aggregates, running aggregates are not available for use in row-by-row computations, because the aggregate values are not known until after all rows have been processed. Running aggregates are most often used to compute values for controls in Before and After frames. The syntax for a running aggregate is as follows.

AggregateFunction(<valueExp>)
[Where(<Condition>) ]
[Distinct(<Expression>) ]


Specifying lookahead aggregates

To specify a lookahead aggregate in a value expression, add the keywords Overall or Group By after the aggregate function and its arguments, using one of the following formats.

<AggregateFunction>(<valueExp>) Overall

<AggregateFunction>(<valueExp>) Group By(<GroupSectionKey>)

When you use the Overall keyword, the lookahead aggregate is computed over all data rows in the data stream.

When you use the Group By clause, the aggregate is computed over all data rows in a particular group section. GroupSectionKey is a database column name which is the sort key (Key property setting) of a group section in the report design. For example, the following expression, set in the ValueExp property, shows the total orders for a customer.

Sum( [items.extension] ) Group By( [customers.ID] )

The following expression, set in the ValueExp property, calculates the percentage of an entire department's salary represented by one employee's salary:

[emp.salary] / Sum( [emp.salary] ) Group By ( [emp.dept] ) * 100

For more information about group sections and the Key property, see About group sections.


Selecting specific rows to include in an aggregate

Normally, an aggregate function computes its return value using all the available rows. You can also specify that you want an aggregate computed only over a specific subset of the rows. To select rows for an aggregate function, add one of the following clauses.

•	The Distinct clause is used in running aggregates only.

•	The Where clause can be used in either running or lookahead aggregates.

•	The Group By clause is used in lookahead aggregates only. For more information about the Group By clause, see Specifying lookahead aggregates.


Using the Distinct clause in a value expression

The Distinct clause in an Actuate expression operates so that a row is included in the aggregate only if the key value of that row differs from the key value of the previous row. The Distinct clause may be only used in running aggregates, not in lookahead aggregates. The Distinct clause is particularly useful for filtering out duplicate values in groups of rows.

To use Distinct to calculate the unique number of items in a column, be sure the data is already ordered by the column that appears in the Distinct clause. The easiest way to sort is to place the column in the first position of the OrderBy page of the Query Editor. For more information, see How to order data for the Distinct clause and How to use the Distinct clause with two report sections.

For example, suppose the report includes rows sorted by order number and item number. Many of the OrdNum column values will repeat row after row until the order number changes. For example, each order has several values for ItemNum, but only one associated value for the Balance.

To calculate the sum of all order balances, you need a way to exclude the duplicate values and include only one order balance for each order ID. To accomplish this, use the Distinct clause as shown in the following example.

Sum( [orders.Balance] ) Distinct( [orders.OrderNumber] )

The syntax of the Distinct clause is as follows.

<AggregateFunction>(<valueExp>) Distinct(<Expression>)

The Expression parameter is a list of one or more expressions. Each expression can include any of the following elements.

•	Reference to a data row column

•	Any Actuate Basic expression

•	Lookahead aggregate

Unlike the Group By clause, the expressions in the Distinct clause need not match any group section keys in the report. Therefore, the Distinct clause is useful for filtering rows, or counting distinct items, in reports that do not include group sections. The Distinct clause is also useful for reports that contain information that lies outside of a group section, such as that in a report created with one sequential section but two report sections.

For an example of building a report using the Distinct clause, see How to use the Distinct clause with two report sections .


How to order data for the Distinct clause

The Distinct clause with an aggregate function in a ValueExp calculates correctly when the data on which it is calculating is already in the correct order.

To work with the Distinct clause, the following process is recommended:

1	In the Query Editor, OrderBy page, place the key on which you wish to have the item sorted in the first position. For example, if you are counting a distinct number of cities, place offices.city first in the items on the OrderBy page.

2	Place other items below this one on the OrderBy page, and continue to fill out the pages of the Query Editor.

3	Examine the SQL statement that is generated by the choices you have made in the pages of the Query Editor.

In the SQL statement, the SQL statement now has, as its first item in OrderBy, offices.city.

By the time the SQL statement has executed, the data items are correctly sorted and prepared for use by the Distinct clause that then operates on the control.

For an example that uses the Distinct clause in a report, see How to use the Distinct clause with two report sections.


How to use the Distinct clause with two report sections

If the Group section key is different from the Distinct() clause key, you may need to construct a report with a Sequential section that contains two Report sections, in order to cause the Distinct() clause to correctly calculate.

In the example described below, which is one way of designing your report, the calculation takes place on items.description.

In order for the Group section not to silently readjust the SQL statement which, in turn, affects the Distinct() calculation, the Distinct() calculation must take place outside of the Group section.

After you complete all the steps shown in the example to construct the report, the Sequential section and two Report sections are visible in the Design Editor's structure and layout panes. The structure pane distinctly shows the order of items.

To create the upper report section of this report that has two report sections, do the following.

1	Drag-and-drop a Sequential Section into the topmost Content slot, which is just under the top-level AcReport component.

2	Drag-and-drop a Report section into the Content slot.

3	Be sure the Connection component is just under the Sequential section. This connection brings in your data, and you'll use the same data for both report sections in this report.

In this report, the sfdata database is used.

4	Place the DataStream and DataRow components below the first Report section.

In the Query Editor, drag and drop the orders table and the items table into the upper pane.

Be sure items.description is in the first position under the OrderBy tab. In this database, items.description is a piece of hardware that the fictional company has decided to ship. Items.description is also the column item that you will be counting for distinct occurrences. For more information on why you need to do this, see How to order data for the Distinct clause.

5	Place the group section in the Content slot. In this example, the Group section's key is OrderGroup.

6	Place the Before and Content frames, and any other frames and controls you wish below this OrderGroup.

7	In the Content slot, place a text control, with ValueExp: items.description, in the Content slot.

You have created the first portion or top half, of your report, which contains the Group section and the data.

Because you have ordered the data by placing it correctly in the OrderBy page of the Query Editor, the Distinct clause will correctly calculate the number of distinct items.

In the second portion of your report, add another Report section, Data Stream component and frames to hold the control with the Count()Distinct() value expression.

In the second portion of the report, the Count Distinct takes place. Construct the second half of the report as follows.

1	Drag a Report section and drop it on top of the Sequential Section.

The Report section positions itself correctly after the first Report section.

2	Drag and drop a Data Source component into the DataStream slot.

3	Drag and drop a DataRow component into the DataRow slot.

4	Place frames into the Content slot and After slots to contain the label and text controls for the results of the Count() Distinct() calculation.

5	In the control for the calculated item, which in this example is items.description, type the following in the ValueExp:

Count()Distinct([items.description])

The design of your report now includes the appropriate sections, frames and Value expressions.

After you build, run and view your report design, the resulting report contains the calculation on the distinct number of items in items.description.

The Distinct clause calculation takes place outside the group section, the key of which is OrderNo. Because the control containing the Distinct() clause is in the second report section, and is outside and after the group section, the calculation of the Distinct() clause correctly operates after the items are already in the correct order.

Though an item such as 32M x 4 Static Ram is repeated a number of times throughout this report, this item will only be counted once. The resulting calculation, 82, correctly calculates the number of distinct items in the set of items.description.


Using the Where clause in a value expression

The Where clause specifies that a row is included in the aggregate only if a specified condition is met. You can use this clause in running aggregates and in lookahead aggregates. The syntax of the Where clause is as follows.

<AggregateFunction>(<valueExp>) Where(<Condition>)

The Condition parameter is a Boolean expression that indicates whether a given row is included in the aggregate calculation. For example, the following expression shows the average dollar amount of sales transactions. Payments and other types of transactions are not included in the calculation.

Ave( [trans.amount] ) Where( [trans.type] = "S" )

The Where clause is also useful for making sure null values are excluded from an aggregate, as shown in the following example.

Ave( [trans.amount] ) Where( Not IsNull( [trans.amount] ) )

The Condition expression can include any valid element of a value expression, including other aggregate functions. However, when you use the Where clause with a lookahead aggregate, the Condition parameter can not include another lookahead aggregate.

For example, the following running aggregate counts the number of orders over $10,000. The Group By clause specifies a lookahead aggregate that is part of the Where clause of a running aggregate.

Count( ) Where( Sum( [items.extension] ) Group By( [orders.orderNo] ) > 10000 )

If the Count( ) function had been specified as a lookahead aggregate, this Where clause would not be valid. For more information about lookahead aggregates, see Specifying lookahead aggregates.


Formatting data in a control

You can change the display format of text or numeric data in a control by using the Format$( ) function. To format a control, type the Format$( ) function in the control's Format property.

For more information about how to use Format$( ), see Actuate Basic Language Reference.


Formatting frames and controls

A frame provides several properties that you can use to change the frame's appearance, such as BackgroundColor and Border. For a complete list of frame properties, refer to the entry for AcFrame in the Actuate Foundation Class Reference. The rest of this section describes how to accomplish some of the more common formatting tasks.

For information about how to set a property, see Setting properties of components.

See also

Moving or resizing a frame
Setting margins for a frame
Placing a shadow behind a frame
Specifying page breaks for frames
Drawing a border around a frame or control
Rounding the corners of a frame or control
Formatting the word wrap of a control
Formatting a frame or control dynamically


Moving or resizing a frame

You can use the mouse to change the size of a frame or to move the frame from place to place in the report design. There are some limits to moving or resizing a frame. If you nest a frame by placing it inside another frame, you can move the inner frame in any way you desire. The position of the outer frame, however, is determined when a user runs the report. Actuate positions the upper edge of each frame flush with the bottom of the previous frame, and the left edge at the left side of the flow. You can not directly move or resize these edges of the frame.

Make sure the frame is not wider than the flow on the page where the frame will display or print. If the frame is too wide, it will be truncated.

For more information about moving and resizing frames, see Arranging components.

Tip

To move a frame to the right or down on the page, specify external margins for the frame or resize the flow on the page layout. For more information about external margins, see Setting margins for a frame. For more information about resizing flows, see Setting page margins.


Setting margins for a frame

Use margins to specify a blank area around the outside of a frame. The following illustration shows frame margins.

To specify external margins, set the frame's Margins property. This property has four values, Top, Bottom, Left, and Right, which you can use to set margins of different widths on each edge of the frame. To specify a margin of even width all the way around the frame, make all four values equal.


Placing a shadow behind a frame

You can draw a shadow effect behind a frame and specify a color for the shadow. To specify a shadow, set the frame's Shadow property. This property has three values, Color, Height, and Width.

When you add a shadow behind a frame, you must also use a margin that is at least as large as the shadow. The shadow appears within the margin area. For more information about frame margins, see Setting margins for a frame.


Specifying page breaks for frames

You can make sure that a frame is the first or last on the page by setting the frame's PageBreakBefore or PageBreakAfter property. If PageBreakBefore is True, the frame appears at the top of a new page. If PageBreakAfter is True, a new page begins immediately after the frame. These properties affect only frames that are placed in Before, Content, or After slots.


Drawing a border around a frame or control

To outline a frame or control, you could use the rectangle control to draw a box. However, Actuate provides a variety of border styles for frames, labels, and data controls to make it easier to outline these components. The advantage of using the border instead of a rectangle is that the border changes size automatically when the control changes size.

To specify a border for a frame or control, set the component's Border property. This property has three values, Color, Pen, and Width.

Removing a border from a frame or control

To remove a border, set the Pen value under the Border property to NullLine.


Rounding the corners of a frame or control

You can give a frame or control rounded corners by using the Rounding property. You must also set the Border property to make the border visible, or rounding has no effect.

The Rounding property has two values, X and Y, which you set to numeric values to specify how round you want the corners. The higher you set X and Y, the rounder the corners.

The corner is curved around an imaginary ellipse. X specifies the horizontal distance of the frame border from the center of the ellipse. Y specifies the vertical distance.


Formatting the word wrap of a control

For all controls, you may specify how you wish the word wrap, or line breaking, to occur.

You may leave the TextPlacement-Multiline property at False, which is the default. This will cause the text, or number, or other data the control contains, to remain on just one line. The text is effectively cut off if Multiline is set to False.

If you wish to allow the text, numbers or other data in a control to wrap:

•	Set TextPlacement-Multiline to True.

•	Set the Wordwrap property to one of the following:

•	TextWordWrap, which is the default

•	TextTruncation

•	TextCharacterWrap

You may work with the TextPlacement-Horizontal alignment properties to wrap and truncate on the left, right or both left and right sides of the control, as well.


Formatting a frame or control dynamically

You may want to design a report that can print the same frame in several different styles depending on conditions when the report runs. For example, you can switch a frame's background color back and forth to print a gray background for every other row in an order.

This kind of dynamic formatting requires that you program a method using Actuate Basic to change the frame's BackgroundColor property each time a new data row comes into the frame.

For an example of alternating background color, look at the Sales Detail example report that was installed with your Developer Workbench software in the DevWb/Examples directory.

Another way to achieve flexible formatting is to create place two different frames in a conditional section. When the report runs, Actuate evaluates a condition and selects one of the frames to include in the report. For more information about conditional sections, see About conditional sections.


Working with OLE controls

Object linking and embedding (OLE) helps you link information from other graphics or word processing or spreadsheet applications to your Actuate report design. Wordpad documents, Excel spreadsheets, Paintshop Pro, and Adobe .PDF files are among those that can be placed in an Actuate report.

When you run and view the report, the application information is available to users in the form appropriate to that linked application.

You may design OLE capability into an Actuate report by:

•	Dragging and dropping a container control on the Controls toolbar into a frame in your report design, and then choosing the object you wish from the list box

•	Using the Insert→New Object menu item to choose an OLE object to insert.

To place an OLE container into a frame or layout of your design, do the following:

1	Select the OLE container from the Controls tool palette.

2	Drag and drop the OLE object into a frame in your report design.

Different OLE objects show different results. This is due to differences among applications. An image-oriented OLE object, for example, may create a 'thumbnail' or graphic approximation of the real graphic image in the report design if the size of the container doesn't match that of the image.

You may also use the menu to link an OLE object to your report design.

1	To place an image in your report design using the menu, choose Edit→Insert New Object.

2	When the dialog appears, choose the OLE object you wish to insert.

3	Place the image in your report.

.

After you run your report, the image is fully resolved in the .ROI.

Depending on whether you have the application open, the application may be activated when you click on the object in the Viewer.

For more information on working with OLE objects, see Using objects from other applications and Programming with other applications' objects in Programming with Actuate.


Presenting data in graphs

The following topics are available. To view the topics in order, use the Browse button (>>) in the Help window's toolbar.

•	About graphs

•	Types of graphs

•	About the data stream

•	About pie graphs

•	About bar graphs

•	About line and tape graphs

•	About area graphs

•	About scatter graphs

•	About HLC, OHLC and candlestick graphs

•	Showing sample data in a graph

•	Formatting the category axis in a graph

•	Formatting the value axis in a graph


About graphs

A graph is a control. But unlike a text or other type of control, which collects data from just one data row, a graph collects data from a group of data rows. Most of the graphs you create in Actuate group data into categories and series, based on the expression properties you set.

Some graphs do not, however, rely on categories and series. A scatter graph, for example, does not rely on categories and series to plot data.

The AcGraph superclass, which is the class from which all graphs derive, contains many combinations of properties that can be set. Not all graphs use all the available properties, however. For example, a pie graph doesn't use the properties available to the y-axis. A bar chart doesn't need to use pie-specific properties. A pie-specific property could be the Show Percent symbol.

Some properties require other properties to be set in order for the first properties to be effective.


Types of graphs

The following illustration shows the types of graphs you can create in an Actuate report.

Like other Actuate components, graphs in Actuate are components for which you set formats, styles and labels.

To decide which graph to use, see the following topics:

•	When to use a pie graph

•	When to use a bar, line or tape graph

•	When to use a scatter graph

•	When to use a high-low-close or candlestick graph

See also

When to use a pie graph
When to use a bar, line or tape graph
When to use a scatter graph
When to use a high-low-close or candlestick graph
The parts of a graph
How to place a graph in a report design


When to use a pie graph

If you want to display percentages and how they compare to a whole, a pie graph is the easiest to read and design. A pie graph could be used to show sales by region. The entire pie could display the total of all sales in the region. Each colored slice, which in Actuate graph terminology means each category, could represent the value in dollars for each segment within the region.

For an illustration of this example, see About pie graphs.

A pie graph is not the best choice for showing numbers over a time or value continuum. Other types of graphs, however, are especially suited to illustrating values over this type of continuum.

Once you know you want to choose a pie graph, you can choose the Actuate class to use, AcSummaryGraph, and within that class, the pie graph type. Or, you can choose AcDetail to make a pie graph. Your choice of which class to begin with depends on your data.


When to use a bar, line or tape graph

If you want to display data that may require a horizontal and vertical axis, especially over a time continuum, a bar, line or tape chart may be the best choice. A bar chart can illustrate combinations of totals for different items or groups.

Say you want to show data about how chips and boards are selling across the four regions of North, South, East and West. Each grouping of two vertical bars in a bar chart could indicate, for example, the values of "chips sold" and "boards sold." In Actuate graph terminology, the chips and boards are the series, which are illustrated in the picture called a legend.

The x-axis shows four categories, North, South, East and West. The y-axis could indicate dollar values.

A line graph and a tape graph both are useful to show a time continuum on the x-axis. Both are good to display, for example, the movement of several different mutual funds over time.

A special kind of line graph is useful to show points along the x-axis that are not distinct. A line graph could display, for example, outdoor temperatures noted in a city at different times of the day.

Once you know you want to create a bar, line or tape graph, you can choose the Actuate AcSummaryGraph class to use, and within that class, the graph type. If you want to create the more detailed line graph, choose the AcDetailGraph class to begin this line graph.


When to use a scatter graph

Choose a scatter graph if you want to show points where the x and y-axis are both numerical values, but a time continuum isn't necessary for their display. A scatter graph displaying data about science fiction movies might display points that reflect "Dollars spent on special effects" on the either the x or y-axis and "Number of times an audience says 'Wow'!" on either the x or y-axis.

If you don't care about time continuums and the values for both the x and y axis are numerical, use a scatter graph.

Once you know which type of graph you want to create, you can choose the Actuate AcDetailGraph class to use, and within that class, the GraphScatter graph type.


When to use a high-low-close or candlestick graph

The high-low-close and candlestick graphs are most useful for showing points along a relatively short and contained time continuum, such as in a business day. Stock quotes or temperature, for example, that start the day at one point, have a high point, a low point, and a final point, make good use of these types of graphs.

Once you know which type of graph you want to create, you can choose the Actuate AcHLCGraph class to use, and within that class, the graph type.

To view the various parts of a basic graph, see The parts of a graph.

For information on placing the graph in your report design, see How to place a graph in a report design.


The parts of a graph

The following illustration shows the elements of a bar graph, one of the most often-used types of graphs. Not all Actuate graphs use all of these elements. Pie graphs, for example, don't use series or properties from the y-axis. For more information about the parts that are available in a specific type of graph, refer to the topic that describes each type of graph.

Part of graph	Description
Title	The title appears above the graph. In the above illustration, the title is "Sales By Region."
Value axis, often the Y-axis	The vertical line, or "height" that indicates the data values. In area, bar, line, tape, scatter, and high-low-close graphs, the value is the Y-axis. A pie graph does not use any properties in the y-axis.
Value labels	Labels that indicate the data values. In the above illustration, the values are those on the Y-axis, such as "10,000," "20,000," and "30,000."
Value title	A value title summarizes the meaning of the values. In this illustration it is "Sales ($)."
Category axis,  often the X-axis	The horizontal line along which the categories of data are represented. In area, bar, line, tape, scatter, and high-low-close graphs, the category axis is the X-axis.
Category labels	Labels that identify each category. In the above illustration, "North," "South," "East," and "West" are examples of category labels.
Category title	A label that summarizes the categories. In the example above, "Regions" is a category title.
Legend	Like a legend on a map, the explanation of the use of color in the graph. The legend defines the series. In this example, the legend indicates which color indicates chips and which color indicates boards.
Series labels	A set of descriptive labels that identify the series of data in the graph. A series is a set of data values with one value for each category in the graph.


How to place a graph in a report design

To place a graph in a report design, follow these general steps.

1	Place a frame anywhere in your report design. Or locate the frame where you would like the graph to reside.

2	Drag-and-drop the graph component into the frame.

3	In the Select Component dialog box, select one of the three graph types, depending on the type of graph you'd like to display. These are general guidelines, and there could be exceptions.

•	AcSummaryGraph: For pie, bar, line, tape and area graphs

•	AcHLCGraph: For high-low-close, open-high-low-close, and candlestick

•	AcDetailGraph: For scatter and detailed line graphs. Sometimes for pie graphs.

For information on how to set the properties for a graph, see  Setting properties of components.

Following is a chart that shows you when to use each type of graph.

	Type of graph	Property type to choose  (in Properties-General)
	Pie	Graph2DPie  Graph3DPie
	Bar	Graph2DBar  Graph3DBar
	Line or Tape	GraphLine
	Tape	GraphTape
	Area	Graph2DArea  Graph3DArea
	High-low-close,  Open-high-low-close, Candlestick	GraphHLC  GraphOHLC  GraphCandleStick
	Scatter	GraphScatter
4	Set up the data in your data stream for the graph to display. For instructions on how to set up your data stream, see About the data stream.

5	Then, format the graph using the properties available to the type of graph you are creating.


About the data stream

The three different classes of graphs, AcSummaryGraph, AcHLCGraph and AcDetailGraph each handle the data stream, data collection and mathematical processes differently. When you choose one class of graph rather than another, you are telling the graph factory processes to gather data from the data stream and populate the graph in a certain way.

Understanding how the data streams work for each graph type helps you choose which class of graph makes sense for your application.

See also

About the data stream for an AcSummaryGraph graph
About the data stream for an AcDetailGraph graph
About the data stream for an AcHLCGraph


About the data stream for an AcSummaryGraph graph

For a graph in the AcSummaryGraph class, the following principles apply:

•	All data rows must look the same.

•	The graph processes one slot at a time.

•	If the query editor asks for it, the data stream needs to contain it.

You will need to edit the data stream using the Query Editor. When you edit your data stream, be sure to select columns in the Query Editor that correspond with the series you are displaying in the legend.

For information on editing using the Query Editor, see Query data streams.

In broad terms, for graphs in the AcSummaryGraph class, the Factory processes make two passes through the data.  The first pass gathers the data rows. Once the data rows are gathered, the internal representation of the graph is built. In the second pass, the processes find all the series. For each row, the processes create a unique list of series objects.

To create the unique series, the following occurs internally:

1	The series value is first extracted and compared to the current list of series. If that series object already exists in the list, it moves to the next.

2	The next row is considered. If the series value does not exist in the next row, a new entry is made.

3	After considering all the data rows, all of the series keys that exist in the data rows would have been found. There are no duplicate cells in the list.

Categories work in the same manner. At the end of the two passes, a matrix of categories and series is built. This matrix looks like the following diagram. This diagram shows the boundaries of the categories and series at the end of these steps. The data next goes into the cell, after each cell is initialized to zero.

After the categories and series are gathered, factory processes pass through the data. For each entry, the processes find the cell in which the key belongs. Then, the value of the point is taken and added to the value in the cell. Once all the rows have been passed through, the data set for the graph is complete.

Tip

Every category has the same set of series "slots."

Following is an example of the data allocated to the various slots.

Category key	Series key	Value
C1	S1	3
C1	S2	4
C2	S1	5
C2	S2	6
C1	S2	7
C1	S2	8
C3	S1	9
Matrix	S1	S2
C1	0+3	0+4 + 7 + 8
C2	5	0+6
C3	9	0*
This is the resulting matrix

*For cell C3S2, Category 3 had no data for the S2 series.


About the data stream for an AcDetailGraph graph

For a graph in the AcDetailGraph class, which is a detailed line or scatter graph, the processes populate the graph in the following steps:

For every row that the data stream collects, it calls the function BuildFromRow() in the graph class.  BuildFromRow gathers the X, Y and Z values from the data row as specified in the Graphs Expression properties.  In turn, the function AddPoint() is called.

AddPoint() adds this new point to the array of existing points for this instance of the graph.

The point count increments and the function returns.   A point is a structure that contains members X, Y and Z.


About the data stream for an AcHLCGraph

For a graph in the AcHLCGraph class, which is a detailed line or scatter graph, the processes populate the graph in the following way:

The high-low-close graphs collect data the same way that a detail graph does. Instead of gathering the X, Y and Z values, however, BuildFromRow gathers the open, high, low, and close values. A point is the structure that contains the open, high, low and close values.


About pie graphs

To create a pie graph,

1	Choose→Class AcSummaryGraph or ClassAcDetailGraph.

2	In Properties, choose→General →Graph Type: Graph2DPie or Graph3DPie.

A pie graph shows data values as a set of "slices" that compose the pie. The area of each slice represents the value of one category of data. Pie graphs are useful to show several values in relation to the whole. Pie graphs cannot show negative values.

The following illustration shows a pie graph with four categories, North, South, East, and West. Some of the graph features shown are optional. The values around the pie slices can be either numbers or percentages.

After you have placed the pie graph in your design, set the following properties to designate how the pie graph gathers data and how the graph will be formatted.

1	In Expressions, choose the CategoryKey to affect the category variable in the data stream.

2	In Expressions, choose the CategoryLabel. These labels appear in the legend. If this property is not set, the values returned by CategoryKey are used.

3	In Expressions, specify the ValueExp to determine the equation you wish the processes to adopt to work with the categories and series. You can use the same kind of expression as you would for a data control. The expression must evaluate to the Double data type.

The following expression graphs the total number of products sold:

Sum([items.quantity])

4	In the Legend group, specify how you want the legend to appear. Most of the properties are self-explanatory. In Legend Size, specify 100 if you wish the Legend to appear in its full, default size.

5	Set the remaining properties you wish. For a summary of properties that affect a pie graph, see "Summary of pie graph formatting properties" later in this chapter.

Note

In step 4, above, you may set a Legend-LegendPosition property other than GraphLegendLeft, GraphLegendRight, GraphLegendTop or GraphLegendBottom. You must also change the Legend-LegendSize to something other than 100, such as 20 or 40, to see movement of the Legend to these other positions.

See also

How to create an exploding pie graph
Summary of pie graph formatting properties


How to create an exploding pie graph

You may wish to extract a slice of the pie so the slice displays separately, but near the rest of the pie. This is called exploding the pie. To explode a slice,

1	Select AcDetailGraph when you choose the graph type.

2	For each slice, set the x expression to "1" or "0." Choose 1 to explode the slide, and 0 to not explode the slice.

3	For a Summary graph, override the Finish method.

4	Iterate through the graph points setting. Set the x value for each point to either 1 or 0. Set the x value to 1 to explode the slice. Set the value to 0 to not explode the slice.


Summary of pie graph formatting properties

The following table lists the properties you can set to change the format of a
2-D pie or 3-D pie graph. If a property is not listed, it is ignored by this type
of graph.

Group	Formatting properties
Data	ValueColorList: A comma-separated list of color names or RGB values to color the bars or lines. For a pie, each color corresponds to one category. For other graphs, each color corresponds to a series. If the number of series exceeds the number of colors in the list, the colors are reused starting at the beginning of the list. If this property is not set, default colors are used.
Expressions	CategoryKey  CategoryLabel  ValueExp
General	BackgroundColor BackgroundIsClear GraphBackgroundColor GraphBackgroundIsClear Graph BorderStyle  GraphStyle
Specific	LineStyle ShowAsPercent ShowLines ShowSymbols
Legend	All
Titles	All except AxisTitleFont

To show sample data in a graph, see Showing sample data in a graph.

For more details about properties, see Actuate Foundation Class Reference.

For more information about expressions in data controls, see Specifying a display value for a control.


About bar graphs

To create a bar graph,

1	Choose→Class AcSummaryGraph.

2	In Properties, choose→General →Graph Type: Graph2DBar or Graph3DBar.

A bar graph shows data values as a set of "standing" rectangular bars. The height of each bar represents the value of one category of data. In the example below, the categories are North, South, East and West.

A bar graph also shows several series of data. A series is a set of data values that includes one value for each category. In the example below, the series are chips and boards. When you include several series in a graph, the graph shows several bars in each category.

The following illustration shows a bar graph with four categories, North, South, East and West, and two series, chips and boards. Some of the graph features shown are optional.

After you have placed the bar graph in your design, do the following to designate how the bar graph gathers data and how the graph will be formatted.

1	In Expressions, choose the CategoryKey to affect the category variable in the data stream.

2	In Expressions, choose the CategoryLabel. These labels will later appear on the x-axis if the expression labels property is set. If this property is not set, the values displayed can be calculated internally. It depends on the XLabelStyle property.

3	In Expressions, choose the SeriesKey to affect the series variable in the data stream.

4	In Expressions, choose the SeriesLabel. For a bar graph, the series labels appear in the legend.

5	In Expressions, specify the ValueExp to determine the equation you wish the processes to adopt to work with the categories and series. You can use the same kind of expression as you would for a data control. The expression must evaluate to the Double data type.

The following expression graphs the total number of products sold:

Sum([items.quantity])

6	In the Legend group, specify how you want the legend to appear. Most of the properties are self-explanatory. In Legend Size, specify 100 if you wish the Legend to appear in its full, default size.

7	Set the remaining properties you wish. For a summary of properties that affect a bar graph, see Summary of bar graph formatting properties.

Note

In step 6, above, you may set a Legend-LegendPosition property other than GraphLegendLeft, GraphLegendRight, GraphLegendTop or GraphLegendBottom. You must also change the Legend-LegendSize to something other than 100, such as 20 or 40, to see movement of the Legend to these other positions.

See also

Summary of bar graph formatting properties


Summary of bar graph formatting properties

The following table lists the properties for a 2-D bar or 3-D bar graph. If a property is not listed, it is ignored by this type of graph.

Group	Formatting properties
Expressions	CategoryKey  CategoryLabel  SeriesKey  Series Label
General	All
Specific	BarGrouping. Note that GraphBarStack lets you horizontally stack bars, as lumber is stacked. BarOrientation
Legend	All
Titles	All
X-Axis	All
Y-Axis	All

To show sample data in a graph, see Showing sample data in a graph.

For information on formatting the x and y axes, see Formatting the category axis in a graph and Formatting the value axis in a graph.

For details about the listed properties, see Actuate Foundation Class Reference.


About line and tape graphs

To create a line or tape graph, do the following:

1	Choose→Class AcSummaryGraph or AcDetailGraph.

You'll choose AcDetailGraph rather than AcSummaryGraph to create a graph that shows distinct detail in the x-axis. This is explained in the steps that follow.

2	In Properties, choose General→Graph Type: GraphLine or GraphTape.

A line graph displays data values as a "dot-to-dot" sequence of points, that represent values, connected by a line. A tape graph can be thought of as a
3-dimensional version of a line graph.

The height of each point represents the values for one category of data. In the example below, the values of the category North are the two colored points above the category label "North."

A line or tape graph can show several series of data. A series is data values that include one value for each category. When you include several series in a graph, the graph shows several lines. In the example below, the series are chips and boards.

The following illustration shows a line graph developed in the AcSummaryGraph class, with four categories and two series. Some of the graph features shown are optional.

After you have placed the line or tape graph in your design, do the following to designate how the graph gathers data and how the graph will be formatted.

If you use the AcSummaryGraph to create this graph, follow these steps:

1	In Expressions, choose the CategoryKey to affect the category variable in the data stream.

2	In Expressions, choose the CategoryLabel. These labels appear on the x-axis.

3	In Expressions, choose the SeriesKey to affect the series variable in the data stream. Usually you set it to [SetVar].

4	In Expressions, choose the SeriesLabel. These labels appear in the legend.

5	In Expressions, specify the ValueExp to determine the equation you wish the processes to adopt to work with the categories and series. You can use the same kind of expression as you would for a data control. The expression must evaluate to the Double data type.

The following expression graphs the total number of products sold:

Sum([items.quantity]).

If you use AcDetailGraph to create this graph, follow these steps:

1	In the Legend group, specify how you want the legend to appear. Most of the properties are self-explanatory. In Legend Size, specify 100 if you wish the Legend to appear in its full, default size.

You may set a Legend-LegendPosition property other than GraphLegendLeft, GraphLegendRight, GraphLegendTop or GraphLegendBottom. You must also change the Legend-LegendSize to something other than 100, such as 20 or 40, to see movement of the Legend to these other positions.

2	Set the remaining properties you wish. For a summary of properties that affect a line or tape graph, see Summary of line graph formatting properties and Summary of tape graph formatting properties.

To create a line graph where the x and y values may not appear at regular intervals, see Plotting x and y values with a line graph.

See also

Plotting x and y values with a line graph
Plotting two sets of data in one graph
Summary of line graph formatting properties
Summary of tape graph formatting properties


Plotting x and y values with a line graph

You can create graphs where the x and y values may not appear at regular intervals, as in the example shown.

To use the x and y data in your line graph, do the following:

1	First, drag-and-drop a graph control into your report.

2	Choose AcDetailGraph.

Note

You can also create a line graph using the AcSummaryGraph class. In the steps shown here, however, use the AcDetailGraph class.

3	In the Properties for the graph, go to the X-Axis properties. Choose the XValueSet.

4	Change the XvalueSet from its default of GraphDefaultXvalues to GraphXValuePerPoint.

This causes the x-axis to use x and y values that are passed to it from the data stream.

The graph shown in this example is set up to use the data contained in the data stream.

5	Override the Fetch method of the Datastream component.

In this case, the x value is theRow.X. The y value is theRow.value.

Function Fetch( ) As AcDataRow

    Dim theRow As DataRow1

Set theRow = new DataRow1

CurrentRow = CurrentRow+1

Select Case CurrentRow

Case 1

theRow.Value	= 2

theRow.X = 1

Case 2

theRow.Value	= 3

theRow.X = 3

Case 3

theRow.Value	= 7

theRow.X=4

Case 4

theRow.Value	= 7

theRow.X=5

Case 5

theRow.Value	= 9

theRow.X=6

Case 6

theRow.Value	= 13

theRow.X=8

Case 7

theRow.Value	= 3

theRow.X=9

Case 8

  	theRow.Value	= 2

theRow.X=10

Case 9

        Set Fetch = nothing

        Exit Function

End Select

Set Fetch = theRow

End Function

You can also create a graph that uses two sets of data. For more information, see Plotting two sets of data in one graph.


Plotting two sets of data in one graph

You can create a graph that plots two sets of data, which shows the relationship between, for example:

•	The increasing engine liter size for the Dodge Dart and Ford Fairlane automobiles.

•	The corresponding increase in miles per hour for both cars, once an engine is installed.

To plot two sets of data in a graph, you need to set up the data stream appropriately and override the Finish method in the graph control.

To create this type of line graph, do the following.

1	Drag and drop a graph control into a frame.

2	Choose AcSummaryGraph in the dialog box.

3	In the Properties for the graph, go to the X-Axis properties.

•	Choose the XValueSet.

•	Change the XvalueSet from its default of GraphDefaultXvalues to GraphXValuePerPoint.

This causes the x-axis to use x and y values that are passed to it from the data stream.

4	In this example, the Fetch method of the Datastream component is overridden. The x value is theRow.X. The y value is theRow. value. The overridden code follows.

Function Fetch( ) As AcDataRow

    	Dim theRow As DataRow1

    	Set theRow = new DataRow1

CurrentRow = CurrentRow+1

Select Case CurrentRow

Case 1

theRow.Category = 1

theRow.Series   = "Dart"

theRow.Value	= 2

theRow.X = 1

Case 2

theRow.Category = 1

theRow.Series   = "Fairlane"

theRow.Value	= 3

theRow.X = 3

Case 3

theRow.Category = 2

theRow.Series   = "Dart"

theRow.Value	= 6

theRow.X=4

Case 4

theRow.Category = 2

theRow.Series  	= "Fairlane"

theRow.Value	= 7

theRow.X=5

Case 5

theRow.Category	 = 3

theRow.Series  	= "Dart"

theRow.Value	= 6.5

theRow.X=6

Case 6

theRow.Category	 = 3

theRow.Series  	 = "Fairlane"

theRow.Value	= 7.5

theRow.X=7

Case 7

theRow.Category	= 4

theRow.Series  	 = "Dart"

theRow.Value	= 7.0

theRow.X=8

Case 8

theRow.Category	 = 4

theRow.Series  	= "Fairlane"

theRow.Value	= 8.0

theRow.X=9

Case 9

        	Set Fetch = nothing

        	Exit Function

End Select

Set Fetch = theRow

End Function

5	In Properties of the graph component, override the Finish method as in the following code. In this code sample, if the value for the category is zero, then data does not appear. If no data appears, the point is plotted back to the previous point.

Sub Finish( )

Super::Finish( )

Dim i As Integer

Dim j As Integer

Dim last As Integer

last = 0

 	For i = 0 To DataSetCount - 1

For j = 0 to PointCount - 1

Points(i,j).X = j

'	if (Points( i, j ).Y <> 0) Then

'	Points(i,j).X = j

'	last = j

'Else

'	Points(i,j).X = last

'	last = j

'	End If

Next

Next

End Sub

For information on working with a single set of x and y values, see Plotting x and y values with a line graph.


Summary of line graph formatting properties

The following table lists the properties you can set to change the format of a line graph. If a property is not listed, it is ignored by this type of graph.

Group	Formatting properties
Expressions for an AcSummary graph	CategoryKey  CategoryLabel  SeriesKey  SeriesLabel  ValueExp
Expressions for line graph using the AcDetailGraph class	X-Axis: All  Y-Axis: All  CategoryLabel
General	All
Specific	LineStylesList  LineStyle  LineThickness  ShowLines  ShowSticks  ShowSymbols
Legend	All
Titles	All
X-Axis	All
Y-Axis	All
Data	ValuesColorList  PointLabelColor  PointLabelStyle

To show sample data in a graph, see Showing sample data in a graph.

For information on formatting the x and y axes, see Formatting the category axis in a graph and Formatting the value axis in a graph.

For details about the listed properties, see Actuate Foundation Class Reference.


Summary of tape graph formatting properties

The following table lists the properties you can set to change the format of a tape graph. If a property is not listed, it is ignored by this type of graph.

Group	Formatting properties
General	All
Data	PointLabelColor  PointLabelStyle  ValuesColorList
Legend	All
Titles	All
X-Axis	All
Y-Axis	All

To show sample data in a graph, see Showing sample data in a graph.

For information on formatting the x and y axes, see Formatting the category axis in a graph and Formatting the value axis in a graph.

For details about the listed properties, see Actuate Foundation Class Reference.


About area graphs

To create an area graph,

1	Choose→Class AcSummaryGraph.

2	In Properties, choose General→Graph Type: Graph2DArea or Graph3DArea.

An area graph shows data values as a set of high and low points connected by lines. The areas under those data values are filled in with colors. The height of each point on a line is the value that is important--the height represents the value of one category of data.

In the 2D area graph shown below, the North, South and East regions are the categories. The CPUs, boards and chips are the series.

An area graph can show several series of data. A series includes one value for each category. If you include several series in a graph, the graph can display filled areas that overlap each other.

In the illustration below, the CPUs, boards and chips are the series. Some of the graph features shown are optional.

After you have placed the area graph in your design, do the following to designate how the graph gathers data and how the graph will be formatted.

1	In Expressions, choose the CategoryKey to affect the category variable in the data stream.

2	In Expressions, choose the CategoryLabel. The labels appear in the legend on the x-axis if the Expression Labels property is set. If this property is not set, the values displayed can be internally calculated. These calculations depend on the X-axis LabelStyle property.

3	In Expressions, choose the SeriesKey to affect the series variable in the data stream.

4	In Expressions, choose the SeriesLabel. These labels appear in the legend.

5	In Expressions, specify the ValueExp to determine the equation you wish the processes to adopt to work with the categories and series. You can use the same kind of expression as you would for a data control. The expression must evaluate to the Double data type.

The following expression graphs the total number of products sold:

Sum([items.quantity])

6	In the Legend group, specify how you want the legend to appear. Most of the properties are self-explanatory. In Legend Size, specify 100 if you wish the Legend to appear in its full default size.

Note

In step 6, above, you may set a Legend-LegendPosition property other than GraphLegendLeft, GraphLegendRight, GraphLegendTop or GraphLegendBottom. You must also change the Legend-LegendSize to something other than 100, such as 20 or 40, to see movement of the Legend to these other positions.

1	Set the remaining properties you wish. For a summary of properties that affect an area graph, see Summary of area graph formatting properties.

See also

Summary of area graph formatting properties


Summary of area graph formatting properties

The following table lists the properties you can set to change the format of a
2-D area or 3-D area graph. If a property is not listed, it is ignored by this type of graph.

Group	Formatting properties
General	All
Data	ValuesColorList
Specific	ShowAsPercent
Legend	All
Titles	All
X-Axis	All
Y-Axis	All

To show sample data in a graph, see Showing sample data in a graph.

For information on formatting the x and y axes, see Formatting the category axis in a graph and Formatting the value axis in a graph.

For details about the listed properties, see Actuate Foundation Class Reference.


About scatter graphs

To create a scatter graph,

1	Choose→Class AcDetailGraph.

2	In Properties, choose→General→Graph Type: GraphScatter.

A scatter graph shows data values as scattered points. The position of each point represents the relationship between two numeric values as locations plotted along the x-axis and y-axis.

Scatter graphs and other graphs developed in the ClassAcDetailGraph class do not display a legend. The discrete points in a scatter graph do not need a legend to describe them.

In scatter graphs, unlike the graphs in the AcSummaryGraph class, the category, or x-axis, plots numeric values rather than categories. A scatter graph doesn't use series properties.

The following illustration shows a scatter graph that compares two sets of numerical data. The x-axis here shows numerical values of "top speed." The y-axis shows increasing dollar amounts. Some of the graph features shown are optional.

With a scatter graph, you don't use the Expressions - Series properties because you aren't plotting values based on an equation; you are plotting the result of the values at the intersections of the x and y-axis.

1	In Expressions, specify the ValueExp to determine the equation you wish the processes to adopt to work with the categories and series. You can use the same kind of expression as you would for a data control. The expression must evaluate to the Double data type.

2	Set the remaining properties you wish. For a summary of properties that affect a scatter graph, see Summary of scatter graph formatting properties.

See also

Summary of scatter graph formatting properties


Summary of scatter graph formatting properties

The following table lists the properties you can set to change the format of a scatter graph. If a property is not listed, it is ignored by this type of graph.

Group	Formatting properties
General	All
Specific	LineStyle ShowLines: When set to True, connects the scattered points of the graph.
Titles	All
X-Axis	All except XLabelsList
Y-Axis	All except YLabelsList

For more information about value expressions, see Specifying a display value for a control. To show sample data in a graph, see Showing sample data in a graph.

For information on formatting the x and y axes, see Formatting the category axis in a graph and Formatting the value axis in a graph.

For details about the listed properties, see Actuate Foundation Class Reference.


About HLC, OHLC and candlestick graphs

A high-low-close graph shows ranges of values. Each range is represented as a vertical line with three optional bars to mark specific values. The position of each bar represents the top of the range, or high value, the bottom of the range, or low value, and a value in the middle, or close value. High-low-close graphs are useful for showing stock prices or other data that can be represented in sets of three values.

The open-high-low-close (OHLC) graph is the same as a high-low-close graph, except that it shows one additional data value, the opening or starting value in the range.

To create a high-low-close (HLC) or an open-high-low-close (OHLC) graph,

1	Choose→Class AcHLCGraph.

2	In Properties, choose→General→Graph Type: GraphHLC or GraphOHLC.

3	Or, choose→General→Graph Type: CandleStick.

The following illustration shows a high-low-close graph. Some of the graph features shown are optional.

A candlestick graph is a variation on the high-low-close graph. Candlestick and high-low-close graphs display the type of data that can be represented in sets of four values.

The candlestick graph uses a different set of symbols to represent the values. Instead of a vertical line marked with horizontal bars, the candlestick graph consists of a series of boxes with lines extending up and down from the ends. If the open value is higher than the close value, the box is filled with a color. Otherwise, the box is filled with white.

The following illustration shows a candlestick graph. Some of the graph features shown are optional.

See also

Summary of HLC, OHLC and candlestick properties


Summary of HLC, OHLC and candlestick properties

The following table lists the properties you can set to change the format of a HLC, OHLC or candlestick graph. If a property is not listed, it is ignored by this type of graph.

Group	Formatting properties
General	All
Data	ValuesColorList
Specific	HLCBarStyle  LineStyle
Titles	All
X-Axis	All except XLabelsList
Y-Axis	All except YLabelsList

The following Expression properties may be set for an HLC, OHLC or candlestick graph.

Expression property	Description
OpenValueExp	Determines the height of the open mark (bar or edge of box)
HighValueExp	Determines the height of the high mark
LowValueExp	Determines the height of the low mark
CloseValueExp	Determines the height of the close mark
LabelExp	Determines the labels along the category axis

Set each property to an expression, such as a database column name. You can use the same kind of expression as you would for a data control. The expression must evaluate to the Double data type. For example, a graph of stock prices might use the following expressions.

OpenValue = [ prices.openPrice ]

HighValue = [ prices.highPrice ]

LowValue = [ prices.lowPrice ]

CloseValue = [ prices.closePrice ]

For more information about value expressions, see Specifying a display value for a control.

To show sample data in a graph, see Showing sample data in a graph.

For information on formatting the x and y axes, see Formatting the category axis in a graph and Formatting the value axis in a graph.

For details about the listed properties, see Actuate Foundation Class Reference.


Showing sample data in a graph

Sample data makes the graph look more realistic in the layout pane of the Design Editor. You can show sample data in any type of graph by setting the following properties in the Data group.

Property	Description
SampleMax	Upper limit of range in which to generate random sample values.
SampleMin	Lower limit of range in which to generate random sample values.
DataSetCount	Number of sample categories to show.
PointCount	Number of sample series to show in an area, bar, line, or tape graph.


Formatting the category axis in a graph

All types of graphs except pie graphs have a category axis, which is the line along which the major divisions of data are represented. This axis is also referred to as the X-axis. The following illustration shows the parts of the category axis you can format.

Use the X-Axis group of properties to format the category axis. For more information about these properties, see Actuate Foundation Class Reference.


Formatting the value axis in a graph

All types of graphs except pie graphs have a value axis, which is the line along which the data values are represented. This axis is also referred to as the Y- axis. The following illustration shows the parts of the value axis you can format.

Use the Y-Axis group of properties to format the value axis. For more information about these properties, see Actuate Foundation Class Reference.


Building HTML reports

The following topics are available. To view the topics in order, use the Browse button (>>) in the Help window's toolbar.

•	About HTML reports

•	Designing an HTML report using the wizard

•	Changing an Actuate report into an HTML report

•	Breaking up a large report for HTML

•	Using the HTML palette

•	About the HTML frame

•	About images, graphs, color and backgrounds

•	About Java applets

•	About plug-ins

•	About the HTML table of contents

•	Deploying HTML reports


About HTML reports

The Developer Workbench and its Design Editor let you create Actuate HTML reports with many options for layout, font, graphic elements, hyperlinks, and online help. A few differences exist between a standard Actuate report and the HTML report. The differences include the following:

•	Ordinarily, reports are divided into printable pages. An .ROI file has a flow, pages and page lists. You can think of an HTML report, however, as one big page through which you scroll and view information online.

•	The default style of an HTML report, containing many ordinary frames, is one big table. You may use the HTML frame and its properties to cause parts of your report to lie outside the table.

•	An HTML report ignores and does not use controls or data contained within Page Header and Page Footer frames of the Designer.

•	Ordinary Actuate reports use Microsoft Windows standard bit-mapped (.BMP) image formats. In HTML reports, you'll use .GIF images for hand-created graphics and .JPEG images for photographs. You can also insert Java applets and plug-ins.

•	Your report design options are limited by the capabilities of HTML 3.2 features, which are available with Microsoft Internet Explorer and Netscape browsers.


Designing an HTML report using the wizard

Because the Report Wizard automatically sets up a number of properties and frames that work best for an HTML report, it is easiest to start an HTML report from scratch, using the Report Wizard.

Following are the steps to follow to begin designing your HTML report:

1	Choose File→New→NewReport Wizard.

2	Work through the Report Wizard to set up your database connection, a simple query, group sections with introductory and summary frames and a page.

3	At tab 6, "Page Style, " check the box to "Create an HTML report."

The landscape choice is automatically selected.

4	When you press Finish, the beginnings of your .ROD appear in the Design Editor.

The Wizard automatically sets up the following:

The HTML report, in the AcHtmlReport class.

•	The AcReport section to have a default HTML-TableStyle property of HtmlAutomaticTable.

•	A regular frame in the Before slot for group sections. This Before frame becomes its own table and picks up the HTML table properties of the group section below it.

Note

It is wise to avoid placing data or any type of label in the Page Header, Page Footer, or PageList frames, because once a report is run and transformed into HTML, the HTML code does not contain data placed in these frames.If you wish to turn off the table qualities of this Before frame, you need to substitute an HTML frame for the regular frame. Then, set the HTML-HTMLStyle property to HTMLNotTable.

•	An HTML frame that contains the Table of Contents based on the report's group sections.

•	Other properties and methods that allow the report to appear in a Web browser.

You may then work with the design file and the HTML and other palettes to add ordinary frames or HTML frames, rules, images, applets and plug-ins as you wish.

To review the basics of building an Actuate report, see Building your first report.

5	When you are satisfied with your HTML report design, you may press the Run Report button or choose Report→Build/Run/View.

The factory processes run and the Web browser appears, displaying your HTML report.


Changing an Actuate report into an HTML report

To change an Actuate report into an HTML report, do the following:

1	In the top-level report component, which has a default name of NewReportApp, select Properties.

2	Select the Class tab.

3	Type the following in the superclass field.

AcHtmlReport

4	Press Close.

You can also save into an HTML file a report you have previously built, run and viewed.

To do this:

1	From within the .ROI, choose File→Save as HTML.

2	Name your report in the New HTML File dialog.

3	After you name your report, you may then open the HTML file from your web browser. Many browsers let you directly open such files using a File→Open menu.

As a result of changing an ordinary Actuate report into an HTML report, several components that you may have included in your original report do not appear in HTML. For a list of components that don't display in HTML, see About controls in an HTML frame.

The HTML palette lets you place items in an HTML report that you are not able to use in an ordinary Actuate report. For more information on the HTML palette, see Using the HTML palette.


Breaking up a large report for HTML

Reports greater than 10 pages in length cause the performance of any Web browser to deteriorate. Therefore, it is wise to cut a large report into smaller pieces and name each sequential piece with a meaningful name.

In the following steps, the generated .ROV files, which store parameters, let you limit the size and scope of your reports. By modifying the SQL SELECT statement and using easily understood, meaningful parameters, you can define the limits, and therefore the size, of an HTML report.

Note

In the following steps you use regular, local parameters to break up a report. You may also use ad hoc parameters to break up a report. Ad hoc parameters require a checkbox in the Conditions tab of the Query Editor. When the requester appears, type the ad hoc parameter you wish, such as a% to request items that start with A.

Here are the main steps to break up a report, using local parameters:

•	Adjust the SQL statement in the Conditions tab of the Query Editor.

•	In the Property Editor of the data stream component, create a parameter.

•	Run each report, changing a default group name. Save each .ROV.

Here are the steps:

1	First, choose a group by which you want to break up your report. A typical division would be by state or region.

2	Activate the left-hand structure pane.

3	Select the Query Editor.

4	In the Conditions tab, choose the following:

•	Under column name, choose offices.state. This allows you to break up your report by state name.

•	Under Query Expression, type

:theState

5	Next, in the Component Editor of the data stream component, next to the State, choose String from the choices in the right-hand menu. Press the Parameters button.

6	In the Parameter Attributes dialog box

•	In Type, type

String

•	In Alias, type

State

•	In Default Value, type

NY

•	Check the Required box

•	Scope is local

7	Choose OK.

Next, run the report.

1	Press the Run Report button.

2	When the Requester appears, the default will appear.

3	Type in one of your group names, such as PA to replace the default value of NY.

4	The portion of the report with PA as the state name appears in the browser window.

5	Look for the .ROV file in the file system. Each time you run the report, an .ROV is created. The .ROV file saves each set of parameters. You can run a report using the .ROV in order to define the .ROX.

6	Rename each .ROV with a meaningful name, such as SalesPA.ROV and SalesNY.ROV.

7	The generated folder for each .ROV file you create contains the HTML code you need for display and distribution.


Using the HTML palette

1	To use the HTML palette, go to the main component palette. The HTML palette contains components useful for your HTML report.

2	From the HTML palette, drag-and-drop any of the following components from the palette into your design. After you drag-and-drop them, you may further define them by working with their properties.

•	HTML frame

•	HTML rule control

•	HTML Java applet

•	HTML plug-in control

•	HTML image control

3	Build, run and view your HTML report. To do this, choose Report→Build/Run/View...

The Developer Workbench compiles an Actuate design into an executable (ROX).  The Factory processes convert the .ROX to an .ROI and to an HTML or .ROW file by querying the database and creating pages.  The Factory presents the browser with the HTML report for display.

You may wish to create a report outside of the HTML framework and later convert it to HTML. To create an ordinary report first, see  Changing an Actuate report into an HTML report.

You may optimize your designs in the following ways when you design Actuate reports.

•	You can design a report optimized for HTML that may not take advantage of the features available in an .ROI.

•	You can design a sophisticated report that is optimized for the .ROI and ignore HTML altogether.

Additional coding allows you to create both an .ROI and HTML report. For instructions on how to do this, see How to generate an .ROI and an HTML report.

See also

How to generate an .ROI and an HTML report


How to generate an .ROI and an HTML report

Ordinarily when you create an HTML report, the .ROI report is not generated. You may, however, cause the factory processes to keep the .ROI for your future needs.

Following is the code to cause an .ROI to be generated as well as your .HTML report.

1	In the left-hand Structure pane, select the topmost component. This component is usually named NewReportApp.

2	Go to the Component Editor. Choose the Methods tab.

3	Select the following method:

Function RoiIsTemporary() as Boolean

Press Override.

4	In the Method Editor, type the following code to cause the factory processes to generate an .ROI:

Function RoiIsTemporary() as Boolean

RoiIsTemporary=False

End Function

5	Press Update and Close.

6	Close the Component Editor.

7	For more information about overriding methods, see Programming with Actuate.


About the HTML frame

The main difference between an AcFrame class frame in an Actuate report and an HTML frame is that the HTML frame offers the HtmlStyle property. The HtmlStyle property lets you specify whether you want the frame to be in a table. The plain frame does not offer this property.

The table style may be defined higher in the report, in the report's topmost Content component. If the table property is set to AutomaticTable in the Content property, the table structure prevails in any group sections and HTML frames and regular frames beneath the Content component.

Choices in the HTMLStyle property of the HTML frame are

•	HtmlTable: The default. This causes the HTML frame to be placed in a table in HTML.

•	HtmlBodyText: Plain HTML body text. For more information on text, see Placing text in an HTML frame.

•	HtmlBulleted, HTMLOrdered Lists and HtmlHeading levels: These choices create a bulleted list or ordered list inside the HTML report. The heading levels are set in the Web browser you use to display your HTML report.

See also

Placing text in an HTML frame
About controls in an HTML frame
Controls that are ignored in HTML
Image controls in HTML
Aligning data inside HTML tables


Placing text in an HTML frame

If you want some of your information to lie outside of a columnar structure, you may place an HTML frame in a slot that lies outside the group structure. You may, for example, wish a small, introductory title to be located above a table of information, such as in the following example.

Note that you don't need to place a title if you have already done so by using the Wizard.

Yosemite National Park

To create such a label in an HTML frame, outside of and above a table:

1	Place an HTML frame in the Before slots, above the HTML table or HTML frames of data.

2	In the properties of the HTML frame, set the HTML-HTMLStyle property to one of the choices other than HTMLTable. The default of HTML table keeps the HTML frame inside a table.

3	In the properties of the topmost Content component, set HTML-TableStyle to HtmlNotTable. This property ensures that the frame will not be part of a table unless the HtmlStyle property is set to Automatic Table.

4	Drag-and-drop a label into the HTML frame. Set properties for the label control into the HTML frame.

Remember: A label control does not receive data from your database. Its value is derived from the Label property. A text control draws data from the database. Its value is derived from the ValueExp property.

You may wish a short message to appear between tables. The following is a simple label dropped into a frame. The Text property is set to contain the following phrase.

Place your food in the bear-proof containers!

The web browser's properties for fonts, color and size may override the corresponding properties you set in the HTML components. Be sure to check your browser's settings to see its range of colors and fonts and how they are set.

5	In your Web browser, you may set the properties for font style, color
and size.

The HTML frame's Text Alignment properties control how the controls behave inside the frame. To learn more about controls and their alignment in a frame, see About controls in an HTML frame.


About controls in an HTML frame

Controls within an HTML frame or table structure can be aligned within the cell of the .ROD and the row of the table, even if many of the HTML frame's properties have been overridden by the associated HTML table or HTML table property.

To align the controls in their rows:

1	In the properties for the control, choose Text Placement.

2	In Horizontal, choose TextAlignJustified, Left, Right or Center.

3	In Vertical, choose TextAlignTop, Bottom or Middle.

4	Press OK.

You may also specify italic, underline, or strikeout font in the properties of the control


Controls that are ignored in HTML

There are several components and controls used in ordinary Actuate reports that are ignored in HTML reports. These items are discarded when you build and run an HTML report. These discarded components and controls and their classes include:

•	Controls and frames in Page Headers and Page Footers

•	Page list (AcPageList)

•	Page (AcPage)

•	Flow (AcFlow)

•	Rectangle (AcRectangle)

•	Ellipses (AcEllipse)

•	OLE controls(AcOleControl)

•	Lines (other than horizontal) (AcLineControl)


Image controls in HTML

You may use .JPEG, .BMP or .GIF images in an HTML report. Though the Actuate client products cannot display .GIF images, a web browser can display .GIF images.

You should not, therefore develop a report containing a .GIF that is intended for viewing from Actuate clients as well as a web browser.

Actuate clients include the Actuate Viewer, Administrator Desktop, Developer Workbench, End User Desktop, LRX and Active X.


Aligning data inside HTML tables

The default arrangement for data in an HTML report is a table arrangement. Placing data inside a table lets you create HTML reports that look similar to Actuate .ROI reports.

The main rules about creating tables are

•	If the Report-Content slot near the top of the report design has the HTML-TableStyle property set to AutomaticTable, the report beneath it and all the report's group sections and frames become part of the "one big table."

•	If you don't want your report to become a table, be sure the Content-Report component properties and all group sections and HTML frames lying beneath Content-Report have their HTML TableStyle component set to something other than AutomaticTable or Create Table.

•	If the group section HTML-TableStyle property is set to AutomaticTable, all the frames and subgroups in that group section become a table.

The other HTML properties you may set in the Content-Report component include:

•	Border properties

•	Cell properties

•	Margin properties

•	Table properties.

You may also align the controls inside each cell of an HTML table. To do this,

1	Open the Properties window for the control.

2	In the Text Placement property, choose Horizontal or Vertical. From the choices given, choose how you want the control aligned inside the table cell.

3	In BackgroundStyle, choose FixedBackground.

Note that the factory processes assume that vertical gaps between groups of controls indicate a line break. If the gap is large enough, a blank line between lines of text is inserted.


About images, graphs, color and backgrounds

The best images to include in an HTML report are .GIF and .JPEG images. Graphs may be included as well as color and backgrounds. For information on including these items in your report design, see Placing images in an HTML report, Placing graphs in an HTML report, Placing color in an HTML report, and Specifying a fixed background.

See also

Placing images in an HTML report
Placing graphs in an HTML report
Placing color in an HTML report
Specifying a fixed background


Placing images in an HTML report

Different browsers are able to display different types of images. To place images in the HTML report, do the following:

1	Check to see which type of images the installed browser is able to display.

2	Convert any unusual image types to the supported image type. The .GIF and .JPEG images are generally accepted for both Netscape and Microsoft Web browsers.

3	Drag-and-drop the image component from the HTML palette. In the Component Properties dialog box that appears, next to FileName, type the file name of the image you wish to embed. Press OK.

4	In the Properties page for the image, choose Embedded and select True.

This ensures the image is copied into the report. This property set to "true" is required if the report is to be run on the server.


Placing graphs in an HTML report

A graph is rendered as a .GIF image in an HTML report. Because a graph is an image, the HTML report containing this graph occupies more disk space than a similar .ROI file containing this graph.

When you build, run and view an Actuate .ROD file that contains a graph, the HTML factory processes create a subdirectory with the same name as the .ROD file.

For example, if your design and executable files are named NATLPARKS.ROD and NATLPARKS.ROX, you generate:

•	A new subdirectory called Natlparks.

•	An image file in that subdirectory with the syntax GRAPH1.GIF.

•	A file named INDEX.HTML.

•	Files named REPORT.HTML and TOC.HTML, if you have specified in properties you want a Table of Contents in your HTML report built with HTML frames in your HTML report. For more information about building a table of contents, see About the HTML table of contents.

To learn more about placing graphs in an Actuate report, see Presenting data in graphs.


Placing color in an HTML report

To set the colors of the background of the report, do the following:

1	Set the web browser to allow the HTML report to set the colors.

2	Double-click on the topmost component (the default name is NewReportApp) to open the Properties page.

3	In BackgroundColor, choose a color other than the default, which is transparent.

Note that the colors set in your web browser are visible when the background color is set to transparent.


Specifying a fixed background

In an HTML report displayed with the Netscape Navigator, the background of a report scrolls as the contents of the report scroll.

If your web browser is Internet Explorer, you may set the background to remain in a fixed position as the contents of a report scrolls. To set the background as fixed, do the following:

1	Double-click on the topmost component (the default name is NewReportApp) to open the Properties page.

2	In BackgroundStyle, set the property to FixedBackground.


About Java applets

The java.sun.com web page offers the following definition of an applet. A Java applet is a Java program that can be included in an HTML page, much as an image can be included. When you use a Java-compatible browser to view a page that contains a Java applet, the applet's code is transferred to your system and executed by the browser.

Using a Java applet in an HTML report requires you to specify the required parameters in the HTML file.

The Java applet coding involves two types of coding:

•	HTML-specific parameters, such as the Code Base attribute, which you specify in the Actuate Property dialog box for the Java applet. The Code Base attribute is specified in the CodeBase property;

•	Applet-specific parameters that you specify in the SubHtmlParams
(htmlFile As Integer) method using Actuate Basic.

See also

Placing a Java applet in an HTML report


Placing a Java applet in an HTML report

Placing a Java applet in your HTML report requires that you accomplish the following:

•	Drag-and-drop the Java applet into an HTML frame.

•	Set two properties in the Properties dialog box for the applet.

•	Write Actuate Basic code to override the SubHtmlParams(htmlFile As Integer) method.

Do the following to place the applet in the report and set its properties. The example applet that is used here is named turn.class.

1	Drag-and-drop the Java applet component from the HTML component palette.

2	In the Size properties, set the height and width sizes.

3	In the AppletName property, specify the name of the applet, such as the following, in quotes:

"turn.class"

In most cases, the applet you wish to use resides in the directory with the .ROX. The above example assumes such a location of the applet.

If the applet you wish to use resides in another directory, specify the path name, in quotes, relative to the directory that contains the .ROX.

Following is an example of a relative path name:

"/java/turn.class"

This syntax indicates the following: Go up one directory level from where this .ROX resides. From there, go to the Java directory. Find the applet at that level.

If you are working on a local machine, write an absolute path name to locate the applet. Writing an absolute path name is more complex. The absolute path name requires syntax that uses HTML conventions, such as:

file:///c:|/actuate/java/turn/turn.class

4	In the CodeBase property, type the path name for the Java applet you wish to include. Note that the CodeBase property is somewhat HTML-version specific.

Following is an example of the CodeBase string for the turn.class applet:

../java/turn/

This string indicates the following:

To get to the applet, start at the current folder, go up one level (../); look for the subdirectory containing applets (java/); then to the subdirectory containing the files associated with this applet called turn.class (turn/).

In this example, the property looks for the applet name, given above in step 3 in quotes, named turn.class.

Once rendered in HTML, turn.class becomes the value for what is known as the Code: attribute in HTML.

Next, override a method. Overriding the method lets Actuate factory processes correctly interpret the code that is behind the applet. Some of this can be tricky; there are applet conventions that need to be translated into Actuate Basic.

1	Select the Methods tab in the Component Editor.

2	Select the following parameter:

Sub HtmlParams(htmlFile As Integer).

3	In the Method Editor, type the Actuate Basic code that yields the correct HTML code.

4	Following is an example of Actuate Basic code and the generated HTML code.

In the Method Editor:

Sub HtmlParams( htmlFile As Integer)

'Super::HtmlParams( htmlFile )

Set param( htmlFile, "speed" , "150"

Set param( htmlFile, "bgimage", "/actuate/devwb/applets/textjava.jpg")

Set param( htmlFile, "turnimage", "/actuate/devwb/applets/example.jif")

Set param( htmlFile, "xoffset", "-10")

Set param( htmlFile, "yoffset", "-15" )

Set param( htmlFile, "einzelschritte", "30")

End Sub

The generated HTML code, which you can view in the web browser, follows:

<HTML>

<TITLE>

Java Test

</TITLE>

<BODY BACKGROUND="bg.jpg">

<applet code="Turn.class" width=150 height=150>

<!param name="offsetcheck" value="true">

<param name="speed" value="150">

<param name="bgimage" value="textjava.jpg">

<!param name="bgcolor" value="000000">

<param name="turnimage" value="example.gif">

<param name="xoffset" value="-10">

<param name="yoffset" value="-15">

<param name="einzelschritte" value="30">

</applet>

</BODY>

</HTML>

5	When you are satisfied with the new, overridden method, press Update and Close.

For more information about programming in Actuate Basic, see Programming with Actuate.


About plug-ins

The Netscape Navigator web page offers the following explanation of a plug- in: Plug-ins are software programs that extend the capabilities of Netscape Navigator in a specific way. Plug-ins give you, for example, the ability to play audio samples or view video movies from within Navigator.

See also

Placing a plug-in in an HTML report


Placing a plug-in in an HTML report

To place a plug-in in your HTML report, you'll need to perform three major steps:

•	Install the extra software for plug-ins for your browser.

•	Place the plug-in in your HTML report and set its properties.

•	Override a method, using Actuate Basic, in the Method Editor.

1	First, read the information with your browser about how to install plug-in software.

2	Install the software for your plug-in. This example uses a sample movie, SAMPLE.MOV, downloaded from the QuickTime web site.

3	Drag-and-drop the plug-in component from the HTML palette into an HTML frame.

4	In Properties for the plug-in, enter values as shown in the following steps:

1	In MimeType, set to the equivalent of the HTML type attribute, found in the plug-in. Set the MimeType property if you do not set the SourceURL property.

The HTML attribute for the MimeType property is type= "opt".

2	In PlugInPage, set the property to the machine or directory from which you can download the plug-in if the plug-in is not already installed on your machine.

The HTML attribute for the PlugInPage property is pluginspage="url".

3	In Size, set the height and width of the plug-in. HTML requires a pixel measurement.

The HTML attribute for the Size property is: height=height, width=width.

4	In SourceURL, set the relative path name for the location of the plug-in file. For example, ../PlugIns/Sample.mov.

This indicates to "go up one level" from the .ROD file in the directory system, go to the PlugIns directory, and find the file Sample.mov.

If you have set the SourceURL property, as above in Substep 1, do not set the MimeType property.

5	In UseForeground Palette, leave at False if you wish the plug-in to use its palette as a background.

The HTML attribute for the UseForegroundPalette property is palette-opt.

5	In the Component Editor Methods page, select Sub HtmlParams(htmlFile As Integer) and choose Override.

6	Override the Sub HtmlParams(htmlFile As Integer) method as in the following example. This example inserts the Controls attribute and sets it to true:

Sub HtmlParams( htmlFile As Integer )

'Super::Html Params( htmlFile )

SetParam ( htmlFile, "controls", "True" )

End Sub

The generated line in the HTML code, which you can view in the web browser, follows:

<EMBED SRC="Sample.mov" WIDTH="136" HEIGHT="160" CONTROLS="TRUE">

7	Press Update and Close.

8	In the Methods page, press Close.

You can view in the web browser the generated code for the plug-in. This HTML code is

<EMBED SRC="Sample.mov" WIDTH="136" HEIGHT="160" CONTROLS="TRUE">


About the HTML table of contents

In the Report Wizard, if you specify that you are creating an HTML report, the table of contents is automatically set up for the report. The Wizard interprets the group sections in the report in order to create group levels within the table of contents.

If you choose not to use the Report Wizard to create an HTML report, you can still create a table of contents that displays in a browser.

You can build a Table of Contents to appear in a header or in a separate HTML frame:

1	Go to the top-level container for the report design.

2	In Properties, choose

•	Title: Type the title of your report.

•	TocStyle: Specify HtmlTocInHeader. This places the table of contents at the top of your report. To place a table of contents along the left side of the report, specify HtmlTocInFrame.

•	Set ShowTitle to False in the AcHTMLReport (top level) component to cause the Title to disappear. This may be useful if you have placed the Table of Contents at the top of the report.

Displaying the table of contents results in three HTML files in your output:

•	INDEX.HTML, which defines the frame set. The web browser later looks for this file to place all the report contents in the correct frame.

•	The TOC.HTML file, which is the table of contents.

•	REPORT.HTML, the HTML report.

Note that if a report has a table of contents at the top of the report, the title appears once at the top of the table of contents and at the top of the body of the report.


Deploying HTML reports

You can view the HTML report in your Web browser. When you build and run the report, the Developer Workbench activates the browser. The browser appears and displays the HTML report.

Factory processes in the Developer Workbench create a directory on your local drive. The report server creates a .ROW file in the Report Encyclopedia. For more information about the Report Encyclopedia, see Using Reports.

You can also view the report later in the browser by typing a URL such as the following:

file: <machinedrive>\<folder>\<reportname>\index.html

file: <machinedrive>\<folder>\<reportname>\TOC.html

file: <machinedrive>\<folder>\<reportname>\report.html

where:

<machinedrive> indicates the machine on which the web server is installed

<folder> is the file folder containing your HTML reports

<reportname> is the file name of the .ROD and .ROI files

index.html, TOC.html and report.html allow the web browser to find the report to display.

Your report is in the directory with INDEX.HTML.

See also

Viewing the report on an Actuate Report Server
Viewing the report on the Web


Viewing the report on an Actuate Report Server

To deploy the report on the Actuate Report Server:

1	Copy the .ROX file to the report encyclopedia.

2	Click on the file name in order to run it. You may also right-click on the context menu. Then choose New Request.

3	The Requester dialog box appears. Press OK.

4	Run the .ROX to produce an .ROW.

The .ROW contains the components for the HTML report, such as the code and the graphics. If you open the .ROW, it activates the web browser, if you do not already have the browser open.

You may also enter a URL to view your report on the Web. To do this, see Viewing the report on the Web.

For more information on navigating through and viewing reports, see Using Reports.


Viewing the report on the Web

To view reports from the Report Encyclopedia in the browser, type the following URL:

http:\\<webserver>\<acweb>\<reportserver>\<folder>\myreport.ROW

where:

<webserver> is the name of the machine on which the web server is installed

<acweb> is a keyword that points the web server to the Actuate Web agent

<reportserver> is the machine on which the report server is installed

<folder> is the folder that contains reports


  Using Reports

Using Reports describes the tasks you can perform with reports that have been designed, compiled, and generated.

Except for running reports, these tasks are common to all Actuate products. You can run reports in all products except the Viewer, which you use only with report documents that are already generated.

Using Reports  includes the following sections.

•	Working with reports in the enterprise environment. This section describes the client/server reporting environment, and explains how to work with files and folders in the Report Encyclopedia.

•	Viewing a report. This section discusses opening, viewing, and moving around in a report. It also describes how Actuate reports use links to other Windows applications.

•	Running a report. This section discusses running report executables to generate new report documents. You learn how to work with report parameters and how to use standard and ad hoc parameters. You can generate new report documents with all Actuate client products except the Actuate Viewer.

•	Searching for and exporting report data. This section describes how to search for specific data in a report and provides examples of how to use complex search criteria. It also describes how to export report data to other documents.

•	Printing and distributing a report. This section discusses printing and distributing reports.

•	Using reports on the Web. This section discusses how to access Actuate reports over the Web using your web browser.


Working with component libraries

The following topics are available. To view the topics in order, use the Browse button (>>) in the Help window's toolbar.

•	About component libraries

•	Creating a component library

•	Publishing a component

•	Including a file in a report design

•	Placing a published component in a report design

•	Modifying published components

Before reading this section, you might find it useful to read Using the Design Editor.


About component libraries

A component library is a file that contains components that can be used in one or more report designs. Component libraries provide one of the most useful ways to reuse components. The person who designs the components publishes them, or saves them, in a library file. Other users can include the library file in their designs and use its components just as they would components from the component palette.

You can use published components just as they are, or you can subclass components from the library to make minor customizations. These subclasses will inherit any future updates made to the library components. The use of inheritance with library components provides a powerful method for distributing updates to a large number of users and for enabling users to make minor changes quickly.


Creating a component library

The first step in creating a component library is to design the components you want to place in it. Use the procedures described in the rest of this book to design the components. You can put any type of component in a library, including data sources, connections, controls, frames, and entire report designs.

After you design one or more components, publish them in a library file (.ROL). If the file does not already exist, you can start a new library.

See also

How to start a new component library


How to start a new component library

When you start a new library using these steps, the library is included in the current design.

1	Open the design file (.ROD) that contains the components you want to publish.

2	From the Design Editor, choose File→New Library.

The New Library dialog box appears.

3	In File Name, type a name for the library.

4	In Directories, select the directory where you want to save the library file. Choose OK.

The Library Browser appears, showing the new library with one icon that represents the library file itself.


Publishing a component

To publish a component means to place it in a file for reuse. When you publish a component, Actuate also creates a reference from the file back to the original design. In other words, before you publish a component, its definition is saved in the design file (.ROD) where the component was built. After you publish the component, its definition is saved in the file displayed in the Library Browser. The design file contains only a reference to the component in the other file.

See also

Publishing in a library file
Publishing in a design file


Publishing in a library file

Ordinarily, the file displayed in the Library Browser is a library file (.ROL). You publish components in library files to make them available to other users. Before you publish a component in a library, be sure to test it thoroughly and design it for stability. When you use a component from a library, you should expect it to work well and change infrequently.

Publishing a query data stream

If you publish a query data stream in a library, it is best to publish the connection component with the data stream. Grouping the connection and the data stream makes it easier for others to reuse the data stream. The connection, for example, is required if you or other users want to edit the query.


Publishing in a design file

You can also publish a component in a design file (.ROD). Use this feature when you want to reuse a component without making it available for
general use.

For example, suppose you want to use an image control in many places in one design. You can publish the image component in the current design file itself by simply opening the Library Browser and selecting the current .ROD file name. The .ROD file appears in the Library Browser. Instead of making multiple copies, references, or subclasses within the Design Editor, you instead create references to or subclasses of the published component displayed in the Library Browser, as shown in the following illustration.

Using the Library Browser in this way ensures that all references or subclasses point to a single original component. It also makes it easier to find the original component when you want to make a change. For example, you might want to change one property of the image and have that change reflected throughout the design. If you had merely subclassed the image from place to place, it would be more difficult to find the image component from which all the others inherit. If you had made multiple copies, instead of subclassing, you would have to make the change in every copy, one by one.

See also

How to publish a component


How to publish a component

1	Open the design file (.ROD) that contains the component you want to publish.

2	Display the Library Browser using one of the following methods.

•	If the file in which you want to publish the component is not already included in the design, include it by following the steps in How to include a file or library in a report design.

•	If the file in which you want to publish the component is included in the design, choose View→Browse→Library and select the file name.

3	Drag the component from the Design Editor and drop it on the top level icon in the Library Browser.

The Component Drop dialog box appears.

4	Select Publish the component. Choose OK.


Including a file in a report design

Before you can use the components in a library file, you must include the file in your design. When you include a file, it is saved along with your report design, and your design can access the components in the file.

The procedure for including a library file can also be used to include design files (.RODs). However, if you include a design file, keep in mind that the components in it, unlike those in a library, were not necessarily designed for reuse. The components in a library file will probably change less frequently and be better tested than those in a design file.

See also

How to include a file or library in a report design


How to include a file or library in a report design

1	Open the design file (.ROD).

2	Select File→Include Module.

3	In File Name, select the name of the file you want to include. Choose OK.

You can include a library (.ROL) or design (.ROD) file. The Library Browser appears, showing the components in the included file.

You can also include a library in the design by default. Do the following.

1	Select View→Options.

2	Go to the Libraries tab.

3	Press Add.

4	The Locate Default Library dialog box appears. Look through the file structure and select the library you wish to add or drop.

5	Press Open to select the library. Press Add or Drop. Press OK.


Placing a published component in a report design

When you place a published component in a report design, you create a subclass or reference. For more information about subclassing and referencing, see Copying, subclassing and referencing components.

See also

How to place a published component in a report design


How to place a published component in a report design

1	Include the file in which the component is published in your report design.

For information about how to include a file, see How to include a file or library in a report design.

2	Drag-and-drop the component from the Library Browser to the Design Editor.

Actuate automatically creates a reference to the component in the library, unless the component is a control or a flow. If you drag-and-drop a control or a flow from a library, Actuate creates a subclass of the original component.

To change a referenced component to a subclass, select the component in your report design, then choose Edit→Local Subclass.


Modifying published components

The following list discusses guidelines and rules for modifying published components in your report design.

•	If a component in your report design references a component in a library, you cannot modify the component from your report design. This design feature prevents users from changing components in a library inadvertently. In the structure pane of a report design, components that reference components that reside elsewhere appear in gray.

•	You can modify a library component by opening a library view of the library, then changing the component in that view. You can also modify a component in a library if you open the library as the target design in the Design Editor.

•	If you want to modify a published component in your report design, create a local subclass of the component. To do so, select the component in your report design, then choose Edit→Local Subclass.

For more information about subclassing and referencing, see Copying, subclassing and referencing components.


Designing page layouts

The following topics are available. To view the topics in order, use the Browse button (>>) in the Help window's toolbar.

•	About pages

•	Setting up page sequences

•	About subpages

•	Placing a subpage in a report design

•	About flows

•	Specifying headers and footers

•	Designing letterheads, patterns, and other effects

•	About printing and viewing reports across platforms


About pages

A page is a component that specifies the visual design of a page in the report. A page can contain the following components:

•	Flows, which determine the printable area of the page. Each page contains at least one flow.

•	Controls (optional), which display text, numbers, images, or graphic shapes. For example, you can include controls to display a company name and logo at the top of the page and page numbers at the bottom of the page.

•	Frames (optional), which provide a way to group the controls. You can also place controls directly on the page without using a frame.

For more information about flows, see About flows. For more information about frames and controls, see Working with frames and controls.

See also

What pages do when you run a report
Types of page layouts provided by Actuate
Page orientation and printing


What pages do when you run a report

When you run a report, Actuate builds frames to display the data. As each frame is created, Actuate places it in the flow on the current page, starting from the top of the flow and aligning each frame with the left edge of the flow. If a frame is too long to fit in the current flow, Actuate places it at the top of the next flow, which may be on the same page or another page.

The sequence of events is somewhat different when your report design includes subpages. For more information about subpages, see About subpages.


Types of page layouts provided by Actuate

Actuate provides several standard page components for the most commonly used page styles. In most cases, your needs will be met by one of the standard page styles shown in the following illustration.

For information about how to add a page to your report design, see Setting up page sequences.

If none of these page styles meets your needs, you can modify a page layout using the Design Editor. For information about how to design a page layout with the Design Editor, see About flows, Specifying headers and footers, and Designing letterheads, patterns, and other effects.

You can also use a page component from a library or from another report design, or define a new page class. For information about defining a new class, see Extending the AFC architecture.


Page orientation and printing

The layout dimensions of a report determine the report's page orientation when it is printed. If the page layout of a report is longer than it is wide, for example, 11 inches long by 8.5 inches wide, the report prints in portrait mode. If the report layout is wider than it is long, for example, 11 inches wide by 8.5 inches wide, the report prints in landscape mode.

The page orientation option is maintained by the operating system and the printer driver.


Setting up page sequences

The first step in specifying the page layouts for your report is to decide whether you want to use the same layout for every page or use different layouts for different pages. Actuate provides several page list components, which you use to specify the following page layouts.

•	Simple page list--Same page layout for all pages in the report.

•	Title/body page list--One page layout for the title area of the report and another layout for the rest of the report.

•	Title page or final page on separate page--One page layout for the title page or final page and another layout for the rest of the report. This approach uses a Sequential section to accomplish a separate page within a report.

•	Left/right page list--Two alternating page layouts for odd- and even-numbered pages.

You can design a different page sequence by defining a new page list component using Actuate Basic. For information about how to define a new class, see Extending the AFC architecture.

See also

Placing a page list and pages in a report design


Placing a page list and pages in a report design

The first steps in defining the page layouts of a report are the following:

Place a page list component in the PageList slot of a report component.

Then, place one or more pages in the page list.

Thirdly, place a flow on the page.

The procedures in this section describe how to place standard page components into a page list. Pages from your component library or another design can also be placed into a page list. After you place a page, you add the flow component. Then you modify its appearance using the procedures described later in this chapter.

These procedures are based on an Actuate report built "from scratch," by choosing, from the beginning, File→New→Blank Report Design.

You may also use the New Report Wizard, by choosing File→New→New Report Wizard to construct the beginnings of a report. The Report Wizard contains a default page layout design.

See also

How to use one page layout for all pages
How to use a layout that includes a title page and a body page
How to create a title page on its own page
How to create a final, separate page
How to alternate left and right page layouts


How to use one page layout for all pages

1	Drag the page list component from the Design Editor's component palette and drop it in the PageList slot.

The Select Component dialog box appears.

2	Select AcSimplePageList. Choose OK.

3	Drag a page component from the component palette and drop it on the page list component.

4	Add a flow component to the page component. For information on flows, see Placing a flow on a page or subpage.

5	Select the TitlePage component in the structure pane. Choose View→Design. Then you may work with the flow to modify the layout of the page.


How to use a layout that includes a title page and a body page

1	Drag the page list component from the Design Editor's component palette and drop it in the PageList slot.

The Select Component dialog box appears.

2	Select AcTitleBodyPageList. Choose OK.

Two slots, TitlePage and BodyPage, appear in the structure pane.

3	Drag a page component from the component palette and drop it into the Title slot.

4	Drag and drop a Flow component, which is also on the Pages palette, into the Content slot of the Title page component. For information on flows, see Placing a flow on a page or subpage

5	Drag and drop a Page component from the component palette and drop it into the Body slot.

6	Drag and drop a Flow component into the Content slot of the Body page component. For information on flows, see Placing a flow on a page or subpage.

7	Select the TitlePage component in the structure pane. Choose View→Design. Then, work with the flow to modify the layout of the first page of your report, which includes your Title text.

For information on how to develop a layout that separates the title page from the rest of the report, see "How to create a title page on its own page".


How to create a title page on its own page

Separating the title page from the pages containing the data of the report can be done by using a Sequential Section, rather than the TitleBodyPageList.

The Sequential section contains the PageBreakAfter property that can be set to true, which forces a page break after this section.

To create a report with the title page on its own page, do the following:

1	If you have an existing report section in your report, move this to the Scratchpad, in order to create an area for the Sequential Section.

The section you move to the Scratchpad may contain the following components:

•	Content component

•	Connection component

•	DataStream component

•	Frames in Before, PageHeader, Content, PageFooter, After and Subpage

•	PageList pages

2	Drag and drop a Sequential Section into the top-level component of your report.

3	Drag and drop a frame into the Content slot.

4	In the Properties of the frame you just placed, set PageBreakAfter to True.

5	From the Controls palette, drag and drop a text control into the frame, or from the Drawing/Graphics palette, drag and drop a label or other graphic into the frame, to create the title you wish.

6	From the Scratchpad, drag and drop the report section that you earlier placed there. Place it on the Sequential Section.

The report section positions itself correctly below the Sequential Section and below the frame holding the title information.


How to create a final, separate page

To create a final, separate page for your report, see How to create a title page on its own page.

Then, do the following:

1	Select in the left hand (structure) pane the Content frame that contains the title text.

2	Select Edit→Relationship Info...

The Structure Reference List opens.

3	In the Structure Reference List, select the first item in the list box, which is the frame containing the Title text.

The Structure Reference List contains information on the relationship of components to one another. It appears when the container component can contain multiple, unordered references. It is particularly useful for moving frames to different locations within a report design. More information is available from the Help button on the dialog box.

4	Click on the down arrow, which is to the left of the list box.

This moves the first item into the second position in the list box. This selection also causes the Title frame to move into a position below that of the rest of the report.

5	Examine your report design to see how the frames have now moved.

You may now edit the frame using the Edit Layout to create a final page of your report.

To edit this frame, see Placing a flow on a page or subpage.


How to alternate left and right page layouts

1	Drag the page list component from the Design Editor's component palette and drop it in the PageList slot.

The Select Component dialog box appears.

2	Select AcLeftRightPageList. Choose OK.

Two slots, Left and Right, appear in the structure pane.

3	Drag a page component from the component palette and drop it into the Left slot.

4	Add a Flow component to the Left page component. For information on flows, see Placing a flow on a page or subpage

5	Drag a Page component from the component palette and drop it into the right slot.

6	Add a Flow component to the Right page component. For information on flows, see Placing a flow on a page or subpage.

7	Select the Left page component in the structure pane. Choose View→Design. Then, work with the flow to modify the layout of the page.

8	Select the Right page component in the structure pane. Choose View→Design. Then, work with the flow to modify the layout of the page.


About subpages

Every section in a report design can optionally have an associated subpage.  A subpage is just like a page except that it fits into a flow on the active page. The active page is the page in the report currently being generated when the subpage starts.

A subpage grows longer or shorter to accommodate the data.

You usually use a subpage when you want to change the page style for the contents of a section in the middle of page. A bank statement, for example, could be mostly printed in one column, but the list of checks appears in two columns.

Like a page, a subpage contains one or more flows and can contain frames and controls. In a parallel section, each flow in the subpage corresponds to one of the reports in the section's Reports slot. For example, you might place two subreports into a subpage with two flows. Each subreport would then use one of the flows. For more information about how to determine which flow is used, see Assigning flows to parallel subreports.


Placing a subpage in a report design

The subpage is optional. You may place a subpage component in the Subpage slot of one of the following types of sections:

•	Sequential

•	Conditional

•	Parallel

•	Report

•	Group

If you do not place a subpage in one of the sections named above, the section will use its regular page component for its design.

See also

How to place a subpage in a report design


How to place a subpage in a report design

1	Drag-and-drop a subpage component from the component palette to the Subpage slot of a section.

2	Design the layout of the subpage.

After you have placed the subpage component into the Subpage slot, you may design the layout of a subpage using the same procedures as for a regular page. For more information about designing a page layout, see the procedures later in this chapter.

Tip

You may also drag a subpage from a library or from another report design. The Subpage slot, however, only receives a subpage component.


About flows

A flow is a component that defines a printable area on a page or subpage. Each flow is a rectangular area. In its properties, you can specify a size, background color, and other visual characteristics. You use flows to determine the margins and the number of columns on a page.

The following illustration shows an approximation of how pages, flows, and frames interact.

Note that data controls, from the data streams must be placed inside a frame. Other controls, such as those with which you design a page header, can lie outside a frame and outside the flow as well.

See also

Placing a flow on a page or subpage
Setting page margins
Setting up multicolumn page layouts


Placing a flow on a page or subpage

You place a flow on a page or subpage in the same way you place any other component in the report design. You can either drag-and-drop or click and draw.

See also

How to place a flow on a page or subpage


How to place a flow on a page or subpage

1	Select the page or subpage component in the Design Editor's structure pane.

2	Choose View→Design.

A new Design Editor window opens, showing the page layout of the page or subpage component.

3	Click inside the structure pane. Right click to open the Context menu. Choose Options→Design Editor tab. Be sure the Outline Components box is checked. This will let you see the outlines of the paper edge, the flow edge, the frames and the components.

4	If necessary, use the toolbar's Zoom control to reduce the view of the page so that you can see the whole work area.

5	In the component palette, click the flow component.

6	Move the mouse pointer to the layout pane. Draw a flow in the size you want by holding down the mouse button and dragging from one corner to another.

Tip

You can also drag-and-drop the flow component from the palette to the layout or structure pane, then resize the flow if necessary.


Setting page margins

To specify the margins in a page layout, work with the height and width of the flow. The shorter and narrower the flow, the larger the margins.

See also

How to set margins on a page or subpage


How to set margins on a page or subpage

1	Select the page or subpage component in the Design Editor's structure pane.

2	Choose View→Design.

A new Design Editor window opens, showing the page layout.

3	If necessary, use the toolbar's Zoom control to reduce the view of the page so that you can see the whole area you want to work with.

4	In the layout pane, select the flow.

5	Use the handles to drag the flow edges with the mouse until the margins are the desired width.

6	To make a more specific adjustment, set the flow's Size property.

For more information about how to set a property, see Setting properties of components.


Setting up multicolumn page layouts

To design a page layout with more than one column, place more than one flow on the page. Each flow is a column.

See also

How to set up multicolumn page layouts


How to set up multicolumn page layouts

1	Select a page or subpage component in the Design Editor's structure pane.

2	Choose View→Design.

A new Design Editor window opens, showing the page layout.

3	If necessary, use the toolbar's Zoom control to reduce the view of the page so that you can see the whole area you want to work with.

4	Place the desired number of flows on the page, following the steps in How to place a flow on a page or subpage.

5	Resize the flows as needed, following the steps in How to set margins on a page or subpage.

6	Align the flows as needed, following the steps in Aligning and centering components.


Specifying headers and footers

You can specify headers and footers by placing components in two different types of locations:

•	In a component--page or subpage

•	In a slot--PageHeader or PageFooter

When you specify headers and footers by placing components in a page or subpage, the headers and footers are associated with that particular page layout. When you use the PageHeader and PageFooter slots, the headers and footers are associated with a particular set of data. Each report section and group section has its own PageHeader and PageFooter slots, so you can associate different headers and footers with each part of a report.

See also

Specifying headers and footers in a page layout
Specifying headers and footers using slots
Adding page numbers
Adding a date/time stamp


Specifying headers and footers in a page layout

Headers and footers in the layout of a page or subpage component have the following characteristics.

•	They are associated with that particular page layout.

•	They print or display on every page that uses that layout.

•	They appear outside the flow.

For example, suppose you are using a left/right page list. You can place an integer control on both the LeftPage and RightPage components to display page numbers and place an image control on the RightPage component to display a company logo on every odd-numbered page in a report.

For more information about left/right page lists, see Setting up page sequences.

See also

How to specify headers and footers in a page layout


How to specify headers and footers in a page layout

You can use frames or controls to add a header or footer to a page layout.

1	Select a page or subpage component in the Design Editor's structure pane.

2	Choose View→Design.

A new Design Editor window opens, showing the page layout.

3	If necessary, use the toolbar's Zoom control to reduce the view of the page so that you can see the whole area you want to work with.

4	Place frames or individual controls outside the flow.

If you want to place data controls from your data stream on your page, however, you must place them in a frame, but outside the flow. For more information about data controls, see About controls.

For information about how to place controls in a report design, see Placing controls in a report design.

5	Specify a value for each control.

For more information about specifying the value of a control, see Specifying a display value for a control.


Specifying headers and footers using slots

Headers and footers in the PageHeader and PageFooter slots have the following characteristics.

•	They are associated with a group of data or a report, depending on whether the slots belong to a group section or a report section.

•	They print or display along with the component that contains the slots.

•	They appear inside the flow, within a frame.

•	They can contain data controls to display data from the data stream.

For example, you can place a frame in the PageHeader slot of a group section component to display a running header as that group section displays or prints on multiple pages. If you use the PageHeader and PageFooter slots of both a group section and the report section that contains it, both sets of headers and footers will appear, as shown in the following illustration.

See also

How to specify headers and footers using slots


How to specify headers and footers using slots

1	Drag-and-drop a frame component to the PageHeader or PageFooter slot of a report section or group section.

You can drag a new frame from the component palette or use a frame from a library or from another report design.

2	Add controls to the frame and associate them with data or another type of value.

For more information about placing controls in frames and associating them with values, see Working with frames and controls.

3	To omit the header from the first page, set the report or group section's ShowHeaderOnFirst property to False. This setting is commonly used when the Before slot contains a frame that is designed for the first page.

4	To omit the footer from the last page, set the report or group section's ShowFooterOnLast property to False. This setting is commonly used when the After slot contains a frame that is designed for the last page.

For more information about how to set a property, see Setting properties of components.


Adding page numbers

Page numbers can display in text format or in number format. A page number displayed in text format lets you add words or numbers around a page number value. An example of a page number in text format follows:

Page 2-23

A page number built with a numeric format lets you do calculations on the number itself. An example of a page number in numeric format might be a page number that starts with a "3" on the first page.

To add a text or numeric page number to a report design, place a text control or number control, respectively, in either of the following locations.

•	In a frame on the PageHeader or PageFooter slot

•	Directly on a Page component

The page number will not appear if you place the control inside a frame in any component other than in the PageHeader or PageFooter. This restriction of the page number location is due to the order in which the Factory processes assign values to controls and frames.

For information on placing page numbers see How to place a page number on all pages except the first page and How to place a page number on each page.

See also

How to place a page number on all pages except the first page
How to place a page number on each page


How to place a page number on all pages except the first page

1	First, drag-and-drop a frame component into the PageFooter frame.

2	To place a page number in text format in the PageFooter frame, drag-and-drop a text control from the controls palette into the PageFooter frame.

3	In Properties, set the text control's ValueExp property to the following:

"Page 2-" + PageNo$()

Following is how this text control would appear in the .ROI.

Page 2-23

Users could interpret this page number indication as "Section 2, Page 23."


How to place a page number on each page

To place either a text or numeric page number directly on each page, outside of a page header or footer, do the following:

1	Drag-and-drop a text control or numeric control to the Structure pane, directly on a PageStyle component.

2	With PageStyle selected, from the context menu (right mouse button), choose Edit Layout.

3	In the Page Layout pane, place the control where you want it on the page.

4	In Properties, if you have placed a text control, set ValueExp property to PageNo$( ). In Properties, if you have placed a number control, set the ValueExp property to PageNo( ).

5	When the report is generated, the page number appears in the location on the page where you have placed it.

For more information about how to place a control in a report design and set the ValueExp property, see Working with frames and controls.

For more information about the PageNo method, and building more complicated page numbering systems, see Actuate Foundation Class Reference.


Adding a date/time stamp

To add the date and time to a report design, follow steps similar to those you followed in "Adding Page Numbers." In general, you place the control, then you modify the control's ValueExp property.

Following are the steps to add a date/time stamp to your report.

1	Drag-and-drop a frame component into a Page component or into the PageFooter or PageHeader slot.

2	From the context menu (right mouse button), choose Edit Layout.

3	In the Page Layout, drag-and-drop a date/time control in the frame in the layout pane.

4	To display both a date and time, in Properties, set the control's ValueExp property to Now( ). The control's Format property is already set to c, by default.

After the Factory processes complete, the Now( ) function displays the current date and time, drawn from the operating system, as a date type. The date type appears in the format of year, month, day (yy,mm,dd).

Following is an example of how the date/time control displays with the ValueExp and Format properties set as described.

11/23/97 3:01:03 P

To display only the current date, set the control's ValueExp property to Date( ). The factory processes generate only the date. No time stamp appears.

To do calculations on the date within your report, see information on the Date Serial function and other functions in Actuate Basic Language Reference.

To specify other formats for your date/time stamp, see the Format and Format$ functions in Actuate Basic Language Reference.

For more information on date types, see Variables and data types in Programming with Actuate.

For more information about how to place a control in a report design and set the ValueExp property, see Working with frames and controls.


Designing letterheads, patterns, and other effects

You can place frames or controls anywhere on a page or subpage, as well as in the header and footer areas.

Tip

If you want to associate words or graphics with a particular set of data, place frames and text or graphics controls in the PageHeader or PageFooter slots. If you want to associate words or graphics with a particular page layout, place the frames and text or graphics controls in a page or subpage.

Drawing controls enable you to draw decorative shapes in the margins. Image controls let you add a company logo and background pattern to your page layout.

See also

Placing a title or logo on a page
Adding a background pattern to a page


Placing a title or logo on a page

To place a title or logo on a page layout, follow the steps in Specifying headers and footers in a page layout.

To display a title, drag-and-drop a label control into the page or subpage.

To display a logo or other image, drag-and-drop an image control to display a logo. The Design Editor lets you specify the file name of an image.


Adding a background pattern to a page

You can place a pattern or text in the background of a page layout. A background pattern is a graphic image that lies partly or entirely inside the printable area of the page. The report prints on top of the pattern. This type of pattern is sometimes called a watermark.

See also

How to add a background pattern to a page or subpage


How to add a background pattern to a page or subpage

1	Select a PageStyle or subpage component in the Design Editor's structure pane.

2	Choose View→Design.

A new Design Editor window opens, showing the page layout.

3	If necessary, use the toolbar's Zoom control to reduce the view of the page so that you can see the whole area you want to work with.

4	Place an image control on the page so that it lies partly or entirely inside the flow.

Note: Be sure that the BackgroundColor for a frame that is positioned over the watermark is set to Transparent Color. Otherwise, the watermark may cover the frame's content.

For information about how to place controls in a report design, see Placing components in a report design.

5	Specify the pathname of the file that contains the graphic you want to use.

The image must be layered on top of the flow, or else the flow's background color will obscure the image. When you first place the image, it is layered on top by default. The image should always remain on top of the flow. You may place more frames and controls on top of the image, however. For more information about layering components, see Layering components.


About printing and viewing reports across platforms

Actuate tries to print a report that closely resembles the displayed report. Actuate also tries to minimize the differences in a report's appearance when printing and viewing in different environments.

Hardware and software differences external to Actuate cause differences between the printed and displayed reports. The hardware and software used in viewing an Actuate report is different from that used in printing it. Viewing a report on a video display uses the Windows display subsystem. The Windows system depends on the following:

•	Capabilities of the installed graphics card

•	The video driver

•	Available Windows software fonts

Printing, on the other hand, depends on the following technologies:

•	The capabilities of the printer, such as color support or resolution in dots per inch

•	Available printer-resident fonts

•	Downloadable (soft) fonts

•	The printer language, which could be PostScript or PCL

•	The printer driver

If extremely accurate printed output is required, you must design for printing in a specific printing environment. No matter how hard you try, however, there will always be a few slight differences between viewing and printing reports when you print in different hardware and software environments. For more information on viewing reports, see Using Reports. For information on working with page orientation in printing, see Page orientation and printing.

Designing to print and view reports across platforms

Following are some strategies for designing a report in the Developer Workbench to help you optimize for both viewing and printing.

•	Design for the final delivery environment. How reports display and print depends on the hardware and software involved. Because exact fidelity between printing and viewing is not possible, decide whether printing or viewing is most important and design for that output.

•	To minimize differences in a heterogeneous environment:

•	Minimize the number of fonts used and use standard fonts

•	Allow for differences in text layout and fonts on different platforms by enlarging controls containing text

•	Minimize the size and color depth of graphics

•	If you view reports online and print reports on UNIX PCL printers, minimize the use of graphs. Graphs in reports do not print in UNIX PCL printers.

•	Use scalable fonts rather than the raster version of fonts. For example, on Windows, use Courier New, not Courier, as the monospaced font.

•	Make sure the users have the proper equipment: hardware, fonts, printers with the proper capabilities, correct display and printer drivers.

•	Monitor resolution could affect how much of a report is visible onscreen. In general, a monitor set to a lower resolution is capable of displaying less of a report than a monitor set to a higher resolution. For example, if you have a report with a wide or long format set at 100%, a monitor set to 640x480 resolution can display less of the report than a monitor with a 1024x768 resolution.

Regarding printing with UNIX,

•	Use PostScript printers if you need to print graphs or images. PCL printers can only print text output.

•	The amount of space between lines on a multiline control differs depending on whether is is printed on a UNIX printer or on a Windows printer.

Regarding testing your report design,

•	Test both viewing and printing, and make sure both generate acceptable reports. Display and printing of text and graphics can exhibit significant differences on different platforms.

•	Test reports in production environments. Use the production printer for development testing, because different printers may exhibit different characteristics.

•	Test reports when you add or change printer models or printer drivers. Because vendors continually enhance products, upgrading hardware or software can change the appearance of a report.


Designing report parameters

The following topics are available. To view the topics in order, use the Browse button (>>) in the Help window's toolbar.

•	About report parameters

•	Adding a parameter to a report design

•	Referencing parameters

•	Modifying a parameter for the Requester dialog box

•	Deleting parameters


About report parameters

A parameter is a variable that passes data into a report when the report runs. A very useful aspect of parameters is that they allow you to customize the output of a report.

For example, you can create a parameter that allows the user to narrow the query at report execution. Narrowing the query lets the user work with the same report to produce many different reports.

Associated with each report is a parameter alias. This alias provides the developer with a field that displays at run time in the Requester dialog box. The prompt lets report developers provide a meaningful description of the parameters.

The Requester, which appears at run time, lets report users enter criteria, such as a date, name, or label, just before running the report. Report developers and users can define those parameters using the Component Editor and Parameter Attributes dialog boxes, except in the case of an ad hoc parameter. An ad hoc parameter is created in the Conditions page of the Query Editor.

The Parameter Attributes dialog box, which can also be used at run time, displays parameters that are on the system. Developers and users can use this dialog box to add parameters to those already existing.

Parameter groups let developers organize parameters into meaningful sets. For more information about organizing parameters, Modifying a parameter for the Requester dialog box.

Following is an illustration of a Requester dialog box. It prompts a report user for the Date Range, Password, System Parameters and User Name. In this illustration, Date Range and System Parameters are groups. They have "+" next to them to indicate prompts are grouped beneath them.

Note that all parameters appear in the Requester in alphabetical order. This alphabetical order cannot be modified.

All of the parameters in the illustration were created by the user, except those in System Parameters.

For information about how to write a parameter prompt, see Modifying a parameter for the Requester dialog box.

Some parameters do not appear in the Requester. A parameter that doesn't appear in the Requester is useful when you, the developer, want to supply a value at the time the report runs, without allowing input from users. For information about how to design a parameter that does not appear in the Requester, see Modifying a parameter for the Requester dialog box.

See also

Global and local parameters


Global and local parameters

Like other variables, parameters have scope. The scope of a parameter is the portion of the report design from which the parameter can be referenced.

When a parameter has a local scope, you can reference it only from within that scope. An example of a parameter with local scope is a local variable that sets the font color in a control. The local variable is referenced in the method code for that control.

When a parameter has a global scope, you can reference it from anywhere in the report design. You might use a global parameter when you want to drag-and-drop a certain label into a number of components throughout a report.

In sum, you can create five major types of global and local parameters:

1	Local parameters, referenced by a component.

2	Global parameters that can be referenced from anywhere in the report design, and are part of components' properties.

3	Global parameters that aren't referenced by any components, but are part of properties and are useful for programming or other reasons.

4	Parameters that are not referenced in properties.

5	Ad hoc parameters, which are local parameters, that let users change the query statement.

For information on ad hoc parameters, see Ad hoc parameters. For more information about scope, see Programming with Actuate.


Adding a parameter to a report design

In general, adding a parameter to a report design is a two-stage process, the steps of which follow. The process is slightly different for ad hoc parameters. For information on ad hoc parameters, see Ad hoc parameters

•	Define the parameter. In the Component Editor dialog box and the Parameter Editor dialog box, specify the name and characteristics of the parameter, respectively.

•	Reference the parameter. Use the parameter name in the report design where you want the value to be used.

See also

Defining parameters
Ad hoc parameters


Defining parameters

When you define a parameter, Actuate automatically declares a variable and adds it to the definition of the appropriate component in the report design. If you define an ad hoc parameter as part of a query, a variable is added to the query data source component. After you define the parameter, you can view the parameter as a variable in the Variables page of the Component Editor.

You can define parameters in several ways. Instructions follow in this chapter for these methods. The following table provides an overview.

Technique	When to use
To define a parameter: Click Component Editor→Properties tab.	When you want to define a parameter that is global or local, that supplies a component property value.
To add a local parameter that doesn't supply a property value: Click Component Editor→Variables tab.  Choose New.	To define a local parameter that may or may not be referenced in a property and can be referenced in method code. Depending on how you define the parameter in the Class Variables dialog box, this parameter may not appear in the component's properties.
To add a parameter: Choose View...Parameters. Parameter Editor→Add.	When you want to define a global parameter that is not associated with a component.
In Query Editor, specify ad hoc on Conditions page.	To define an ad hoc parameter.

See also

How to define user name and password as parameters
How to define a local parameter that is not a property


How to define user name and password as parameters

You can use parameters to supply values for many types of properties. In the example illustrated below, from MYREPORT.ROD, you'll work with the Connection component to add a user name and password, as parameters.

1	Double-click the Connection component, where you wish to create a parameter.

The Component Editor appears.

2	Choose the Properties tab.

The Properties page appears.

3	Click in the area to the right of UserName. Type your name.

4	Click in the area to the right of Password. Type a password.

If a property cannot be a parameter, the check box in the Properties dialog box is dimmed.

5	Select Parameter. The Parameter checkbox sits at the very bottom of the Component Editor page.

Because this property can be used as a parameter, the Property Parameter Info dialog box appears. If this type of property cannot be a parameter, the check box in the Properties dialog box is dimmed.

6	Name the parameter in the Property Parameter Info dialog box.

7	Choose either Local or Global to indicate the parameter scope. In the following illustration, the parameter has been given a Local scope. The parameter also requires a unique name.

8	Choose OK.

The parameter name, in this case, <ParmUserName>, appears in the Properties page.

To the right of the variable in the Properties page, the square box with three dots appears. This indicates the Parameter Attributes dialog box is now available. For more information about the Requester, see Modifying a parameter for the Requester dialog box.

You have just defined and referenced the parameter. For more information about defining and referencing, see Adding a parameter to a report design.


How to define a local parameter that is not a property

1	Double-click the component to which you want to add a parameter that is not a property.

The Component Editor appears.

2	Choose the Variables tab.

The Variables page appears.

3	To make an existing variable into a parameter:

1	Select the variable name.

2	Choose Edit.

3	Go to step 5.

4	To add a new parameter, choose New.

The Class Variable dialog box appears.

5	Fill out the dialog box as described in the following illustration.

For static parameters, which are not ad hoc parameters, you need to specify the correct Actuate data type, such as Integer, or Long, that is to be passed into processing. If you don't specify the correct data type or you don't know the data type, the type is altered to be a string.

6	Choose OK.

For more information on creating variables, see Using the Component Editor in Programming with Actuate.


Ad hoc parameters

Developers create many parameters by using a combination of the Component Editor, Parameter Attributes and Parameter Editor dialog boxes, depending on what kind of parameter is needed. A parameter with global scope can be referenced in more than one component. A parameter with local scope can be referenced by just one component.

A parameter can be referenced in the Properties page of the Component Editor. Then, the Requester dialog box lets users set values at run time. The Requester dialog box and the Parameter Editor let you add parameters at run time.

The ad hoc parameter is a specific type of parameter. First, it is always a local parameter. An ad hoc parameter enables report users to redefine the report's SQL statement. In the Requester dialog box, the ad hoc parameter accepts a conditional expression. This conditional expression operates on the Where clause of the query.

Developers create an ad hoc parameter in the Conditions page of the Query Editor. The ad hoc parameter then appears in the Requester dialog box, along with other parameters already defined.

After you create an ad hoc parameter, the Where clause in the SQL statement changes. The change in the Where clause then adjusts the fields in the Requester dialog box. When the user clicks OK in the Requester and runs the report, the adjusted Where clause goes to work.

You can define and reference ad hoc parameters only in reports that use a query data stream. The illustration shown below and in How to define an ad hoc parameter show ordinary and ad hoc parameters in a query.

For information about how to define and reference an ad hoc parameter, see How to define an ad hoc parameter.

See also

How to define an ad hoc parameter


How to define an ad hoc parameter

1	Choose View→Query.

2	The Query Editor appears.

3	In the Query Editor, select the Conditions tab.

4	Click under Column Name and select a column name from the drop-down list box.

5	Check the Ad-Hoc box.

Once you click the Ad-Hoc box, you cannot enter an expression or constant in the Query Expression column.

From this point forward, the column name you specified in the Query Editor appears in the Requester dialog box, unless you delete it.

To configure how the ad hoc parameter appears in the Requester dialog box, use the Parameter Attributes and Parameter Editor dialog boxes.

At run time, in the Requester dialog box, the user may leave the Query Expression blank or type an expression to refine the Where clause of the Query Expression.

With Actuate's Query by Example (QBE) syntax, the user creates an ad hoc parameter that Actuate translates into SQL. QBE syntax builds expressions for single values, relational expressions, a range of values and a combination of all of these.

Note

Once you identify a column name in the Conditions tab of the Query Editor as an ad hoc parameter, its Actuate data type becomes a String when processing begins, by default.

For a complete explanation of QBE syntax, see Query by Example (QBE) syntax.

Note that the column name you defined on the Conditions page is also the name of an ad hoc parameter. In the Query Editor you have, therefore, defined and referenced the parameter.

For information about referencing parameters, such as in the Query Editor, see Referencing parameters.


Referencing parameters

You can reference parameter names as part of any expression or value in a report design. You can use parameter names in the following ways:

•	As part of a query, as in an ad hoc parameter.

•	To set the value of a property, as in a component or components.

•	In method code.

See also

How to reference a parameter


How to reference a parameter

To reference a parameter, use its name in any expression or value within the scope of the parameter in your report design. You can refer to global parameters from any part of the report design.

In some cases, Actuate automatically references a parameter when you create and define it. This occurs when you define an ad hoc parameter or use a parameter to set the value of a property.

When you reference a parameter in the Query Editor, type a colon ( : ) before the parameter name. For example, :State.To view the parameters in your report design,

1	Choose View→Browse→Globals or Project.

2	Right mouse click to bring up the context menu and choose Settings. Be sure Variables is checked.

The Globals and Project views allow you to see which parameters are global and which are local, based on the layout in each view.

See also

How to display a parameter value in a report


How to display a parameter value in a report

To display a parameter value in a report,

1	In your report design, create a control of the appropriate type.

2	Set the control's ValueExp property to <component>::<parameter>, where <component> is the name of the component on which the parameter is defined and <parameter> is the name of the parameter. In your report, the control displays the parameter value entered in the Requester dialog box.

For example, you would create a date/time control to display a date. If the name of the component on which the parameter is defined is DataSource and the name of the parameter is StartDate, you would set the control's ValueExp property to DataSource::StartDate. If you enter 8/1/98 for the parameter StartDate in the Requester dialog box, the date/time control you created displays the value 8/1/98 in your report.


Modifying a parameter for the Requester dialog box

1	Click the component for which you want to modify a parameter.

In the Properties page of the Component Editor, click the three-dot button, to the right of the parameter name that you have already defined.

The Parameter Attributes dialog box appears.

This dialog box enables you to construct the attributes of the parameter. These attributes are then reflected in the Requester dialog box.

The Parameter Attributes dialog box lets you provide a value through code, rather than a value that appears in the Requester.

2	Fill out the dialog box as described in the following text and illustration. The illustration follows this description.

•	Parameter Name is the name of your parameter. In the example, we want to assign a global parameter to the font color property.

•	Select the Actuate Basic type of data. This data can be integer, string, or one of several other data types. For a complete list of data types, see
Actuate basic, data types in Actuate Basic Language Reference.

•	Alias is the prompt that a user will see in the Requester dialog box when the report starts to build and run. Assigning an alias is optional.

•	Group indicates the group in which a specific parameter might belong. Assigning a group is optional.

•	Default Value is the value that appears with the variable if you choose nothing else. Assigning a default value is optional.

•	You can also specify how you want to display the parameter in the Requester by checking the appropriate boxes.

•	"Required" indicates there must be a value entered before the request can continue.

•	"Hidden" indicates the parameter is not displayed in the Requester. It can be accessed through the API.

•	"Hide Text" indicates the text a user types in the Requester will be hidden. A password that a user types can be hidden this way.

•	Finally, determine if the parameter is to be local or global by checking the appropriate box.

•	Choose OK.


Deleting parameters

To delete a parameter, you can reverse the procedure with which you defined it. For example, if you defined the parameter through the Properties page, you can return to that page to delete the parameter.

See also

How to delete a parameter using the Parameter Editor


How to delete a parameter using the Parameter Editor

If you added a parameter to your set of parameters by only using the Parameter Editor dialog box, the parameter is global, but not attached to or referenced by any component. To delete this kind of parameter, do the following:

1	Choose View→Parameters.

The Parameter Editor appears.

2	Select the parameter you want to delete.

3	Choose Delete.

See also

How to delete a local or global parameter that supplies a property value
How to delete a parameter not referenced in properties
How to delete an ad hoc parameter


How to delete a local or global parameter that supplies a property value

1	Double-click the component.

The Component Editor appears.

2	Choose the Properties tab.

The Properties page appears.

3	Click the parameter name in the area to the right of the property.

4	Deselect Parameter in the checkbox.


How to delete a parameter not referenced in properties

1	Double-click the component.

The Component Editor appears.

2	Choose the Variables tab.

The Variables page appears.

3	Select the parameter you want to delete.

In the Variables page, you cannot delete a parameter that is referenced by or that sets a property value. To delete a parameter that supplies a property value, see How to delete a local or global parameter that supplies a property value.

4	Choose Delete.


How to delete an ad hoc parameter

1	Choose View→Query.

The Query Editor appears.

2	In the Query Editor, select the Conditions tab.

3	Select the ad hoc parameter you want to delete.

4	Press Shift + Delete.

The ad hoc parameter is removed from the page and deleted.


Working with sections

The following topics are available. To view the topics in order, use the Browse button (>>) in the Help window's toolbar.

•	About sections

•	About report sections

•	About group sections

•	About sequential sections

•	About conditional sections

•	About parallel sections


About sections

A section is a component that determines the logical structure of the report. When you design a report, sections act as containers for other components. When you run the report, sections receive the incoming data rows and determine which components to instantiate to create the appropriate output.

Sections appear only as icons in the structure pane of the Design Editor. When you look at the report design in the layout pane of the Design Editor or run the report and view it, you don't see the sections themselves. The only visible sign of a section's existence is the effect it has on the organization of the visual components, such as frames and controls.

See also

Types of sections


Types of sections

The following table summarizes the five types of sections. Each type of section is described in more detail later in this chapter.

Section	Description	Example of use
Report section	Retrieves information from a data source and contains components to display that information	Design a report or subreport
Group section	Sorts data on a common field, such as customers grouped by state, and contains components to display the data group	Design a grouped report to print orders for customers in various states
Sequential section	Contains several frames or sections that display or print in a specified order	Print two related reports, such as a sales history and a staffing history, one after the other
Conditional section	Uses a conditional expression to determine which of two frames or sections to display or print	Print different frame for salaried or commission employees
Parallel section	Contains two or more report sections which are displayed or printed simultaneously in different flows on the same page	Present two related reports, such as employee addresses and salary histories, printed side by side for easy comparison


About report sections

A report section is the main component in a report design. A report section initiates and maintains the data stream to retrieve information from a data source. A report section also contains components to display the retrieved information.

See also

Combining report sections in a report design
Placing a report section in a report design
Placing components in a report section
Sharing connections between report sections


Combining report sections in a report design

Your report design can contain a single report section or many report sections. Each report section has its own data stream. The term subreport is sometimes used to indicate that a particular report section is only one of several in a report design.

You can combine report sections in a number of different ways, as summarized in the following list.

•	Nested reports

•	Sequential reports

•	Conditional reports

•	Parallel reports

See also

Nested reports
Sequential reports
Conditional reports
Parallel reports


Nested reports

You can use a report section to read rows from a database, perhaps a company-wide database of customers. For each row from the first report, you can use another report section to read rows from another database, perhaps a file that contains your notes for each customer. This second report is a nested report. You build a nested report by placing a report section in the Content slot of another report section.


Sequential reports

You can print several reports in sequence. The second report begins after the first one finishes, and so on. You build a sequential report by placing several report sections in a sequential section. For more information about sequential sections, see  About sequential sections.


Conditional reports

You can choose which of two report sections is actually instantiated depending on conditions when the user runs the report. For example, you can make a decision based on parameters entered by the user. You build a conditional report by placing two report sections in a conditional section. For more information about conditional sections, see About conditional sections.


Parallel reports

You can print two or more reports side by side. For example, you can print the job history for an employee on the left side of a page and print a salary history report on the right side of the page. You build a parallel report by placing several report sections in a parallel section. For more information about parallel sections, see About sequential sections.


Placing a report section in a report design

To place a report section in a report design, drag-and-drop the report section icon from the component palette to the Content slot of another section, the Reports slot of a parallel section, the Then or Else slot of a conditional section, or the Content slot of the report component.

You can also use a prebuilt report section from a library or from another report design.

For more information about slots, see About slots.


Placing components in a report section

A report section can contain the following components.

•	Connection in the Connection slot

•	Data stream in the DataStream slot

•	Frame in the Before, After, PageHeader, or PageFooter slot

•	Frame or section in the Content slot

•	Subpage in the Subpage slot

If you do not use a subpage, the report section will use the current page component.


Sharing connections between report sections

Each report section normally has its own connection component. However, if you place multiple report sections in a report design, you may choose to have them share a connection to increase performance. Most databases incur considerable overhead when you open or close a connection. Some vendors limit the number of connections you can have open at the same time.

If you do not place a connection component in a report section, and that report section requires a connection, Actuate searches upward through the report structure to look for a connection when the user runs the report.

For example, suppose your report includes two report sections, which you want to print one after the other. You use a sequential section to hold the two report sections. Rather than placing a connection component in each report section, you can place the connection component in the sequential section so that both report sections can use it.


About group sections

A group section is a component that groups data on a common field and contains components to display that data. For example, you can use a group section to group customer data by state. If your report uses a query data stream, the grouping keys in group sections are also used as sort keys to sort the data. Use a group section to accomplish the following tasks.

•	Build a grouped report

•	Sort data in a report with a query data stream

•	Accumulate and display totals or other summary data for a group of data

•	Associate headers and footers with a group of data

See also

What is a grouped report?
Placing a group section in a report design
Specifying a group key for a group section
Sorting data with group sections
Placing components in a group section
What group sections do when you run a report


What is a grouped report?

A common type of report is a grouped report, in which data is sorted and displayed according to one or more common data values. All the data that shares one common value is grouped together. For example, you can display orders grouped by customer. The customers, in turn, might be grouped by geographic region.

A grouped report presents data in an organized way that is more meaningful to the reader than simply listing the data. A grouped report also provides a way to avoid repeating information. For example, you would only need to print the customer's name and address once, at the beginning of the group of orders for that customer, rather than including customer name with every order.

For example, consider the following set of rows. Each row represents an item in a sales order. The rows are sorted according to order number. The set of rows that contain all the items for one order is called one order group. The order groups, in turn, are sorted according to customer number. The set of rows that contain all the orders for one customer is called one customer group.

The column that contains a value on which rows are sorted is called a sort key column. Each group section in your report design corresponds to one sort key column.


Placing a group section in a report design

Placing a group section in another group section is called nesting group sections. The outermost group section is placed in the Content slot of a report section. The following illustration shows nested group sections.

To place a group section in a report design, drag-and-drop the group section icon from the component palette to the Content slot of a report section or group section in the Design Editor.

You can also use a prebuilt group section from a library or from another report design.


Specifying a group key for a group section

After placing a group section component in a report design, you specify which data corresponds to that section. Each group section corresponds to a sort key column, which is one of the columns returned by the data stream.

To set the key for a group section, set the section's Key property to the appropriate column name. For example, the following illustration shows the Key property in the Properties page for the CustomerGroup section.

If you are not using the query data source component provided by Actuate, you must make sure the sort key in the data stream matches the keys in the group sections. If you are using the Actuate query data source component, Actuate automatically modifies the sort key in the query to match the group sections.


Sorting data with group sections

If you are using the query data source component provided by Actuate, you can use group sections to sort data. When you place or modify a group section, Actuate records the column name you assign to the group section's Key property. When you run the report, Actuate automatically modifies the Order By clause of the query to match the keys in the group sections.

You can specify whether the sorting for each key is done in ascending or descending order. Type Asc or Desc after the sort key name in the group section's Key property. Ascending order is the default. The following illustration shows how to sort customers in descending order.

As you place group sections one inside the other, you create a nested group structure that specifies the sort order of the data. The innermost group section often contains a frame to print the most detailed level of data. If you want to sort the data in that frame, add one final sort key column to the query using the Query Editor. For more information about how to edit the sort key, see  Sorting data with the Query Editor.

The following illustration shows a typical structure of nested group sections and the corresponding Order By clause in the query. The first two sort keys are added by Actuate to match the keys in the group sections. The third entry, items.itemcode, is added using the Query Editor.


Placing components in a group section

A group section provides seven slots in which you can place components for the section to use in various ways. Each slot is optional.

A group section can contain the following components.

•	Connection component in the Connection slot.

•	Frame in the PageHeader, Before, Content, After, or PageFooter slot. A Graph component can then be inserted within the new Frame in any of these slots.

•	Report, Sequential, Parallel, or Conditional in the Before, Content, or After Slot.

•	Subpage component in the Subpage Slot.

•	Another Group section in the Content slot.

The following illustration shows which types of components you can place in each slot.

For more information about slots, see About slots.

See also

Summary of group section slots


Summary of group section slots

The following table summarizes how you use each of the slots in a group section.

Slot	Contains	Location	Example of use
Connection	Connection	Not applicable (the component does not appear in the report)	Separate database connection for this section
Before	Frame	Before the group	Column headings such as Name and Phone for a customer group
PageHeader	Frame	Top of each page as the group continues	Running header that repeats the column headings to keep readers oriented
Content	Frame or section	Between Before and After. Content is where the group's data prints.	Customer names and phone numbers
PageFooter	Frame	Bottom of each page of the group	Page numbers or text: "To be continued"
After	Frame	After the group	Total number of customers in the group
Subpage	Subpage, Frame	After the page footer	A second, "subdesign" within the report

The following illustration shows the sequence in which components from these slots display or print. The pages shown are for a grouped report with a subpage section.


What group sections do when you run a report

Remember that a group section corresponds to one column from the sort key. Each time the section receives a data row, the group section determines whether the value of the sort key has changed. The change in the value of the sort key indicates the end of one group of data and the start of the next group. The group section instantiates each of the components it contains in sequence. Some components, such as the Before frame, are instantiated only once each time the value of the sort key changes.

The following illustration shows the sequence of events for a simple group section that processes a series of data rows containing orders sorted by customer number and order number.

1	The customer group section receives a data row.

2	The frame in the customer group's Before slot is printed if the row contains a new customer number.

3	The OrderGroup section in the Content slot prints the order. Keep in mind that the OrderGroup section contains its own components and prints them for each group of order data (the items in one order). The order group keeps track of both its own sort key (the order number) and that of the customer group section. If either key changes (or if both do), the order group section begins a new data group. This is the essence of how nested group sections work.

4	The frame in the customer group's After slot is printed if the data row contains a new customer number.

This process repeats for each order returned by the data stream. The following illustration shows the report that results.


About sequential sections

A sequential section is a component that contains several frames or sections that display or print in a specified order. For example, you might use a sequential section to create a report that prints a company's sales history followed by its staffing history. Use a sequential section to accomplish the following tasks.

•	Include several reports to display or print data from several queries

•	Include several reports with the same query to print different reports based on the same data

See also

Placing a sequential section in a report design
Placing components in a sequential section
Specifying the print order in a sequential section
What sequential sections do when you run a report


Placing a sequential section in a report design

To place a sequential section in a report design, drag-and-drop the sequential section icon from the structure palette to another section's Content slot in the Design Editor.

You can also use a prebuilt sequential section from a library or from another report design.

The following illustration shows a typical report structure using a sequential section. The section prints three reports, one after the other.


Placing components in a sequential section

A sequential section provides three slots, the Connection slot, the Content slot and the Subpage slot. A sequential section can contain the following components.

•	One or more frames or sections in the Content slot

•	One optional subpage in the Subpage slot

The following illustration shows which types of components you can place in the Content slot.

The components you place in the Content slot do not all have to be the same type. If you do not place a subpage in the Subpage slot, the sequential section will use the current page component.

For more information about slots, see About slots.


Specifying the print order in a sequential section

By default, the components in a sequential section are printed in the order in which you placed them in the section. You can change the default order and so change the order in which they are displayed in the .ROI file, and the order in which they are printed.

See also

How to specify the printing order in a sequential section


How to specify the printing order in a sequential section

A simple way to change the printing order or the display order in the generated .ROI file is to swap the positions of the components in the structure pane of the Design Editor, using the Scratch Pad. For information on the Scratch Pad, see About the Scratch Pad.

You can also use the following steps to specify an order number for each component.

1	In the structure pane, position the mouse pointer on the Sequential section component. If there are several components nested at a level within Sequential section, position the mouse pointer on the Content component within that next section.

2	Press the right mouse button.

The component's context menu appears.

3	Choose Relationship Info.

If the Sequential section resided alone at its level, the Single Structure Reference dialog box appears.

If you selected Relationship Info for the inner-level Content component, the Structure Reference List appears.

In the Structure Reference list, select the name of the component you want to reorder and use the up or down arrow buttons to move the component up or down in the list.

The following illustration is from the FORECAST.ROD file, contained in the Developer Workbench examples, which reside in the directory with your Developer Workbench.


What sequential sections do when you run a report

The following illustration shows the sequence of events for a simple sequential section.

1	The report section that contains the sequential section can pass data along to the sequential section. Any frames that are contained in the sequential section can receive this data. In the previous illustration, the TitlePage frame receives data from the outer report.

2	Each component in the section prints its output. In this illustration, the TitlePage frame is printed first, then each report section is printed. Each report section can contain its own data stream and print data from a different query.

The following illustration shows the report that results.


About conditional sections

A conditional section is a component that uses a conditional expression to determine which of two frames or sections to display or print. Use a conditional section to accomplish the following tasks.

•	The user who runs the report may enter parameters to choose which content to print

•	The user may choose between two subreports to display data from different queries

•	The user may choose between frames depending on data in the data row

See also

Placing a conditional section in a report design
Specifying the condition for a conditional section
Placing components in a conditional section
What conditional sections do when you run a report


Placing a conditional section in a report design

To place a conditional section in a report design, drag-and-drop the conditional section icon from the component palette to another section's Content slot in the Design Editor.

You can also use a prebuilt conditional section from a library or from another report design.

The following illustration shows a typical report structure using a conditional section. The Orders section prints orders in two different styles, depending on the total order amount.


Specifying the condition for a conditional section

After placing a conditional section component in a report design, you specify its conditional expression. When a user runs the report, Actuate evaluates this expression to determine what to print for that section. Depending on where you placed the conditional section, the expression can refer to parameters, global variables, or data row columns.

Rule

You can use column names in the conditional expression only if the conditional section is in the Content slot of a report section or group section.

To specify the conditional expression, set the section's IfExp property to a Boolean expression that returns True or False. If the expression in IfExp is True, the component in the Then slot is used. If the expression is False, the component in the Else slot is used.


Placing components in a conditional section

A conditional section provides four slots, the Connection, Then, Else, and Subpage slots. A conditional section can contain the following components.

•	A connection component in the connection slot. This component is optional.

•	A frame or section in the Then and Else slots.

•	A subpage in the Subpage slot, which is optional.

The following illustration shows which types of components you can place in the Then or Else slot.

You can only place a connection component in the Connection slot. The components you place in the Then or Else slots do not, however, have to be the same type. If you do not place a subpage in the Subpage slot, the conditional section will use the current page component.

For more information about slots, see About slots.


What conditional sections do when you run a report

Each time the section's content is to be printed, Actuate evaluates the conditional expression and chooses the appropriate component to generate the output. The following illustration shows how an Employees group section could be implemented using a conditional section to print alternative frames for salaried and commissioned employees. The data rows contain information about employees and departments, sorted by employee name within each department.

1	The Department group section receives a data row.

2	The frame in the Department group's Before slot is printed if the data row contains a new department name, such as Operations.

3	The Employee group section prints information about the employee. The conditional expression is evaluated, and depending on the result, one of the frames is printed.

This process repeats for each employee. The following illustration shows the report that results.

For more information about group sections, see About group sections.


About parallel sections

A parallel section is a component that contains two or more subreports that are displayed or printed simultaneously in different flows on the same page. Use a parallel section to present different reports side by side.

See also

Placing a parallel section in a report design
Placing components in a parallel section
Assigning flows to parallel subreports
What parallel sections do when you run a report


Placing a parallel section in a report design

You can place a parallel section component in the Content slot of any type of section. To place a parallel section in a report design, drag and drop the parallel section icon from the component palette to another section's Content slot in the Design Editor.

You can also use a prebuilt parallel section from a library or from another report design.


Placing components in a parallel section

A parallel section provides three slots, the Connection slot, the Reports slot and the Subpage slot. A parallel section can contain the following components.

•	A connection component in the Connection slot

•	One or more report sections in the Reports slot

•	One subpage in the Subpage slot (optional)

The following illustration shows a typical parallel section.

If you do not place a subpage in the Subpage slot, the parallel section will use the current page component.


Assigning flows to parallel subreports

The subpage or page component used by a parallel section must have enough flows to print all of the subreports. For example, if you place three subreports in a parallel section, the subpage or page must contain three flows. You specify the flow in which a report appears by assigning the flow name to the report.

If the parallel section contains a subpage component, the section will use the flows on that subpage. Otherwise, the parallel section will use the flows on the current page component. Remember that a report design can contain several page components. For example, the design might include different page components for the even-numbered and odd-numbered pages.

For more information about pages and subpages, see Designing page layouts.

See also

How to specify flows for parallel subreports


How to specify flows for parallel subreports

1	Double-click a report section in the parallel section.

2	In the FlowName property, type the name of the flow in which the report is to appear.

The name is the class name you assigned to the flow.

3	Repeat steps 1 and 2 to assign flows to all the report sections in the parallel section.


What parallel sections do when you run a report

The following illustration shows a typical set of components in a parallel section, the flow layout in the subpage, and the output that results when you run the report. The information that appears in each report depends on how you designed each subreport.


Terminology Map

If you are familiar with another reporting tool, the words you use to refer to reporting concepts may be different from the words used in Actuate documentation. To help you make the transition, this section lists some important terms from the world of reporting and gives the equivalent Actuate terminology.

Reporting term	Actuate term
attribute	property
break group	group
break report	grouped report
calculated field	calculated control
criteria	parameters
detail section	detail frame or innermost frame
field	column or control
formula	expression
group field	calculated control
group level	group
groups/totals report	grouped report
layout painter	Design Editor
level break listing	grouped report
link	join
link field	key
matrix report	crosstab report
N-up report	multi-column page layout
property sheet	Properties tab in Component Editor
region	frame
repeating frame	detail frame or innermost frame
report painter	Design Editor
select painter	Query Editor
selection formula	parameter
setting	property


Using the Design Editor

The following topics are available. To view the topics in order, use the Browse button (>>) in the Help window's toolbar.

•	Placing components in a report design

•	Copying, subclassing and referencing components

•	Arranging components

•	Setting properties of components

•	Removing components from a report design

•	Managing multiple Design Editor windows


Placing components in a report design

To place a component in a report design, drag-and-drop from a component palette, a library, the Project Browser, the Globals Browser, the Scratch Pad, or the Field List into the structure pane or layout pane of the Design Editor.

You can also draw a component in the layout pane. This method gives you more control over the size and shape of the component. For more information about how to draw a component, see Using the mouse to draw components in the layout pane.

For more information about dragging and dropping into the structure or layout pane, see Placing components in the structure pane and Placing components in the layout pane. For more information about using the Field List, see Placing data controls in a frame.

See also

Sources from which you can drag components
How placing components determines their use
About slots
Placing components in the structure pane
Placing components in the layout pane


Sources from which you can drag components

The Developer Workbench provides six sources from which you can
drag-and-drop components, as summarized in the following table.

Component source	Available components
Component palettes	All components that correspond to Actuate Foundation Classes.
Project View	Components in all library (.ROL) and design (.ROD) files included in the report design, listed by file.
Globals View	Components in all files included in the report design, listed alphabetically.
Library View	Reusable components that have been published in library files.
Field List	Column names in the data row retrieved by the data stream for the currently selected frame. The Field List is the only source from which you can place more than one component at a time.
Scratch Pad	Components you previously placed in the Scratch Pad for temporary storage.

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

Component source	More information
Component palettes	The component palettes
Project Browser	About the Design Editor's helper tools
Globals Browser	About the Design Editor's helper tools
Library Browser	Working with component libraries
Scratch Pad	About the Scratch Pad


How placing components determines their use

When you place a component in your report design, the location where you place the component determines how it is used.

•	When you drop a component in a particular slot in the structure pane or layout pane, the name of the slot determines the use. For more information about slots, see About slots.

•	When you drop a component on another component's icon in the structure pane, Actuate assigns a default use to the component. If Actuate cannot determine the most logical use for a component, a dialog box appears in which you choose a location and use for the component.

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

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

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


About slots

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

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

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

See also

Slots for Visual Components
How to display slots


Slots for Visual Components

Each slot is labeled with a name that indicates how the component dropped in that slot is used. For example, the report section component has a Before slot. When you drop a frame in that slot, it is printed or displayed at the beginning of the report.

The following table describes the six slots that contain visual components. This table doesn't include the Connection slot, where the database connection lies. The Connection slot is further discussed in Placing components in a report section.

Slot name	Description
Before	Text or data that appears at the beginning of a report or section, such as column headings. A component in the Before slot can also present summary data.
PageHeader	Text or data that appears at the top of every page (except the first) on which a component is printed or displayed. To display the PageHeader component on the first page as well, set the report's ShowHeaderFirst property to True.  The component in this slot is often a continuation version of the component in the Before slot. For example, a page header could display a customer name at the top of every page of a multi-page customer group.
Content	Text or data that appears for every data row processed by the component, such as a frame for every item in a customer order. Some components can use more than one component in the Content slot. For example, you can place several text and data controls in the Content slot of a frame.
PageFooter	Text or data, such as page numbers, that appear at the bottom of every page, except the last, on which a component is printed or displayed. To display the PageFooter component on the last page as well, set the report's ShowFooterLast property to True.
After	Text or data that appears at the end of a report or section, such as summary data.
Subpage	A page layout that is specific to one section of the report and defines the layout of just that section. For example, you can place a parallel section inside a subpage in order to produce a two-column section.

For details about how these six slots relate to each other in a grouped report, see  Summary of group section slots.

There are other slots, such as the PageList slot, that you will work with less often. A report section component, for example, has a PageList slot for the component that defines the set of page layouts in the report.

All the slots are described in later chapters, where their corresponding tasks are documented in detail. The Connections slot is further illustrated in Placing components in a report section.The PageList slot is described inPlacing a page list and pages in a report design.


How to display slots

You can display or hide slots in the panes of the Design Editor.

1	Position the mouse pointer in the background of the structure pane or layout pane.

2	Press the right mouse button.

The context menu appears.

3	Choose Show Empty Slots.

You can also

1	Choose View→Options.

2	In the Design Editor tab, check and uncheck Show Empty Slots.

3	Choose OK.


Placing components in the structure pane

When you want to add components to a frame, you might prefer to place them in the structure pane rather than the layout pane. The advantage of using the structure pane is that it provides a compact view of the report design. It shows a logical view of all components used in the design. The layout pane, in contrast, shows only visual components such as frames and controls.

The structure pane also provides a clear picture of the relationships between the components. The layout pane provides relational information in the captions above each frame, but you might prefer the more graphic, "what you see is what you get (WYSIWYG)" presentation in the structure pane.

You can place components in the structure pane in two ways:

•	Place components in slots

•	Place components on icons

See also

Placing components in slots in the structure pane
Placing components on icons in the structure pane


Placing components in slots in the structure pane

If slots are displayed, place a component in the appropriate slot. For example, to nest a group section in another group section, use the Content slot as shown in the following illustration.

For more information about slots, see About slots.


Placing components on icons in the structure pane

In addition to using slots, you can also place components directly on component icons in the structure pane. Reasons why you might use this technique include the following.

•	The structure pane is not currently configured to display slots.

•	A component's contents and slots are not currently displayed. A plus icon appears next to the component.

•	You simply prefer using icons rather than slots.

For example, to add a frame to a group section, drag-and-drop the frame component on the group section icon in the structure pane.

The Use As dialog box appears, in which you specify how you want the frame to be used in the section. The choices listed in this dialog box are the same as the names of the slots. Move the highlight in the Use As dialog box to the name of the slot you want to use and choose OK.


Placing components in the layout pane

When you want to add components to a frame, you might prefer to place them in the layout pane rather than the structure pane. The advantage of using the layout pane is that you can work with the location and appearance of the components.

For example, in the layout pane you can move, resize, and align components. For more information about working with components in the layout pane, see Arranging components.

You can place components in the layout pane in three ways:

•	Drag-and-drop components into slots.

•	Drag-and-drop components into frames. Using this method, you can control the position and size of the component as you place it.

•	Draw components using the mouse. Using this method, you can control the size and position of the component as you place it.

See also

Placing components in slots in the layout pane
Placing components in frames in the layout pane
Using the mouse to draw components in the layout pane
How to draw components in the layout pane


Placing components in slots in the layout pane

You can use slots in the layout pane just as you can in the structure pane. The following illustration shows how the Design Editor looks when slots are displayed in the two panes of a simple report design.

Keep in mind that these are two views of the same slots, not two different sets of slots.

The following illustration shows the same report design after a frame is placed in the group section's Content slot. The frame appears as an icon in the structure pane, and as a rectangular area in the layout pane. Keep in mind that these are two views of the same frame, not two different frames.


Placing components in frames in the layout pane

When you place a frame in your report design, an empty rectangular area appears in the layout pane. You can drag-and-drop components directly into this rectangular area.

When you drag-and-drop a component, you are actually subclassing the component. For more information about subclassing, see Subclassing components in the Design Editor.

The previous illustration shows how to drag a component from the component palette. You can also use components from several other sources, including the Field List, as described in Sources from which you can drag components. The Field List is the easiest way to place several controls to display data from the data stream. For details about how to use the Field List, see  Placing data controls in a frame.


Using the mouse to draw components in the layout pane

Instead of dragging and dropping to place a component in your report design, you can click and draw in the layout pane. This method works for any component that you can place in a frame, such as a text control, rectangle, or nested frame.

For example, suppose you want to add a rectangle. When you simply drag-and-drop a rectangle component in the structure or layout pane, a rectangle with a default size appears, as shown in the following illustration.

If the default size and location do not meet your needs, you can move and resize the rectangle. However, you might prefer to use the mouse to draw a component with the size and location you want.


How to draw components in the layout pane

1	In the component palette, choose the component you want to use.

To draw several components without having to click the button each time, single-click the palette button. The button remains depressed.

2	Release the mouse button.

3	Move the mouse pointer to the layout pane and draw a rectangle of the size you want by holding down the mouse button and dragging from one corner to another.

This rectangle shows the boundaries of the component you are adding, not its actual shape.

4	Release the mouse button.

The component appears in the layout pane within the area you outlined. In the illustration immediately above, the grid lines have been turned off.


Copying, subclassing and referencing components

When you drag-and-drop components in the Design Editor or its helper windows, you are either moving the component or creating a copy, subclass or reference. Moving acomponent simply changes its location in the report design, and is not a form of reuse. Copying, subclassing and referencing are the three ways to reuse components in Actuate. The following table summarizes these operations.

Operation	Description	When and how to use
Copy	Duplicate a component.	To locally change some characteristics of the original component.  When you create a copy of a component, changes to the original do not affect the new component.  A lower-level component, such as a control within a frame of a library, can be copied into a report design and altered in its new location.
Subclass	Derive a component from another component.	To locally change some characteristics of the original component. The new component inherits from the original.  Future changes to the original will be reflected in the new component. When you drag-and-drop a frame or a control from a palette, you are actually subclassing that frame or control.
Reference	Refer to a component rather than creating a new component.	To use the original component exactly as it was created, no matter how the original changes in the future.  When a top-level component, such as a frame, is referenced from a library, in a report design, that component cannot be altered within the design.  It can, however, be altered in the library, and then dragged and dropped (referenced) again.

The Developer Workbench provides default behavior that makes sure the most logical operation is performed each time you drag-and-drop. When Actuate cannot determine the most logical operation, a dialog box appears so that you can choose the operation you want.

The mouse cursor changes to indicate whether you are moving, copying, subclassing, or referencing.

For more information on copying components, see Copying components.

For more information on subclassing components, see Subclassing components in the Design Editor.

For more information on referencing components, seeReferencing components.

See also

Copying components
Subclassing components in the Design Editor
Subclassing a report design
Referencing components


Copying components

You can copy a component, such as a frame, from one part of a report design to another. You may wish to copy a control from one frame to another. Or, you may wish to copy a component from the Library Browser to the Scratch Pad.

To copy a component, see How to copy a component.

A component and a copy of the component are useful when:

•	You have created one component and you want to work with that component as a basis, or template, for creating a new component.

•	You wish to resume work on the original component and not affect the second, new component.

The new component inherits from the same class that the original inherits from. That is, the original and copy are both at the same level in the class hierarchy.

For more information about inheritance, see  About inheritance.

When you make a copy, all the property settings are also copied. When you copy a component that contains other components, the contained components are copied as well as the lower-level components in that internal frame.

If you copy a frame, for example, the controls it contains are copied. You may then work with each version of the frame separately, to create the combination of components you wish.

A copied frame within a frame, however, operates slightly differently.

•	A frame within a frame, and any controls within that internal frame, are shared by the original larger frame and the copied larger frame.

•	A frame and any labels or controls within a frame do not go along when the larger, higher-level frame is copied into the Scratch Pad.

Because labels and controls in a frame within the copied frame are shared, the changes you make to a label within a frame within the copied frame are made in both places.

See also

How to copy a component


How to copy a component

To copy a component, Ctrl + drag the component you wish to copy to the location where you want to place the copy .


Subclassing components in the Design Editor

Subclassing means creating a new component that inherits characteristics from the original component. Make a subclass when you want to locally change some characteristics of the original component and use inheritance to obtain other characteristics. The inherited characteristics will reflect future changes to the original component.

When you locally change, or override, characteristics in the new subclass, the component stops inheriting those characteristics from the original component. For example, if you set a new background color for the subclass, it will stop using the inherited color. Now the background color of the subclass will not change when you modify the original component.

The most common example of subclassing is when you drag-and-drop a component from the component palette to the Design Editor. You are creating a subclass of the Actuate Foundation Class that is represented on the component palette.

For more information on subclassing and inheritance, see About Actuate's object-oriented design.

See also

How to subclass in the Design Editor
How to subclass a connection component in the Design Editor


How to subclass in the Design Editor

Drag-and-drop the component from the source into your report design.

If subclassing is the only logical operation for the source and destination, the new component appears in the Design Editor. Otherwise, a dialog box appears, prompting you to create a reference to or a subclass of the source component.

The following table summarizes the cases in which subclassing is the default operation for a simple drag-and-drop.

Component source	Component destination
Component palette	Any destination
Field List	Design Editor
Control or flow in a library	Design Editor


How to subclass a connection component in the Design Editor

A developer may wish to subclass a connection component to give users, at run time, choices of databases to which they can connect. This process involves a few steps.

1	In a library, create all possible connections from which a user can choose.

2	Override the correct method of the report section to instantiate the correct connection, which is based on a parameter.

In the example that follows, a Sybase and Oracle connection class are defined.

Override the NewConnection() method of the report section to instantiate the proper connection, according to the parameter.

Function NewConnection( ) As AcConnection

Select Case MyConnParam

Case "Oracle"

Set NewConnection = New Persistent MyOracleConnection

...

End Select

End Function

For more information on overriding methods, see Programming with Actuate


Subclassing a report design

Subclassing a report design provides a powerful method for reusing components and distributing updates. If a report already exists that is close to what you want, you can subclass the entire design, then make minor changes.

Future updates to the original report will be inherited by your report, except for updates to the parts you have changed in the subclass. For example, if the company logo is redesigned in the master report, all reports that are subclassed from the master report will inherit the change automatically, except those that include a local change to that portion of the report.

Subclassing a design gives you more of a head start on your design than using a component library, building the report from palette components in the Design Editor, or using the New Report Wizard.

See also

How to subclass a report design


How to subclass a report design

1	Choose File→New.

2	Select Subclass a Design. Choose OK.

The Open Base Report Design dialog box appears.

3	Select the name of the report design file you want to subclass. Choose OK.

The New Report Design dialog box appears.

4	Type a new name for your report design, or accept the default name. Choose OK.

The Design Editor appears, showing the subclassed design. The original design file (.ROD) is an included module in the new design.

5	To see the included module, choose View→Browse→Project. Choose the Includes folder.


Referencing components

Referencing means to refer to an existing component rather than create a new component. If you wish to minimize the amount of time spent on updating components, it is easiest to create a boilerplate, or template component, publish it in a library, and reference it elsewhere in the Design Editor.

You use a reference when an existing component meets your needs and you want to use it as it exists, no matter how it changes in the future.

The most common example of referencing is when you use a component from a library. A company logo is an example of a common use of a component that is often referenced. The library designer creates the component and publishes it in a library. Then, many people can refer to the component. They cannot, however, change its properties inside a report design.

See also

How to reference an existing component


How to reference an existing component

Drag-and-drop the component from the source into your report design.

If the source is a library, Actuate creates a reference to the component in the library, unless the component is a control or a flow. When you drag-and-drop a control or a flow from a library, Actuate creates a subclass of the original component.

In some cases, Actuate cannot determine the best default operation, and it must prompt you for a choice. The following table summarizes these cases. The term top level in the table indicates the level shown in the illustration.

Component source	Component destination
Globals Browser, Project Browser, or top level of Library Browser	Design Editor, Scratch Pad (below top level), or Library Browser (below top level)


Arranging components

Once you have placed components in the report design, you can rearrange them. This section gives detailed instructions for arranging components in the following ways.

•	Selecting components

•	Moving components

•	Sizing components

•	Aligning and centering components

•	Layering components

See also

Selecting components
Moving components
Sizing components
Aligning and centering components
Layering components


Selecting components

Selecting means choosing one or more items to be affected by the next command you perform. When you select a component in the structure pane, the same component is selected in the layout pane, and the layout pane scrolls, if necessary, to display the component. When you place a component in a report design, the component is automatically selected.

See also

How to select a component
How to select multiple components
How to deselect a component


How to select a component

1	Position the mouse cursor on the component.

2	Click once.


How to select multiple components

You can select multiple components only in the layout pane, not the structure pane.

Method 1: Using the rubberband

1	Choose Rubberband in the main component palette.

2	Move the mouse pointer to the layout pane and draw a rectangle around the components you want by holding down the mouse button and dragging from one corner of the rectangle to another.

All the components inside the rubberband are selected. Components that are only partially inside the rubberband are not selected.

Method 2: Using the Shift key

1	Choose Single Selection in the main component palette.

2	Position the mouse cursor on the first component and click once.

3	Position the mouse cursor on another component and Shift-click.

4	Repeat step 3 to select additional components.


How to deselect a component

•	To deselect one component, position the mouse pointer on it and Ctrl+click.

•	To deselect all the currently selected components, click the background of the layout pane.


Moving components

Moving a component can mean either of the following operations, depending on the source and destination of the component.

•	Change the display location of the component

•	Change the location of the component in the design

To change the display location of a component, move it from one part of the layout pane to another. For example, you can move a control to the right in a frame. For information about how to move the display positions of components in relation to one another, see Aligning and centering components.

To change the location of a component in the design, move it from one place to another in the structure pane or layout pane. For example, you can move a control from one frame to another. The display appearance of the control is not changed, but its place in the design is changed.

Note

You can move a second-level component, such as a control, from a library into a structure view. When you work with a top-level component such as a frame, from a library, however, the component is referenced. You can see that the top-level component is referenced, rather than moved or copied, because the properties in the top-level components are greyed. The referenced top-level component cannot be changed within the report design.

The Scratch Pad is useful for moving components from one part of a report design to another. For more information about the Scratch Pad, see About the Scratch Pad.

See also

How to move a component using the mouse
How to move a component using the arrow keys
How to move multiple components
About the Scratch Pad
How to use the Scratch Pad


How to move a component using the mouse

Drag-and-drop the component to a new location. If the mouse pointer changes appearance while you are dragging, start again and hold down Shift while you drag-and-drop.

The changed mouse pointer indicates that Actuate is performing a copy, reference, or subclass instead of a move. For more information about the mouse pointers, see Copying, subclassing and referencing components.


How to move a component using the arrow keys

You can move components using the arrow keys only in the layout pane, not the structure pane. You can move a component within a frame, but you cannot move it from one frame to another using this method.

1	Select the component you want to move.

2	Press the left, right, up, or down arrow key.

The component moves by one square as defined by the snap to grid. If the snap to grid is not enabled, the component moves by one pixel. For more information about the snap to grid, see Using grids in the layout pane.


How to move multiple components

You can move multiple components only in the layout pane, not the structure pane.

1	Select the components using the steps in How to select multiple components.

2	Position the mouse cursor on one of the selected components.

3	Press the left mouse button and drag the components to the new location.


About the Scratch Pad

The Scratch Pad is a helper window that you use along with the Design Editor. The Scratch Pad temporarily stores components while you are working on a report design. Use the Scratch Pad to help you move components from one part of a report design to another, or let components rest in the Scratch Pad as you move them between the Design Editor and its helper windows.

For example, in the following illustration, all the slots are full. If you want to place a new frame in the Before slot, you can delete the frame from that slot. However, you might not want to throw away the work you did to create that frame. By moving the frame to the Scratch Pad, you create room for a new frame in the Before slot and save the old frame in case you want to use it again later.


How to use the Scratch Pad

1	Choose View→Scratch Pad.

The Scratch Pad appears.

2	Drag-and-drop a component to the folder icon in the Scratch Pad.


Sizing components

When you place a frame or control in a report by dragging and dropping, Actuate gives it a default size. You can also use the mouse to size a component at the same time you place it in the report. In either case, you can easily change the size later.

You can only resize components in the layout pane, not the structure pane, because many of the components that appear in the structure pane, such as group sections, have no physical size.

See also

How to resize a component


How to resize a component

1	Select the component in the layout pane.

2	Use the handles to drag the component edges with the mouse until the component is the desired size.

3	To specify an exact size, set the component's Size property.

For more information about how to set a property, see Setting properties of components.


Aligning and centering components

You can align components in several ways.

•	Align components in relation to each other using their right, left, top, or bottom edges, or their vertical or horizontal centers.

•	Center components in relation to the frame.

•	Use the snap to grid option to automatically align components as you drop them in the layout pane. For more information about grids, see  Using grids in the layout pane.

See also

How to align components with each other
How to center components in a frame
Using grids in the layout pane
How to enable the snap to grid and visible grid


How to align components with each other

1	Select the components in the layout pane using the steps in How to select multiple components.

2	Choose Edit→Align.

A cascading menu appears.

3	Choose one of the following commands.

The components align to the last component you selected.


How to center components in a frame

1	Select the component or components you want to center.

2	Choose Edit→Center.

A cascading menu appears.

3	Choose one of the following commands.


Using grids in the layout pane

The layout pane of the Design Editor provides two different grids to help you align components, the snap to grid and the visible grid.

The snap to grid is a matrix of invisible horizontal and vertical lines that aligns components automatically. When you place a component in the layout pane, the Design Editor adjusts the position of the component so that the upper left corner is on the nearest gridline intersection.

The visible grid is a matrix of horizontal and vertical lines that are displayed in the background of the layout pane. These lines need not be the same distance apart as those in the snap to grid. The visible grid has no effect on where you can place components. It is simply a visual cue that helps you arrange components.


How to enable the snap to grid and visible grid

1	In the layout pane, press the right mouse button.

The context menu appears.

2	Choose Editor Settings.

The Options dialog box appears with the Editor Page open.

3	Select Snap To Grid, Display Gridlines, or both.

4	(Optional) Specify a new size for each square in the grid by typing values in Horizontal and Vertical.

You can specify a different size for each grid.


Layering components

When you add a component to a frame, Actuate places it on top of the other components. If the component is filled, it obscures the components in back of it. You can control the "Z-order, or how objects overlap, by moving them forward and backward in relation to each other.

See also

How to change the layering depth of a component


How to change the layering depth of a component

1	In the layout pane, select the component you want to bring forward or send backward.

2	Choose Edit→Layers.

A cascading menu appears.

3	Choose one of the following commands.

•	To move the component one step closer to the top of the stack, choose Move Forward.

•	To stop other components from overlapping the selected component, choose Move to Front.

•	To move the component one step towards the bottom of the stack, choose Send Backward.

•	To let all other components overlap the selected component, choose Send to Back.


Setting properties of components

Properties are characteristics of a component for which you can specify a default value. A property controls the appearance or behavior of an object, such as the font size for a label control or the server name for a database connection.

You use the Properties page of the Component Editor to work with properties. Many of the properties in the Properties page have default values listed in gray. These are inherited properties. If you change these values, you can always go back to the inherited values by using the Default button. For more information about inherited properties, see About inheritance.

Example

You can use the SampleData property to make the layout pane look more similar to how the report will appear after it is run. Set a value for the SampleData property of each data control. For example, use the value "XYZ Corporation" for the control that will display company names.

See also

How to set a property


How to set a property

1	Double-click a component in the structure or layout pane of the Design Editor.

The Component Editor appears.

2	Choose the Properties tab.

The Properties page appears, showing the properties of the selected component.

3	Click in the field to the right of the property name.

4	Specify a new value using one of the following techniques.

•	Type a value in the field.

•	If the field changes to a drop-down list box when you click it, choose a value from the list.

•	If the Builder button appears when you click in the field, choose the button to display the tool you can use to construct a value. The tool displayed depends on which property you are modifying.

5	Choose Apply.

6	To delete changes and revert to the inherited value, choose Default.


Removing components from a report design

You can remove any component from a report design except the ReportApp component.

When you remove a component from a report design, remember that it may contain other components which will also be removed. For example, if you delete a frame, all the components contained in that frame are also deleted.

Some of the components that appear in the structure and layout panes are only references to other components. When you delete a reference, the original component and its contents are not deleted. You do not lose any work if you delete a reference. However, if you delete the original component, it is removed from the report design and you might lose some work. For more information about component references, see Referencing components.

If you want to temporarily remove a component from the design but save it in a place to use it a few minutes later in your design session, move it to the Scratch Pad. You can also, of course, publish it to a library.

For more information about the Scratch Pad, see About the Scratch Pad.

See also

How to remove a component from a report design


How to remove a component from a report design

1	Select the component in the structure or layout pane.

2	Select Edit→Delete.

Or, with the component selected, choose Delete in the Context menu.


Managing multiple Design Editor windows

You can have only one report design open at one time. You can, however, open several Design Editor windows at the same time. For example, you can use one Design Editor to work with the whole report and another to focus on the page layout.

To manage multiple Design Editor windows, use the following techniques.

•	To open a Design Editor window focused on a single component from a report design, such as a page layout, follow the steps in Focusing the Design Editor on one component.

•	To change focus to a Design Editor window that is already open, use the Window menu.

See also

Focusing the Design Editor on one component


Focusing the Design Editor on one component

In addition to editing a report design, you can also open additional Design Editor windows to edit one component at a time. There are several reasons you might want to do this, including the following.

•	You are working on a complex report design and you want to focus on one component without distractions.

•	You need to modify the appearance of a component that is not normally displayed in the layout pane, such as the page component.

•	You are creating or modifying a reusable component from a library.

See also

How to focus the Design Editor on a single component


How to focus the Design Editor on a single component

You cannot open a Design Editor window on a single control or one of the database or data stream components. You can open a Design Editor window on any other type of component.

1	Open the report design.

2	To edit a library component, open the Library Browser. Choose View→Browse→Library and select the file name.

3	Select a component in the Design Editor, Library Browser, or any of the other Design Editor helper windows.

For more information about the helper windows, see About the Design Editor's helper tools.

4	Choose View→Design.

An additional Design Editor window appears.


Report Wizard

The Report Wizard lets you construct the beginnings of a simple Actuate report or a simple HTML report. The Report Wizard contains a subset of the tools available in the Design Editor. All the tasks you perform in the Report Wizard--and more--are available in the Developer Workbench Design Editor.

Page 1 of the Report Wizard explains what the Report Wizard can help you create.


Connection page of the Report Wizard

The Connection page, page 2 of the Report Wizard, helps you specify the properties of the connection you wish to make.

Concepts

A connection is a communication link with a database or other data source. An Actuate report contains a connection component, which establishes and maintains the connection. When you complete this page of the Report Wizard, Actuate adds a connection component to the report design.

A connection property is a value required to log on to the database server, such as server name, user name, and password. The properties required for your database connection vary, depending on the type of database connection you select. A value for every property may not be necessary. The prompts indicate the properties that are associated with the type of connection you selected. However, the specific connection being used might not actually require all these values.

When you leave this page of the Wizard, such as by choosing the Tables and Views tab, Actuate will log on to your database server.

More information

For details about connection properties, see your DBMS documentation.

For more information about how the AFC classes work with the database connections, see Actuate Foundation Class Reference.

After you finish using the Report Wizard, use the Design Editor to modify the connection or add more connections. For more information, see Defining database connections.

See also

How to specify the connection properties


How to specify the connection properties

1	From list under "Select a database connection," select the database connection you wish to make.

The properties that apply to type of connection you selected appear below in the list box.

2	Set the connection properties. To set a property, click in the field to the right of the property name and type a value.

Some properties are optional, depending on your database server. And, you may occasionally need to add more than the supplied properties. The ODBC database connection requires, for example, the name of the DataSource, such as sfdata. The sfdata data source is used in Building your first report.

3 	After you press Next, you may be asked to log into the database you have specified. Type in any necessary passwords

See also

DB2 connection properties
Informix connection properties
Microsoft SQL Server connection properties
ODBC connection properties
Oracle connection properties
Progress connection properties
Sybase connection properties
Sybase DBLib connection properties


DB2 connection properties

For details about these properties, see your DB2 documentation.

Property	Description
DllPath	Name of DLL providing client database connectivity.
DataSource	The DB2 data source.
Password	The password may be required, depending on your user account.
UserName	Your user ID, required for the connection.


Informix connection properties

For details about these properties, see your Informix documentation.

Property	Description
DllPath	Name of DLL providing client database connectivity.
Database Environment	The name of the database and/or server to which you want to connect. Specify either a server and a database, a database server only, or a database only.
Password	May be required depending on your user account.
UserName	Your user ID as specified in your user account.


Microsoft SQL Server connection properties

For details about these properties, see your Microsoft SQL Server documentation.

Property	Description
DllPath	Name of DLL providing client database connectivity.
Password	May be required depending on your user account.
ServerName	If not supplied, Actuate defaults to locally-defined server.
UserName	Your user ID as specified in your user account.


ODBC connection properties

For details about these properties, see your database vendor's documentation.

Property	Description
ConnectionString	The contents of this string depend on the driver you are using with your ODBC data source. For example, the connection string could include the name of an Excel file. See your ODBC driver documentation for information about the connection string for the driver you are using.
DataSource	Before using an ODBC connection, you must create an ODBC data source using the ODBC-Administrator utility supplied with your ODBC driver software. See your ODBC documentation for information about how to set up the data source.
DllPath	Name of DLL providing client database connectivity. Default is most common name used for the connectivity DLL provided by the database vendor.
Password	May be required depending on your user account.
UserName	Your user ID as specified in your user account.


Oracle connection properties

For details about these properties, see your Oracle documentation.

Property	Description
DllPath	Name of DLL providing client database connectivity.
HostString	Network prefix, target host, and system ID of the remote database.
Password	May be required depending on your user account.
UserName	Your user ID as specified in your user account.


Progress connection properties

For details about these properties, see your Progress documentation.

Property	Description
Database List	Database name.
DllPath	Name of DLL providing client database connectivity. This is the Actuate/Progress interface software.
StartUp Parameters	Progress Open Interface Broker parameters.
Password	May be required to access the Progress database, depending on your user account.
UserName	Login name for the Progress database.


Sybase connection properties

For details about these properties, see your Sybase documentation.

Property	Description
CsDllPath CtDllPath	Names of DLLs providing client database connectivity.
Password	May be required depending on your user account.
ServerName	If not supplied, Actuate defaults to a locally-defined server.
UserName	Your user ID as specified in your user account.


Sybase DBLib connection properties

For details about these properties, see your Sybase DBLib documentation.

Property	Description
CsDllPath CtDllPath	Names of DLLs providing client database connectivity. For System 10 and System 11, use the default names libcs and libct for the Sybase connectivity DLLs. For version 4.9, supply the name libsybdb. An alternate common name is Default.
Password	The password may be required, depending on your user account.
ServerName	The server name for the connection.
UserName	Your user ID as specified in your user account.


Tables and views page of the Report Wizard

Page 3 of the Report Wizard shows the tables and views of the database you selected in the Connection page of the Wizard.

Concepts

A table is a named group of related data in rows and columns in a relational database. A view is a named set of data, created through a SQL SELECT statement, that forms a virtual table. Unlike a table, a view does not exist as a separate copy of data in the database. Tables and views are set up by the database administrator.

More information

After you finish this Wizard, you can use the Query Editor to work with tables and views in the report design. For more information, see Writing queries.

See also

How to set the table or view


How to set the table or view

To choose the table or view of data you wish to use in your report, you need to move each table or view you want to use to the right-hand column. To do this:

1	Select the table or view in the left-hand column.

2	Select the right arrow button.

To remove a table:

1	Select the table you want to remove in Selected Tables and Views.

2	Choose the left arrow button.


Sorting and grouping page of the Report Wizard

You complete the Sorting and Grouping page, page 4 of the Report Wizard, if you want to design a grouped report. The sorting choice lets you choose how you would like the items in a group to be arranged.

Concepts

A grouped report is a report that organizes data in nested groups. The data is sorted and displayed according to one or more common data values, called keys. All the data that shares one common value is grouped together.

Geographic region could be the outermost group for a nested report. "Region" would be the item in the table you indicate as a key. Nested inside the region group, could be the customer group. "Customer" is the key from the items listed in the table. This key indicates data is to be grouped by customer. A group nested inside the customer group could be "orders." "OrderID" might be the key to indicate this is the next level of grouping.

A frame is a rectangular container for controls such as graphics, numbers, and text. By selecting Before or After in this page of the Wizard, you specify whether you want to display data in frames before and after each group. For example, the frame before the group of orders for a customer might contain controls to display the customer name and address. To specify which data you want to display in each frame, you can use the Fields page of the Wizard, or you can use the Design Editor.

When you complete this page of the Wizard, Actuate takes four actions.

•	Adds the sorting information specified in the keys to the Order By clause of the report's query. For example, data may be sorted in alphabetical order by customer name.

•	Adds a group section component to the report for each key. A group section is a component that sorts rows on a common field and contains components to display the data in those rows.

•	Adds a frame to the last group section. This is the detail frame, which displays the innermost level of sorted data rows.

•	If you selected Before or After for any of the keys, Actuate adds frame components to the Before or After slots of the corresponding group sections.

More information

After you finish this Wizard, you can use the Design Editor to add or remove group sections, change sort keys, and add or delete frames. For more information, see About group sections, About sorting data, and Placing a frame in a report design.

See also

How to sort and group


How to sort and group

1	Click in the first empty field under Keys.

The list displays the columns from the tables and views you selected in the Tables and Views page of the Wizard.

2	From the list, select a column name.

3	In Sort, select Ascending (1-100, A-Z) or Descending (100-1, Z-A). This is an alphanumeric sort. Selecting "Ascending" lets your group key be sorted from A-Z. For example, if your key is "City," an ascending sort would cause a Anchorage group items to be listed before group items in Minneapolis and Wellington.

4	(Optional) To place a group section in the Before frame, select Before. Note that when you're just starting out, it is easiest to place your group sections in Before frames, generate the report, and see how the Design Editor behaves.

5	(Optional) To place a group section, in the After frame select After.

6	Repeat these steps to add more keys.

To delete a key, click the numbered button to the left of the key and press Delete.

To specify which data you want to display in the Before and After frames, you can use the Fields page of the Wizard.


Fields page of the Report Wizard

Complete this page, which is Page 5 of the Report Wizard, if you selected Before or After in the Sorting and Grouping page of the Wizard.

Concepts

When you complete this page of the New Report Wizard, Actuate adds controls to the report design to display the data from the columns you selected. A control is a component that displays data, such as text or numbers. For example, a control can display a customer name or a calculated value such as an order total.

The frame you select determines where the controls appear in the report. For example, a frame called Group_Before_customers_custID might contain controls to display the customer name, address, and phone number. These values are then displayed at the beginning of each customer's group of data.

The detail frame is a frame that Actuate automatically adds to the last group section. This frame is normally used to display the innermost level of sorted data rows, such as individual items and prices in sales orders.

A sum is a total which Actuate calculates by adding values for that column within that group of data. For example, the items in one order constitute a group of data, and the total order amount is calculated by adding the amount for each item in the order group.

More information

After you finish this Wizard, you can use the Design Editor to add controls, delete controls, move controls from one frame to another, or change the data displayed by particular controls. For more information, see Working with frames and controls and Using the Design Editor.

See also

How to set fields


How to set fields

1	In the list box, select the name of a frame.

The list displays one entry for each Before or After checkbox you selected in the Sorting and Grouping page of the Report Wizard, and an entry for the Detail Frame.

2	In Available Fields, select the name of a column that contains data you want to display in the selected frame.

The list displays the columns from the tables and views you selected in the Tables and Views page of the Wizard.

3	Choose the right arrow button.

4	(Optional) To display a total, select Sum.

5	To add more fields to the same frame, repeat steps 2 through 4. To work on another frame, start from step 1.

To remove a field from the list, select the field name in Selected Fields and choose the left arrow button.


Page Style page of the Report Wizard

In Page Style, which is Page 6 of the Report Wizard, you specify the Report Title, the paper size and orientation and whether you wish to create an HTML report.

Concepts

A page is a component that specifies the visual design of a page in the report. Actuate provides several standard page components for the most commonly-used pages. These standard components appear in the Paper Size list in this page of the Wizard.

When you complete this page of the Report Wizard, Actuate adds a page list component to the report design. The page list component is a container for the page styles used in the report design. Actuate also adds a page component that corresponds to the paper size and orientation you selected. The page component is contained by the page list component.

When you design a report using the New Report Wizard, the report contains only one page style. To design a report that uses several page styles, such as alternating left and right pages, use the Design Editor.

HTML reports do not use pages, but do require a larger than normal "width" in which to generate HTML. When you choose to create an HTML report, landscape mode provides the larger width.

More information

After you finish this Wizard, you can use the Design Editor to modify the page layout or change the page list. For more information, see Designing page layouts.

See also

How to set page style


How to set page style

1	In Report Title, type the name you wish to display at the top of your report.

2	In Paper Size, select the size of paper on which you wish to print the report. These dimensions also affect how the report appears when it is viewed online.

3	In Orientation, select Portrait or Landscape. This choice determines whether the long or short edge of the paper is used as the leftmost edge.

4	If you check the box next to "Create an HTML Report," you set up the report to generate an HTML report rather than an "ordinary" Actuate report. This choice automatically selects Landscape mode.


Finish page of the Report Wizard

If you are finished using the Wizard, use Page 7, the Finish page.

More information

After you finish this Wizard, you can run the report immediately, or you can continue designing the report by doing some or all of the following tasks.

•	Define the report appearance using the Design Editor layout pane. See Using the Design Editor.

•	Refine the query using the Query Editor. See Writing queries.

•	Set page margins, columns, headers, and footers. See Designing page layouts.

•	Add more sections to determine the report structure. See Working with sections.

•	Add frames and controls to display more data. See Working with frames and controls.

•	Work with the HTML component palette to create an HTML report. See Building HTML reports.

See also

How to finish


How to finish

If you are finished using the Wizard, choose OK. You can also choose any tab in the Wizard to modify or add to your previous selections. Choose OK at any time to exit the Wizard.

When you exit the Wizard, the Design Editor will appear, showing the report design Actuate builds using the selections you make in the Wizard. To run the report and see how it looks with real data, choose Report→Build/Run/View. Or, press the "Running Man" button.