Copyright: Actuate Software Corporation


  Actuate Client API

The Actuate Client Application Programming Interface Guide provides information about an API that you can use to control how and when a report is generated. The Requester API contains functions for performing the following tasks:

Accessing attributes and values of report parameters

Changing the values of report parameters

Generating reports

Displaying and printing reports

Configuring the print setup

Organization of this guide

Actuate Client API Guide includes the following sections.

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

Requester API reference. This section provides an alphabetical reference with descriptions and programmatic details for each Requester API method.

Search Extension API user guide. This section provides a description of the Search Extension API and a task-oriented description of the interface.

Search Extension API reference. This section provides an alphabetical reference with descriptions and programmatic details for each Search Extension API function.

See also

When to use the Requester API

When to use the Search Extension API


When to use the Requester API

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

•	Environment--varied platforms and operating systems

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

•	Development resources--moderate design cycle

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

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


When to use the Search Extension API

The Search Extension API is a tool developers use to customize the search feature of the Developer Workbench, Administrator Desktop, End User Desktop, LRX plug-ins, and ActiveX controls. Typically, developers use the Search Extension API to transfer the results of a user-specified search to a third-party application such as Excel.


Requester API user guide

The Requester API, formerly known as the Actuate API, is one of several Actuate programmatic interfaces. With the Requester API you can modify report parameters and then generate, display, and print new reports. A subset of the Requester API, called the LRX API, works in conjunction with Live Report Extensions to print reports locally.

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

•	About the Requester API

•	About the LRX API

•	Working with reports

•	Using the Requester and LRX APIs

•	API functions by programming tasks

•	Summary of methods included with the LRX API

•	Writing your first Requester application

•	Using the Requester API in Actuate Basic: A programming example

•	Using the Requester API in Visual Basic: Programming examples

•	Using the Requester in a C++ application

•	Examples included with the Developer Workbench

For an alphabetic reference of all the functions in the Requester and LRX APIs, see Requester API reference.


About the Requester API

The Requester API controls how and when a report is generated. Using the Requester API, you write applications that perform the following tasks:

•	Access attributes and values of report parameters

•	Change the values of report parameters

•	Generate reports

•	Display and print reports

•	Configure the print setup

The Requester API works in conjunction with the Actuate Viewer or End User Desktop to display reports, and requires the Developer Workbench or End User Desktop to generate reports locally.


About the LRX API

The LRX API is much smaller than the Requester API and is better suited to printing reports from the Netscape or Internet Explorer LRX. Using the LRX API, you write applications that perform the following tasks:

•	Check and set up the client environment for printing reports

•	Display and print reports locally

The LRX API only works locally. To work with the Report Server, you must use the Requester API. Since the LRX API is a subset of the Requester API, you can implement LRX functions using either the LRX or Requester APIs.

To print from Netscape or the Internet Explorer, you need to use command line options for the LRX. For more information on using command line options, see Using Reports.

For a summary of the LRX API methods, see Summary of methods included with the LRX API.


Working with reports

How you use the Requester or LRX APIs depend on how you handle reports within your organization. You can use the APIs in different ways:

•	Client-server reporting

If you currently use the Actuate Report Server and Report Encyclopedia to handle your reporting tasks, then you will likely use the Requester API on a client machine that interacts with a separate Report Server.

•	Local reporting

If you perform your reporting tasks locally using the End User Desktop or Developer Workbench, then you must use the local reporting features of the Requester API.

If you view and print reports using a web browser, then the LRX API may provide the features you require. The LRX API only works for local reporting.

The way you write your application for client-server versus local reporting is slightly different. For example, an API application must connect with a Report Server for client-server reporting, but not for local reporting.

The following sections describe both reporting methods and show the required Actuate products and how they interconnect.

See also

Working with the Report Server
Working locally


Working with the Report Server

The Requester API, working in conjunction with a Report Server, uses a client-server architecture to execute, view, and print reports. The client typically runs the following software components:

•	Requester API

•	Custom API application

•	Actuate Viewer (Windows OS only)

The Viewer is optional and only necessary if you want your application to display reports on-screen. The Actuate Viewer is ideal for this application, but you can also use the End User Desktop or Developer Workbench. In the UNIX environment you cannot display reports on a client.

The server runs the Actuate Report Server components:

•	Report Server

•	Report Encyclopedia (part of the report server)

The following diagram shows a typical client-server configuration for the Requester API.

Working with the Report Server, your application will:

•	Work with reports in the Report Encyclopedia

Reference report executable, parameter, and output files using rotp file system convention:

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

•	Observe Report Server security

Programmatically log into the Report Server as a valid user with read and execute privileges on the desired reports.

•	Print reports from the Report Server

Specify a printer known to the Report Server.

•	View reports locally (Windows OS only)

Launch a local copy of the Viewer, End User Desktop, or Developer Workbench. In the UNIX environment you cannot display reports on the client.


Working locally

Local reporting uses the End User Desktop or Developer Workbench rather than the Report Server for report generation. In the local configuration, the client machine contains all applications needed to generate, view, and print reports. You cannot work locally in the UNIX environment. Typical local configurations are:

•	Requester API and End User Desktop or Developer Workbench (includes Viewer)

•	LRX API and the LRX product

The following diagram illustrates a Requester application using the End User Desktop to generate, display, and print reports.

Working locally, your Requester application will:

•	Work with reports on a local hard drive

Reference report executable, parameter, and output files using standard operating system conventions:

<drive>:/<path>/<filename>

•	Generate and display reports locally

You specify the location of the application that compiles and displays the report. Specify report executable, parameter, and output files using standard file system conventions.

•	Print reports locally

Specify a printer known to the local operating system.

The LRX API also works locally, but cannot generate reports.


Using the Requester and LRX APIs

You can use the Requester API to run reports in batch mode, create your own requester interface in Visual Basic or C++, or generate a new report when an external hyperlink is activated. These tasks can be accomplished on a local machine or on a report server.

Using this API, you can inspect and change parameter values before generating a report. If you want to change, add, or delete the definitions of report parameters, you must do so in the report design itself.

See also

Requester and LRX API development environment
Choosing API files
Windows libraries
Unix libraries and path variables
Compilers
Requester API operating environment
Using the Requester API with the Actuate Viewer
Using the Requester 16-bit DLL in Windows 3.1
LRX API operating environment


Requester and LRX API development environment

You access the Requester and LRX APIs through a library of methods defined by header or declare statements and an API library file.

See also

API declarations


API declarations

You identify the API to your application according to the programming language you plan to use:

•	Actuate Basic

Call the Requester or LRX API functions as you would any other Actuate Basic function.

•	Visual Basic

Declare the Requester or LRX methods in a code module using the Declare statement. The REQAPIVB.TXT file contains declarations for all Requester and LRX API methods.

•	C or C++

For the Requester API, include the REQBASIC.H header file.

For the LRX API, include the LRXAPI.h header file.

When programming in C or C++, you declare strings as BSTRs. For more information, see Working with BSTR--Windows environment.


Choosing API files

The Requester API utilizes dynamic link libraries (DLL) and compiled libraries (ROX) during execution. Actuate periodically updates the DLLs to enhance features, correct problems, and support different development environments. This section explains how to choose the correct DLL version for your application.

See also

API file name conventions
API file versions


API file name conventions

The following table summarizes the naming conventions for files used by the Requester API

DLL	File Name
Report Server API DLL	ACRSxxyy.DLL • xx = Report Server API version • yy = Visual C++ version (4.1, 4.2, or 5.0) Example: ACRS3041.DLL
Requester API DLL	ACRQxxyy.DLL • xx = Requester version • yy = Visual C++ version (4.1, 4.2, or 5.0) Example: ACRQ3015.DLL
LRX API DLL	ACLXxxyy.DLL • xx = Requester version • yy = Visual C++ version (4.1, 4.2, or 5.0) Example: ACLX3041.DLL
.


API file versions

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

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

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

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


Windows libraries

When linking your Windows application, specify the library files appropriate for your compiler and Actuate release. The following tables summarize the DLLs for various combinations operating systems, compiler version, and Actuate release.

See also

Windows 95 or NT
Windows 3.1


Windows 95 or NT

For the Requester API, refer to the following table for the correct DLL:

Release	VC++ 4.1	VC++ 4.2	VC++ 5.0
Use ACRQ 30yy.DLL file dated before 4/20/98 3.0 to 3.0.6	ACRQ3041.DLL	ACRQ3042.DLL	N/A
Use ACRQ30yy.DLL file dated on or after 4/20/98 3.1 to 3.1.1	ACRQ3041.DLL	ACRQ3042.DLL	N/A
The correct DLL files have a property indicating Version 3.2 3.2	ACRQ3041.DLL	ACRQ3042.DLL	ACRQ3050.DLL
The Requester API requires the Report Server API DLL when you run your application. Refer to the following table to determine the correct Report Server DLL:

Release	VC++ 4.1	VC++ 4.2	VC++ 5.0
Use with ACRQ 30yy.DLL file dated before 4/20/98 3.0 to 3.0.6	ACRS3041.DLL	ACRS3042.DLL	N/A
Use with ACRQ30yy.DLL file dated on or after 4/20/98 3.1 to 3.1.1	ACRS3341.DLL	ACRS3342.DLL	N/A
The correct DLL files have a property indicating Version 3.2 3.2	ACRS3441.DLL	ACRs3442.DLL	ACRS3450.DLL
The LRX API does not require the Requester or Report Server DLLs. Refer to the following table to determine the required DLL for the LRX API:

Release	VC++ 4.1	VC++ 4.2	VC++ 5.0
3.2	ACLX3041.DLL	N/A	ACLX3050.DLL


Windows 3.1

For the Requester API running on a 16 bit system, use the following DLL and EXE files:

Release	VC++ 4.1	VC++ 4.2	VC++ 5.0
3.1.1	Required on Win32s systems. ACTRSAS must be executed once after installation to become registered on the system. ACRQ3015.DLL ACTRSAS.EXE	ACRQ3015.DLL ACTRSAS.EXE1	N/A
3.2	ACRQ3015.DLL ACTRSAS.EXE1	N/A	N/A
You generally specify the path to the library files in your development environment or copy the DLLs to your system directory. If you are using the Developer Workbench, the library files are in /actuate/devwb/lib folder and the DLL files are in the /actuate/devwb/bin folder.


Unix libraries and path variables

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

Operating system	Shared library	Path variable
SunOS	libreqstapi.so	LD_LIBRARY_PATH
HP-UX	libreqstapi.sl	SHLIB_PATH
AIX	libreqstapi_share.a	LIBPATH
Make sure the environment variable AC_SERVER_HOME is properly set for the server installation on your UNIX system.


Compilers

The compiler required for the Requester and LRX APIs is as follows:

•	Windows NT -- Visual Basic 4.0 or Visual C++ 4.1, 4.1, or 5.0

•	IBM AIX -- C++ version 3.x

•	HP-UX -- C++ A.10.24 to A.10.28. Do not use the ANSI C-C++ compiler.

•	Sun Solaris -- SC4.2 C++

UNIX C is not supported.

See also

Compile and Link options for UNIX C++


Compile and Link options for UNIX C++

At compile time, specify -D__ACSERVER as a command line option for all Unix platforms. For AIX, specify -D_ILS_MACROS as well.

The following are link options for UNIX C++:

SunOS SC4.2 C++	AIX C++ 3.X	HP-UX C++ A.10.24 to A.10.28.
-lreqstrapi -lrwtool -mt -lole41 -loleclisrvr41 -lmsrpc41 -lgdi41 -luser41 -lkernel41  -lprnt -lXm -lXt -lX11 -lthread -lposix4 /usr/ucblib/libucb.a	-lreqstrapi_share -lole41 -lgdi41 -luser41 -lkernel41 -lwincrt -lprnt41 -lXm -lXt -lXmu -lX11 -lm -lld -lC_r     -lC     -ldcelibc_r -ldcepthreads  -lpthreads  -lc_r      -lm -lc	-lreqstrapi -ldce       -lm           -lXt             -lXm  -lX11 -lacrwtool -ldce -lm -lole32  -loleaut32  -loc32  -loleclisvr32  -lole2ui32  -lddeml32  -lcommdlg32  -lcommctrl32  -lgdi32  -luser32  -lkernel32  -lprnt32 -lmsrpc32
Note

The following additional AIX link options are path and drive dependent and depend on your UNIX installation.

-bE:$(AC_SERVER_HOME)/sdk/reqapi/lib/app.exp

-bE:$(AC_SERVER_HOME)/sdk/reqapi/lib/Xm.exp

-bE:$(AC_SERVER_HOME)/sdk/reqapi/lib/Xt.exp

-bE:$(AC_SERVER_HOME)/sdk/reqapi/lib/X11.exp


Requester API operating environment

A client station running an application using the Requester API requires up to three components:

•	Actuate Viewer, End User Desktop, or Developer Workbench

The Actuate Viewer is required to view reports. The End User Desktop or Developer Workbench is required to run reports locally.

•	Custom application using the Requester API

•	Requester API DLL for your system

The Requester DLLs are located in the bin subdirectory of the Developer Workbench. When using the Requester API with the Actuate Viewer, you must also copy the viewer executable to the client system and set up the operating environment. The Actuate Viewer is free but other components require a valid license.


Using the Requester API with the Actuate Viewer

You can use the Actuate Viewer to display reports for your API application if you set up the client station as follows:

1	Install the Viewer

2	Copy the Requester DLL to your Windows system directory or set the PATH environment variable to the location of the DLL. If you copy the DLL, choose from the following:

•	Windows NT-- copy ACRQ3041.DLL to the System32 directory

•	Windows 95-- copy ACRQ3041.DLL to the System directory

•	Windows 3.1-- copy ACRQ3015.DLL to the System directory

3	Install your API application

On a 16-bit system, you must also install the OLE Automation Server, as described in "Using the Requester 16-bit DLL in Windows 3.1".


Using the Requester 16-bit DLL in Windows 3.1

To set up the Actuate Viewer on a 16-bit system:

•	Run the automation server (ACTRSAS.EXE) before using the Requester API. Running the automation server sets up the environment.

•	If programming in C or C++:

•	If you include the header file REQBASIC.H, define the macro _WIN16.

•	The currency type is a double. If you use a CY structure, copy the structure to a double before passing it as an argument to a function. Similarly, if the function returns a double, copy the value to the CY structure.


LRX API operating environment

An client station running a LRX API application requires up to four components:

•	Netscape or Internet Explorer browser

•	Actuate LRX for the browser

•	Custom application using the LRX API

•	The LRX DLL for your system

The LRX API only operates in the Windows environment.


API functions by programming tasks

This section categorizes and lists the functions in the Requester API by the following general programming tasks:

•	Writing startup and cleanup code

•	Working with report files

•	Getting the names of parameters and parameter groups

•	Getting the attributes of parameters

•	Getting the default values of parameters

•	Getting the current values of parameters

•	Setting parameter values

•	Configuring a printer

•	Running, viewing, and printing reports

•	Checking for errors

For a complete description of each function, see Requester API reference.

See also

Writing startup and cleanup code
Working with report files
Getting the names of parameters and parameter groups
Getting the attributes of parameters
Getting the default values of parameters
Getting the current values of parameters
Setting parameter values
Configuring a printer
Running, viewing, and printing reports
Checking for errors


Writing startup and cleanup code

The following table lists the functions for starting and ending usage of the Requester or LRX APIs.

Programming task	API function
Select the client product to use for client-side viewing, printing, and running reports	Members of both the Requester and LRX APIs AcReqSelectClient
Specify the End User Desktop application to use to generate a report (.ROI).	AcReqSetEUDTPath1
Initialize the API. This step is required before the program can call any of the other API functions.	AcReqInitialize1
Connect to the server if the program accesses files on a server.	AcReqConnect
Disconnect from the server after the program has finished executing tasks on the server.	AcReqDisconnect
Close the library and free resources used by the API.	AcReqUninitialize1
Applications must call AcReqSelectClient or AcReqSetEUDTPath to select the client product. AcReqSelectClient supersedes AcReqSetEUDTPath and is the recommended method for new applications. You must use AcReqSelectClient in order to use AcReqIsAfcInstalled, AcReqInstallAfc, or AcReqSetCacheSize.


Working with report files

When using the Requester API functions, you typically work with the following files:

•	Report parameter values (.ROV) file

The parameter values file contains a report request's parameter definitions and values. Actuate creates the parameter values file automatically when users issue a request. You open a parameter values file to access and manipulate parameter values. The alternative is to open a report executable (.ROX) file, described next. After setting parameter values, you write the information to a parameter values file, which you can then use to generate a report based on the specified parameter values.

•	Report executable (.ROX) file

The executable file contains the report request's parameter definitions as well as other information. Actuate creates the executable file when a report design is compiled and built. You open either a parameter values or executable file to access and manipulate parameter values.

•	Report document (.ROI)

From the API, you can display or print a report document on a local system or report server at any time.

See also

Specifying local file names--Requester API
Specifying report server file names--Requester API


Specifying local file names--Requester API

When you specify file names as arguments to the Requester API functions, you must specify the full path if the file you want to access is not in the current directory. For example, if code in a report opens an .ROV file in a different directory, specify the full path name of the .ROV file as an argument to AcReqReadFile.


Specifying report server file names--Requester API

The following is the syntax for specifying server file names as arguments to API functions:

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

<server>

Optional. The name of the server. If you omit this argument, the server the program is currently connected to is used by default.

<path>

The full path to the directory in which the file resides.

<filename>

The name of the file to access.

<version>

Optional. The version of the file to use. If you omit this argument, the latest version of the file is used by default. You can specify one of the following values:

Value	Description
Latest	The most recent version of the file
Oldest	The oldest version of the file
LatestDev	The most recent development version of the file
LatestRel	The most recent released version of the file
<#>	The version number of the file
<version name>	The version name of the file
The following are examples of valid arguments for AcReqViewReport, one of the Requester API functions that requires the filename argument:

AcReqViewReport( "rotp://Paradise/MyDir/MyReport.roi", AC_REQ_VIEW )

AcReqViewReport( "rotp://Paradise/MyDir/MyReport.rov;Latest", AC_REQ_VIEW )

AcReqViewReport( "rotp://Paradise/Accounting/July96/AcctRpt.roi", AC_REQ_VIEW )

AcReqViewReport( "rotp://Paradise/Accounting/July96/AcctRpt.roi;15", AC_REQ_VIEW )

The following table lists the functions for working with report files.

Programming task	API function
Open an .ROV or .ROX file to access information about the parameters.	AcReqReadFile
Create a new .ROV file to store parameter values you set.	AcReqWriteFile
Close an open .ROV or .ROX file.	AcReqCloseFile


Getting the names of parameters and parameter groups

At design time, parameters can be defined in logical groups. For example, a parameter group called Customer might contain the parameters Name, Credit_rank, and Purchase_volume. A parameter group called Office might contain the parameters City and State.

The Requester API provides functions for getting the names of parameter groups and parameters in the order in which they appear in the Requester dialog box in the Developer Workbench or End User Desktop. With this information, you can, for example, create a custom Requester dialog box with a Visual Basic form.

You also need the names of parameters as arguments to other functions that set or retrieve parameter values.

Programming task	API function
Get the name of the first parameter group.	AcReqGetFirstGroup
Get the name of the next parameter group.	AcReqGetNextGroup
Get the name of the first parameter.	AcReqGetFirstParameter
Get the name of the next parameter.	AcReqGetNextParameter


Getting the attributes of parameters

At design time, each parameter is assigned a variety of attributes, such as its data type, whether it is required or optional, or whether it is an ad hoc parameter or not. The Requester API provides functions for getting information on each parameter's attributes. You cannot change these attributes with the API.

Programming task	API function
Get a parameter's alias name. The alias name appears as a prompt in the Requester dialog box.	AcReqGetAlias
Determine if a parameter is required or optional.	AcReqGetRequired
Determine if a parameter can only be set programmatically.	AcReqGetHidden
Determine whether a parameter was defined to display asterisks or actual text as users type the value in the Requester.	AcReqGetHideText
Determine if a parameter is an ad hoc parameter.	AcReqGetAdhoc
Get the data type of a parameter as a string.	AcReqGetParmType
Get the data type of a parameter as an enumeration.	AcReqGetType


Getting the default values of parameters

At design time, parameters defined as required must have a default value. The default value is used if a value is not supplied when the report is run. The following table lists the functions for getting default values for parameters.

Programming task	API function
Get the default value of a parameter of any type as a string.	AcReqGetDefaultValueStr
Get the default value of a parameter of type currency as a currency.	AcReqGetDefaultValueCurrency
Get the default value of a parameter of type date as a date.	AcReqGetDefaultValueDate
Get the default value of a parameter of type double as a double.	AcReqGetDefaultValueDouble
Get the default value of a parameter of type integer as an integer.	AcReqGetDefaultValueInteger
Get the default value of a parameter of type string as a string.	AcReqGetDefaultValueString


Getting the current values of parameters

The current value of a parameter is the value last entered in the parameter values (.ROV) file. If you are accessing a parameter values file and need to find the values of parameters, use the functions described in the following table. If you are accessing an executable file, the values of parameters are the default values defined at design time.

Programming task	API function
Get the current value of a parameter of any type as a string.	AcReqGetValueStr
Get the current value of a parameter of type currency as a currency.	AcReqGetValueCurrency
Get the current value of a parameter of type date as a date.	AcReqGetValueDate
Get the current value of a parameter of type double as a double.	AcReqGetValueDouble
Get the current value of a parameter of type integer as an integer.	AcReqGetValueInteger
Get the current value of a parameter of type string as a string.	AcReqGetValueString


Setting parameter values

The following table lists the functions you use to set parameter values. You need to be careful to assign values whose type matches the parameter type. There is a function for each data type. Before you assign a value to a parameter, you can check the parameter's type by calling AcReqGetParmType.

Programming task	API function
Set the value of a parameter of type currency.	AcReqSetValueCurrency
Set the value of a parameter of type date.	AcReqSetValueDate
Set the value of a parameter of type double.	AcReqSetValueDouble
Set the value of a parameter of type integer.	AcReqSetValueInteger
Set the value of a parameter of type string.	AcReqSetValueString


Configuring a printer

If you do not want to use your system's default printer or its default settings, you can change the printer and the printer settings before you print a report. The following table lists the printer-related API functions.

Programming task	API function
Specify a printer to use.	Member of both the Requester and LRX APIs AcReqSetPrinterName
Specify the number of copies to print.	AcReqSetPrinterNumberCopies
Specify the page orientation as Portrait or Landscape.	AcReqSetPrinterOrientation
Specify the size of the image to print.	AcReqSetPrinterScale
Turn color printing on or off.	AcReqSetPrinterColor
UNIX servers do not support this feature. Turn duplexing on or off.	AcReqSetPrinterDuplex
Turn collating on or off.	AcReqSetPrinterCollate
UNIX servers support logical size but not physical size Specify the paper size by its type (Letter, Legal, and so on) or physical size.	AcReqSetPrinterFormName
Specify the paper size with specific dimensions.	AcReqSetPrinterPaperSize
Revert to the system's default printer.	AcReqSetDefaultPrinter
Specify the paper tray	AcReqSetPrinterTray


Running, viewing, and printing reports

The following table defines the methods used to run, view, and print reports.

Programming task	API function
Specify the priority for reports generated on the Report Server	AcReqSetRequestPriority
Generate a report (.ROI) based on an existing .ROV file or one you created with new parameter values.	AcReqGenerateReport
Print a report.	Members of both the Requester and LRX APIs AcReqPrintReport
Prints a report when the .ROX name for the ROI is different than the name stored within the ROI.	AcReqPrintReportEx1
Display a report.	AcReqViewReport1
You must call AcReqSelectClient or AcReqSetEUDTPath before printing, viewing, or running a report locally.

See also

Support methods for the LRX product
Running a report locally using the Requester API


Support methods for the LRX product

The following table lists the supporting methods tailored for printing reports from the LRX.

Programming task	API function
Gets the name of the .ROX file associated with a specified ROI file.	Members of both the Requester and LRX APIs AcReqGetRoxNameForRoi
Gets the name of the AFC executable required to view or print a report.	AcReqGetAfcNameForRox1
Asks if the specified AFC file is installed.	AcReqIsAfcInstalled1
Installs the specified AFC file.	AcReqInstallAfc1
Changes the size of the Actuate cache.	AcReqSetCacheSize1
You must call AcReqSelectClient before using AcReqIsAfcInstalled, AcReqInstallAfc, or AcReqSetCacheSize.

For a description of using these methods to write an LRX application that prints reports locally, see Writing an application to print from the LRX.


Running a report locally using the Requester API

When you call AcReqGenerateReport to generate a report, Actuate automatically runs the executable associated with the parameter values (.ROV) file you specify. It looks for the executable in the same directory in which the parameter values file resides. If the executable is not in the same directory as the parameter values file, Actuate displays "Can't access <file name>.rox" and displays an open file dialog box which you can use to find the executable.

To run a report in batch mode, you need to specify the executable programmatically. To do so, set the .ROX file name parameter--represented by the constant, AC_REQ_ROX--to the name of the executable to use before you write the parameter values to a new parameter values file. The .ROX file name parameter is a hidden parameter that can only be set programmatically; it does not appear in the Requester dialog box.

To set the .ROX file name parameter, use AcReqSetValueString as the following code snippet shows.

' Specify the .ROX file to use to generate the report

AcReqSetValueString( fileNum, AC_REQ_ROX, "c:\test\myreport.rox" )

' Write the parameter values you set to a new .ROV file. This file is in a

' different directory from the .ROX file

AcReqWriteFile( fileNum, "myreport.rov" )

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

AcReqGenerateReport( "myreport.rov", AC_REQ_GENERATE, 0)

If the executable you want to run is in the same directory as the parameter values file, you do not have to set the .ROX file name parameter.


Checking for errors

There are two functions you can use to check for error conditions that might occur with API function calls. One returns an error number, the other, an error string. There is also a function for checking the generation status of a report on a server.

Programming task	API function
Check the last error that occurred and return an error number.	AcReqGetError
Check the last error that occurred and return the error description.	AcReqGetErrorString
Check the status of a specified report-generation request on the server.	AcReqReportStatus


Summary of methods included with the LRX API

The LRX methods are a subset of the Requester methods. The following list summarizes the methods included in the LRX API:

AcReqInitialize

AcReqPrintReport

AcReqSetEUDTPath

AcReqSetPrinterName

AcReqUninitialize

AcReqViewReport

AcReqSelectClient

AcReqGetRoxNameForRoi

AcReqGetAfcNameForRox

AcReqIsAfcInstalled

AcReqInstallAfc

AcReqSetCacheSize

AcReqPrintReportEx


Writing your first Requester application

All Requester applications have a common set of core operations. This section explains how to build two simple applications, which both set parameters and generate a new report. These applications demonstrate two types of reporting:

•	Client-server reporting using the Report Server. Written in C++

•	Local reporting using the End User Desktop. Written in Visual Basic

Before trying out the following examples, set up your development environment as described in "Using the Requester and LRX APIs" on page 11.

See also

Writing an application that uses the Report Server
Writing an application for local reports
Writing an application to print from the LRX


Writing an application that uses the Report Server

You build a Requester application that generates, displays, and prints reports using the Report Server in six steps:

1	Initialize an API session

2	Connect to the server

3	Specify parameters

4	Run the report, specifying options such as viewing

5	Print the report

6	Close the API session

The C++ example code is broken into small member functions for clarity. An actual implementation would likely combine these segments into a larger procedure. Also, the server name and file names are hard-coded to a specific environment. For a practical example see Using the Requester in a C++ application.

See also

Initialize an API session
Connect to the server
Specify parameters
Run and view the report
Print a report
Close the API session


Initialize an API session

Initialize the Requester library and prepare the API for a new session by calling AcReqInitialize. Also, declare the application's variables.

#include <reqbasic.h>

static long fileNum;

static long sessionHandle;

static long connectionHandle;

void CReqReportDlg::OnSession()

{

// Initialize session

sessionHandle = AcReqInitialize();

}


Connect to the server

The gateway to the Report Encyclopedia is the Report Server connection. The Report Server enforces security by requiring a user name and password before validating a connection and allowing server requests. Once made, the server connection generally remains active for an entire session. Other methods use the server connection handle to invoke server functionality. The following C++ code makes a Report Server connection:

void CReqReportDlg::OnConnect()

{

// Connect to the Report Server

connectionHandle = AcReqConnect("Kilauea", "Administrator", "");

}

In this case, the application uses a fixed login account on Kilauea called Administrator. The user name and password must represent a valid account on the Report Server and the user must have permission to access and run the desired reports. The Administrator account is a special account for system administrators. The client application usually uses other accounts set up by the Report Server system administrator.


Specify parameters

All Actuate reports have two parameters that you must set prior to report execution:

•	RoiFileName -- Sets the name of the output report file.

•	RoxFileName -- Sets the name of the report executable file.

Reports have additional parameters that are part of the report design. This example has an optional parameter called customers_creditrank. Set the required and optional parameters before you run the report.

You get parameters from either an .ROX or .ROV file and then set the values. The parameters must be stored in a file prior to executing the report, either in a temporary file that AcReqGenerateReport creates or an explicit .ROV file that you create. This example uses the .ROX file as the report generation argument so there is no need to save the parameters in a .ROV file. For another variation of setting parameters and running a report using an explicit .ROV file see Generate a new report.

The following example shows how to specify parameters in C++. It assumes you have a report called Detail.rox in a folder called Western on your Report Server and you are already connected.

void CReqReportDlg::OnParameters()

{

// Read the .ROX from the server.

fileNum = AcReqReadFile( "rotp://Kilauea/Western/Detail.rox");

// Set the parameter specifying the output ROI name

AcReqSetValueString( fileNum, "RoiFileName", "/Western/Detail.roi");

// Set the parameter specifying the .ROX file to be used for report

AcReqSetValueString( fileNum, "RoxFileName", "/Western/Detail.rox");

// Set a report-specific paramater

AcReqSetValueString( fileNum, "customers_creditrank", "C");

}Note that you specify the report locations using the rotp format. This format tells the Requester API to look in the Report Encyclopedia for the file. The parameters RoiFileName and RoxFileName do not need the rotp format because the server location is implied.


Run and view the report

You submit a request for report generation with AcReqGenerateReport. This example generates a report from the .ROX, using the parameters you set in the previous step. Since this example does not use an explicit .ROV parameter file, the Report Server creates a temporary one in the Report Encyclopedia before running the report.

The following code segment shows how to request report generation in C++. The rotp format in the file specifier tells the API to look in the Report Encyclopedia for the report and execute it on the Report Server.

void CReqReportDlg::OnExecute()

{

// Generate Report

long requestHandle = AcReqGenerateReport (
"rotp://Kilauea/Western/Detail.rox",
AC_REQ_GENERATE + AC_REQ_VIEW,
fileNum);

}

When requesting report generation, you specify one or more options in the second argument of AcReqGenerateReport. With the options specified in this example, the Report Server generates the report (AC_REQ_GENERATE) and a local viewer displays the report (AC_REQ_VIEW).


Print a report

To print a report using Report Server resources, set the printer name and invoke the AcReqPrintReport method. Specify a printer known to the Report Server. If you do not specify a printer, the Report Server will use the default printer for the report.

void CReqReportDlg::OnPrint()

{

// Specify printer and print report

AcReqSetPrinterName( "HP LaserJet IIP");

requestHandle = AcReqPrintReport( "rotp://Kilauea/Western/Detail.roi",0);

}


Close the API session

The final step is simply cleanup code. You need to close the file, disconnect from the server, and close the API session.

void CReqReportDlg::OnClose()

{

AcReqCloseFile( fileNum );

AcReqDisconnect(connectionHandle);

AcReqUnInitialize(sessionHandle);

}


Writing an application for local reports

You build a Requester application that generates and prints reports locally, on the client machine, in six steps:

1	Declare Visual Basic Methods

2	Initialize an API session

3	Specify parameters

4	Run the report, specifying options such as viewing and printing

5	Print the report

6	Close the API session

Unlike working with reports in the Report Encyclopedia, you don't need a connection to the Report Server.

The code segments that accompany this description are written in Visual Basic. An actual implementation would likely combine these small segments into a larger procedure. For a more practical example, see Using the Requester API in Visual Basic: Programming examples.

See also

Declare Visual Basic methods
Initialize a session
Specify report generation parameters
Generate a new report
Print a new report
Close a session


Declare Visual Basic methods

Open REQAPIVB.TXT in a text or word processor, copy and paste all the function declarations into a general code module. Also, declare other global variables. Basic function declarations appear as follows:

Declare Function AcReqInitialize Lib "ACRQ3041.DLL" ( ) As Long

Declare Function AcReqUnInitialize Lib "ACRQ3041.DLL" (ByVal sessionHandle As Long ) As Boolean

' Other declarations ...

Dim sessionNum As Integer


Initialize a session

Initialize the Requester DLL and prepare the API for a new session by calling AcReqInitialize.

Private Sub Form_Load

sessionNum = AcReqInitialize( )

End Sub


Specify report generation parameters

All Actuate reports have two parameters that you must set prior to report execution:

•	RoiFileName -- Sets the name of the output report file

•	RoxFileName -- Sets the name of the report executable file

Reports have additional parameters that are part of the report design. This example has an optional parameter called customers_creditrank. You set both required and optional parameters before you run the report.

You get parameters from either an .ROX or .ROV file and then set the values. The parameters must be stored in a file prior to executing the report, either in a temporary file that AcReqGenerateReport creates or an explicit .ROV file that you create. This example uses an explicit .ROV file so it saves the parameters in a .ROV file before running the report. For another variation of setting parameters and running a report from a .ROX file, see Specify parameters.

The following example shows how to specify parameters in Visual Basic. It assumes you have a report called Detail.rox in a folder on your C: drive called example.

Private Sub SetParameters()

Dim fileNum As Long

' Open detail.rox to access the parameter definitions

fileNum = AcReqReadFile("c:/example/detail.rox")

' Set parameter values

AcReqSetValueString fileNum, AC_REQ_ROI, "c:/example/mydetail.roi"

AcReqSetValueString fileNum, AC_REQ_ROX, "c:/example/detail.rox"

AcReqSetValueString fileNum, "customers_creditrank", "C"

' Write the parameter values to mydetail.rov

AcReqWriteFile fileNum, "c:/example/mydetail.rov"

' Close the file

AcReqClosefile(fileNum)

End Sub

This example references the two required parameters using constants declared in reqapivb.txt:

' Intername paramter names.

Private Const AC_REQ_ROI As String= "RoiFileName"

Private Const AC_REQ_ROX As String= "RoxFileName"


Generate a new report

You submit a request for report generation with AcReqGenerateReport, using either the .ROX or .ROV files. When specifying the .ROV, as this example does, you need to pass the fileNum variable from the preceding step as an argument to the method.

The following code segment shows how to request report generation in Visual Basic. The standard Windows file specification in the file specifier tells the API to look in the local file system for the report and execute it on the specified End User Desktop.

Private Sub GenerateReport( )

Dim ret As Long

' Specify the End User Desktop application to generate the report

AcReqSetEUDTPath ("c:/actuate/devwb/bin/runview.exe")

' Generate the report

ret = AcReqGenerateReport("c:/example/mydetail.rov",
AC_REQ_GENERATE+AC_REQ_VIEW, 0)

End Sub

When working locally, specify the location of the End User Desktop or Developer Workbench you want to generate and display the report. Use AcReqSetEUDTPath for this purpose.

With the AcReqGenerateReport options specified in this example, the End User Desktop generates the report (AC_REQ_GENERATE) and then displays the report (AC_REQ_VIEW).


Print a new report

To print a report using Report Server resources, set the printer and invoke the AcReqPrintReport method. Specify a printer known to the local operating system.

Private Sub PrintReport( )

    Dim ret As Long

    AcReqSetDefaultPrinter

    ret = AcReqPrintReport("c:/example/mydetail.roi", AC_REQ_PRINT)

End Sub

As an alternative, you could have printed the report by specifying the AC_REQ_PRINT option in the AcReqGenerateReport command.


Close a session

Terminate the API session by calling AcReqUninitialize.

Private Sub Form_UnLoad( Cancel As Integer )

AcReqUnInitialize( sessionNum )

End Sub

For more information on writing the code to implement these steps, see Using the Requester API in Visual Basic: Programming examples.


Writing an application to print from the LRX

You print from the LRX by writing an application that uses the LRX API. The following steps summarize the process:

1	Choose the proper LRX using AcReqSelectClient.

2	If the report is an Actuate report, use AcReqGetAfcNameForRox to find out what AFC the report requires.

3	Using AcReqIsAfcInstalled, check to see if the required AFC is installed.

4	If the required AFC is not installed, install it using AcReqInstallAfc.

5	Using AcReqPrintReportEx, print the report.


Using the Requester API in Actuate Basic: A programming example

One typical use of the Requester API is to generate a new report before activating a hyperlink that connects one report to another. This feature, called dynamic hyperlinks, has two advantages over a hyperlink between two existing reports:

•	The information in the destination report is current as it is generated just before the hyperlink is activated.

•	The dynamic hyperlink does not rely on an existing destination report.

The example in this section shows how you generate a new report before activating a hyperlink. The report is generated when users press the left mouse button on a control. Two methods are overridden:

1	To trigger report generation, the OnLButtonDown of a control in the source report is overridden.

2	To implement the hyperlink to the newly-generated report, OnFollowLink of the source control is overridden.

See also

Example: Overriding OnLButtonDown()
Example: Overriding OnFollowLink()


Example: Overriding OnLButtonDown()

Function OnLButtonDown( view As AcReportView, Shift As AcShiftKeyState,
+ x As Integer, y As Integer ) As Boolean

    OnLButtonDown = Super::OnLButtonDown( view, Shift, x, y )

' Declare a variable to store the file number returned by AcReqReadFile.
' You need to use the file number as an argument to other functions.

Dim fileNum As Integer

' Declare a variable to store the value returned by AcReqGenerateReport.

Dim generateValue As Long

' Initialize the API. Declare a variable to store the session handle returned
' by AcReqInitialize.

Dim sessionNum As Integer

sessionNum = AcReqInitialize( )

' Open the .ROV file

fileNum = AcReqReadFile("c:\reports\detail.rov")

' If an error occurs, display the error description.

If (AcReqGetError(fileNum)) Then

MsgBox (AcReqGetErrorString(fileNum))

End If

' Assign values to the offices_state and customers_creditrank parameters.

AcReqSetValueString(fileNum, "offices_state", "MA")

AcReqSetValueString(fileNum, "customers_creditrank", "B")

' If an error occurs, display the error description.

If (AcReqGetError(fileNum)) Then

MsgBox (AcReqGetErrorString(fileNum))

End If

' Write the parameter value changes to the .ROV file.

AcReqWriteFile(fileNum, "c:\reports\detail.rov")

' If an error occurs, display the error description.

If (AcReqGetError(fileNum)) Then

MsgBox (AcReqGetErrorString(fileNum))

End If

' Generate the report using parameter values in the new .ROV file.

generateValue = AcReqGenerateReport("c:\reports\detail.rov",
+ AC_REQ_GENERATE+AC_REQ_LOCAL, 0)

' If an error occurs, display the error description.

If (AcReqGetError(fileNum)) Then

MsgBox (AcReqGetErrorString(fileNum))

End If

End Function


Example: Overriding OnFollowLink()

' Set up the hyperlink between this report and the newly-generated report.

Function OnFollowLink( ) As Boolean

    OnFollowLink = Super::OnFollowLink( )

' Declare an object reference variable of type AcReportController

    Dim theLink As AcReportController

' Create an instance of AcReportController

Set theLink = New AcReportController

' Specify the newly-generated report as the destination report

theLink.AttachReport("c:\reports\detail.roi")

' Specify the hyperlink search criteria. In this case, link to the destination
' OrderNumber control with a matching number.

theLink.FollowLink( "OrderTitleFrame::OrderNumber", "DataValue", CStr(DataValue), True )

End Function


Using the Requester API in Visual Basic: Programming examples

The following topics describe how you access and use the API from Visual Basic.

See also

Accessing the Requester API from Visual Basic
Example 1: Manipulating parameter values, generating and printing a report
Example 2: Creating a custom dialog box for requesting parameter values


Accessing the Requester API from Visual Basic

To access the Requester API, you must declare the functions in a general code module. The Actuate Developer Workbench provides a file, REQAPIVB.TXT, that contains all the declarations. If you installed the Developer Workbench in the default location, the file is in Actuate\Devwb. You can open REQAPIVB.TXT in a text or word processor, copy the function declarations you want, and paste them into a code module.

See also

Specifying the DLL in the Declare statement


Specifying the DLL in the Declare statement

If you type the declarations yourself, you must use a relative path name to the DLL. You must also ensure that the directory in which the DLL resides is in the search path, for example, the current directory or a directory defined in the PATH environment variable. Hard-coding a full path name to the DLL in the Declare statement causes problems. The following are examples of a valid and an invalid Declare statement.

Declare Function AcReqReadFile Lib "ACRQ3041.DLL" (ByVal fileName As String) As Long	' Valid statement

Declare Function AcReqReadFile Lib "C:\LIBRARIES\ACRQ3041.DLL" (ByVal fileName As String) As Long	' Invalid statement


Example 1: Manipulating parameter values, generating and printing a report

This example shows how you generate a report, print a report, get and set parameter values, and get parameter names from a Visual Basic form.

The following illustration shows the sample Visual Basic form and identifies the procedure with each button. The code for each procedure follows the illustration.

See also

Example 1: Declaring the Requester API functions
Example 1: Initializing the Requester API
Example 1: Generating and viewing a report locally
Example 1: Printing the report locally
Example 1: Getting and setting parameter values
Example 1: Getting the parameter names
Example 1: Generating a report on the Report Server
Example 1: Viewing a report on the Report Server
Example 1: Closing the Requester API library


Example 1: Declaring the Requester API functions

Open REQAPIVB.TXT in a text or word processor, copy all the function declarations and paste them into a general code module. In the same code area, declare the variables the test application uses. Edit these definitions to suit your environment.

Private Const DetailRox As String = "c:/examples/detail/detail.rox"

Private Const MyDetailRoi As String = "c:/examples/detail/mydetail.roi"

Private Const RunViewExe As String = "c:/bin/runview.exe"

Private Const SourceRox As String = "c:/examples/request/vb/source.rox"

Private Const MyTypesRov As String = "c:/examples/request/vb/mytypes.rov"

Private Const SourceRoi As String = "c:/examples/request/vb/source.roi"

Private Const RotpHost As String = "kilauea"

Private Const RotpUser As String = "Administrator"

Private Const RotpPassword As String = ""

Private Const RotpFolder As String = "/Western"

Private Const RotpObjectName As String = "detail"

Private Const RoiParmName As String = "RoiFileName"

Private Const RoxParmName As String = "RoxFileName"

Dim genReport As Boolean

Dim viewRpt As Boolean

Dim printRpt As Boolean

Dim stayopen As Boolean

Dim async As Boolean

Dim always As Boolean

Dim hideEUDT As Boolean

Dim sessionHandle As Long


Example 1: Initializing the Requester API

Private Sub Form_Load()

    sessionHandle = AcReqInitialize

    AcReqSetEUDTPath (RunViewExe)

End Sub


Example 1: Generating and viewing a report locally

Private Sub GenerateReport_Click()

    Dim fileNumber As Long

    Dim ret As Long

    fileNum = AcReqReadFile(DetailRox)

    If (AcReqGetError(fileNum)) Then

        MsgBox (AcReqGetErrorString(fileNum))

    End If

    'Set report parameters

    AcReqSetValueString fileNum, "RoiFileName", MyDetailRoi

    AcReqSetValueString fileNum, "RoxFileName", DetailRox

    AcReqSetValueString fileNum, "customers_creditrank", "C"

    ' Set the options to view the report

    genReport = True

    viewRpt = True

    printRpt = False

    stayopen = True

    async = False

    always = True

    hideEUDT = False

    opts = 0

    If (genReport = True) Then

        opts = AC_REQ_GENERATE

    End If

    If (viewRpt = True) Then

        opts = opts + AC_REQ_VIEW

    End If

    If (printRpt = True) Then

        opts = opts + AC_REQ_PRINT

    End If

    If (stayopen = True) Then

        opts = opts + AC_REQ_STAY_OPEN

    End If

    If (async = True) Then

        opts = opts + AC_REQ_ASYNC

    End If

    If (always = True) Then

        opts = opts + AC_REQ_LAUNCH_ALWAYS

    End If

    If (hideEUDT = True) Then

        opts = opts + AC_REQ_HIDE

    End If

    ret = AcReqGenerateReport(DetailRox, opts, fileNum)

    AcReqCloseFile fileNum

End Sub


Example 1: Printing the report locally

Private Sub PrintReport_Click()

    Dim ret As Long

    AcReqSetDefaultPrinter

    ret = AcReqPrintReport(SourceRoi, AC_REQ_PRINT)

End Sub


Example 1: Getting and setting parameter values

The following code assumes that the following parameters have been defined for the report design: aCurrency, aDate, aDouble, aInteger, aString.

Private Sub AllTypes_Click()

    Dim fileNumber As Long

    Dim inDouble, outDouble As Double

    Dim inInteger, outInteger As Integer

    Dim inLong, outLong As Long

    Dim inString, outString As String

    Dim inDate, outDate As Date

    Dim inCurrency, outCurrency As Currency

    inDouble = 0.0345

    inInteger = 321

    inLong = 987654

    inString = "Hello In"

    inDate = CDate(#12/6/67#)

    inCurrency = 123324.567

    fileNumber = AcReqReadFile(SourceRox)

    If (AcReqGetError(fileNumber)) Then

        MsgBox (AcReqGetErrorString(fileNumber))

    End If

    outCurrency = AcReqGetDefaultValueCurrency(fileNumber, "aCurrency")

    outDate = AcReqGetDefaultValueDate(fileNumber, "aDate")

    outDouble = AcReqGetDefaultValueDouble(fileNumber, "aDouble")

    outInteger = AcReqGetDefaultValueInteger(fileNumber, "aInteger")

    outString = AcReqGetDefaultValueString(fileNumber, "aString")

    AcReqSetValueCurrency fileNumber, "aCurrency", inCurrency

    AcReqSetValueDate fileNumber, "aDate", inDate

    AcReqSetValueDouble fileNumber, "aDouble", inDouble

    AcReqSetValueInteger fileNumber, "aInteger", inInteger

    AcReqSetValueString fileNumber, "aString", inString

    AcReqWriteFile fileNumber, MyTypesRov

    AcReqCloseFile fileNumber

    fileNumber = AcReqReadFile(MyTypesRov)

    If (AcReqGetError(fileNumber)) Then

        MsgBox (AcReqGetErrorString(fileNumber))

    End If

    outCurrency = AcReqGetValueCurrency(fileNumber, "aCurrency")

    outDate = AcReqGetValueDate(fileNumber, "aDate")

    outDouble = AcReqGetValueDouble(fileNumber, "aDouble")

    outInteger = AcReqGetValueInteger(fileNumber, "aInteger")

    outString = AcReqGetValueString(fileNumber, "aString")

    AcReqCloseFile fileNumber

End Sub


Example 1: Getting the parameter names

Private Sub FindParms_Click()

    Dim CurrentGroup As String

    Dim CurrentParameter As String

    Dim Alias As String

    Dim Required As Boolean

    Dim Hidden As Boolean

    Dim HideText As Boolean

    Dim Adhoc As Boolean

    Dim ParmType As String

    fileNumber = AcReqReadFile(DetailRox)

    CurrentGroup = AcReqGetFirstGroup(fileNumber)

    Do While (CurrentGroup <> "")

        CurrentParameter = AcReqGetFirstParameter(fileNumber, CurrentGroup)

        Do While (CurrentParameter <> "")

            Alias = AcReqGetAlias(fileNumber, CurrentParameter)

            Required = AcReqGetRequired(fileNumber, CurrentParameter)

            Hidden = AcReqGetHidden(fileNumber, CurrentParameter)

            HideText = AcReqGetHideText(fileNumber, CurrentParameter)

            Adhoc = AcReqGetAdhoc(fileNumber, CurrentParameter)

            ParmType = AcReqGetParmType(fileNumber, CurrentParameter)

            CurrentParameter = AcReqGetNextParameter(fileNumber, CurrentGroup)

        Loop

    CurrentGroup = AcReqGetNextGroup(fileNumber)

    Loop

    AcReqCloseFile (fileNumber)

End Sub


Example 1: Generating a report on the Report Server

Private Sub GenerateServerReport_Click()

    Dim connectionHandle As Long

    Dim requestHandle As Long

    Dim rov As String

    Dim rox As String

    Dim rsRoi As String

    Dim rsRox As String

    Dim fileNumber As Long

    ' Connect to the Report Server

    connectionHandle = AcReqConnect(RotpHost, RotpUser, RotpPassword)

    ' Build the file names based of the set properties.

    'rov = "rotp://" + RotpHost + RotpFolder + "/" + RotpObjectName + ".rov"

    rox = "rotp://" + RotpHost + RotpFolder + "/" + RotpObjectName + ".rox"

    rsRoi = RotpFolder + "/" + RotpObjectName + ".roi"

    rsRox = RotpFolder + "/" + RotpObjectName + ".rox"

    ' Read the rov from the server.

    fileNumber = AcReqReadFile(rox)

    ' Tell the Report Server where to generate the ROI

    AcReqSetValueString fileNumber, RoiParmName, rsRoi

    AcReqSetValueString fileNumber, RoxParmName, rsRox

    ' Set parameters for the Report

    AcReqSetValueString fileNumber, "customers_creditrank", "C"

    ' Generate the report

    requestHandle = AcReqGenerateReport(rox, AC_REQ_GENERATE, fileNumber)

    AcReqCloseFile fileNumber

    AcReqDisconnect (connectionHandle)

End Sub


Example 1: Viewing a report on the Report Server

Private Sub ViewServerReport_Click()

    Dim connectionHandle As Long

    Dim roi As String

    ' Connect to the Report Server

    connectionHandle = AcReqConnect(RotpHost, RotpUser, RotpPassword)

    ' Build the file names based of the set properties.

    roi = "rotp://" + RotpHost + RotpFolder + "/" + RotpObjectName + ".roi"

    ' View the report

    AcReqViewReport roi, AC_REQ_VIEW

    AcReqDisconnect (connectionHandle)

End Sub


Example 1: Closing the Requester API library

Private Sub Form_Unload(Cancel As Integer)

    AcReqUnInitialize (sessionHandle)

End Sub


Example 2: Creating a custom dialog box for requesting parameter values

This example shows how you can replace Actuate's requester interface with a custom interface that prompts users to supply values for report parameters when users run an executable. The following are general guidelines for implementing a custom requester interface:

1	The requester program must read in the parameter values (.ROV) file specified at the command line.

2	After reading in the values from the parameter values file and manipulating them, the requester program must write out the new parameter values to the same parameter values file.

3	Assign the name of the requester program executable to the CustomRequesterName property of the topmost report object in your report design. The topmost report object is a subclass of AcReport.

The following illustration shows the Visual Basic form, the custom requester interface. The code to implement the custom requester follows the illustration. In this simple example, the custom requester retrieves only one parameter.

See also

Example 2: Declaring the Requester API functions and global variables
Example 2: Loading the custom requester and initializing the Requester API
Example 2: Setting the parameter value entered by the user
Example 2: Closing the Requester API


Example 2: Declaring the Requester API functions and global variables

In a general code module, declare the Requester API functions that will be called.

Private Declare Function AcReqInitialize Lib "ACRQ3041.DLL" () As Long

Private Declare Function AcReqUnInitialize Lib "ACRQ3041.DLL" _

(ByVal sessionHandle As Long) As Long

Private Declare Function AcReqReadFile Lib "ACRQ3041.DLL" _
(ByVal fileName As String) As Long

Private Declare Sub AcReqWriteFile Lib "ACRQ3041.DLL" _
(ByVal fileNumber As Long, ByVal fileName As String)

Private Declare Sub AcReqCloseFile Lib "ACRQ3041.DLL" _
(ByVal fileNumber As Long)

Private Declare Function AcReqGetValueString Lib "ACRQ3041.DLL" _
(ByVal fileNumber As Long, ByVal aParmName As String) As String

Private Declare Sub AcReqSetValueString Lib "ACRQ3041.DLL" _
(ByVal fileNumber As Long, ByVal aParmName As String, _
ByVal aValue As String)

Private Declare Function AcReqGetErrorStr Lib "ACRQ3041.DLL" _
(ByVal fileNumber As Long) As String

' Declare global variables

Dim fileName As String

Dim fileNum As Long


Example 2: Loading the custom requester and initializing the Requester API

Private Sub Form_Load()

' Read in the parameter values file specified at the command line.

 fileName = Command

' Initialize the API

Dim sessionNum As Integer

    sessionNum = AcReqInitialize()

' Open the parameter values file to access the parameter definitions

fileNum = AcReqReadFile( fileName )

' Specify the parameter whose value to get

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

End Sub


Example 2: Setting the parameter value entered by the user

Private Sub btnClose_Click(Index As Integer)

' When the user clicks the Close button, set the value to the parameter

    AcReqSetValueString fileNum, "orders_orderID", valueField.Text

' Write the parameter value to the parameter values file

AcReqWriteFile fileNum, fileName

    End

End Sub


Example 2: Closing the Requester API

Private Sub Form_Unload(Cancel As Integer)

 AcReqUnInitialize( sessionNum )

End Sub


Using the Requester in a C++ application

This sections explains how to work with BSTR strings and dates in the C++ environment. A practical example shows how to specify report parameters, generate a report, and display the results in a C++ application.

See also

Working with BSTR--Windows environment
A C++ example


Working with BSTR--Windows environment

Unlike C++ strings that are freed by their creator, BSTRs, OLE strings, are freed by their requester. The following example shows how to use SysFreeString to free a BSTR. Failure to free a BSTR causes memory leaks.

// NT only.

        BSTR Alias;

        fileNumber = AcReqReadFile( szDetailRox );

        Alias = AcReqGetAlias( fileNumber, "RoiFileName" );

        SysFreeString(Alias);   // UNIX -> 'delete Alias;'

        AcReqCloseFile (fileNumber);

The following example shows how dates are set from C++ as doubles using C++ Runtime library classes:

 int fileNumber;

    double inDate, outDate;

        COleDateTime oleDate( 67, 12, 6, 0, 0, 0 ); // y   m  d  h  m  s

    inDate = oleDate;

        fileNumber = AcReqReadFile( szSourceRox );

    outDate =                   AcReqGetDefaultValueDate(fileNumber, "aDate");

        oleDate = outDate;

AcReqSetValueDate( fileNumber, "aDate", inDate );

        AcReqCloseFile( fileNumber );


A C++ example

This example shows how you generate a report, print a report, get and set parameter values, and get parameter names from a Visual C++ form.

The following illustration shows the sample Visual C++ form and identifies the procedure with each button. The code for each procedure follows the illustration.

This example demonstrates use of the following Requester methods:

Test description	Key classes & functions
Submit a request after setting three parameters.	AcReqSetValueString AcReqGenerateReport AcReqSetEUDTPath
Print a report locally.	AcReqSetPrinterName AcReqPrintReport
See also

Declaring variables
Setting parameters and generating a report
Printing a report
Viewing parameters for a report
Getting and setting report parameters


Declaring variables

This section defines the reports used in this example. Edit these definitions to suit your environment.

#include <reqbasic.h>

static char *szMyDetailRoi ="C:/Actuate/devwb/examples/detail/mydetail.roi";

// pointer to example ROI file (contains report instance)

static char *szDetailRox = "C:/Actuate/devwb/examples/detail/detail.rox";

// pointer to example .ROX file (contains report executable)

static char *szEUDT = "c:/Actuate/devwb/bin/runview.exe";

// pointer to End User Desktop

static char *szRoxFile = "RoxFileName";

// .ROX file to be used to generate the report (required by .ROV)

static char *szRoiFile =	"RoiFileName";

// ROI file to be generated (output parameter)


Setting parameters and generating a report

This code segment shows how to set the two required parameters and one report parameter and then submit the report for local execution.

void CReqReportDlg::OnGenerate()

{

int fileNumber;

//Initialize a session

long sessionHandle = AcReqInitialize();

// Open the report executable and read its parameter definitions

// Check the error flag to ensure the opertaion was successful

fileNumber = AcReqReadFile( szDetailRox );

if ( AcReqGetError(fileNumber) )

        AfxMessageBox ( (char*)AcReqGetErrorStr(fileNumber) );

// Set the output ROI name to myDetail.roi

AcReqSetValueString( fileNumber, szRoiFile, szMyDetailRoi );

// Set the parameter specifying the .ROX file for report generation to

// detail.rox

AcReqSetValueString( fileNumber, szRoxFile, szDetailRox );

// Set the customers_creaditrank input parameter to C

AcReqSetValueString( fileNumber, "customers_creditrank", "C" );

// Set a pointer to the End User Desktop

AcReqSetEUDTPath ( szEUDT );

// Generate the report myDetail.roi using the parameters just created and

// display it using the End User Desktop (print option here is set to False)

// Check for errors.

// Set the options to generate the report

BOOL viewRp = TRUE; // Views report

BOOL print = FALSE; // Prints Report

BOOL stayopen = TRUE; // Keep the EUDT open

BOOL async = FALSE; // Runs asynchronously

BOOL always = TRUE; // Launches EUDT

BOOL hide = FALSE; // Hide EUDT

long opts = AC_REQ_GENERATE	|

(viewRpt	? AC_REQ_VIEW : 0 )	|

(print	? AC_REQ_PRINT : 0 )	|

(stayopen	? AC_REQ_STAY_OPEN : 0 )	|

(async	? AC_REQ_ASYNC : 0 )	|

(always	? AC_REQ_LAUNCH_ALWAYS : 0 )	|

(hide	? AC_REQ_HIDE : 0 );

// Generate the report

long requestHandle = AcReqGenerateReport(szDetailRox, opts, 	fileNumber);

// Close the file and session

AcReqCloseFile( fileNumber );

AcReqUnInitialize( sessionHandle);

}


Printing a report

This code segment shows how to print the report you generated with the previous code.

void CReqReportDlg::OnPrint()

{

int ret;

//Initialize a session

long sessionHandle = AcReqInitialize();

// Set a pointer to the End USer Desktop

AcReqSetEUDTPath ( szEUDT );

// Set a pointer to the default printer

AcReqSetDefaultPrinter( );

// Uncomment this line if you want to set the number of copies printed

//AcReqSetPrinterNumberCopies( 1 );

// Print the myDetail.roi (this code assumes the report has already been

// generated)

ret = AcReqPrintReport(szMyDetailRoi, AC_REQ_PRINT);

AcReqUnInitialize( sessionHandle);

}


Viewing parameters for a report

This code facilitates viewing of parameters in a report.

void CActReqDlg::OnView()

{

    // Byte sized BStrings are used rather than short strings to allow identical code to work with Visual Basic

BSTR CurrentParameter;

BSTR CurrentGroup;

BSTR Alias;

    BOOL Required;

    BOOL Hidden;

    BOOL HideText;

    BOOL Adhoc;

    BSTR ParmType;

int fileNumber;

    // Open the parameter definition file from the report executable

fileNumber = AcReqReadFile( szDetailRox );

// Get the first parameter group defined for that report

CurrentGroup = AcReqGetFirstGroup(fileNumber);

while (*(((char*)CurrentGroup)+1))

{

        // Get the first parameter contained within the parameter group

CurrentParameter = AcReqGetFirstParameter(fileNumber, (char*) CurrentGroup);

        while (*(((char*)CurrentParameter)+1))

        {

// Find the alias set by the devleoper for that parameter

Alias = ReqGetAlias(fileNumber, (char*) CurrentParameter);

            // Find whether the parameter is required or not

Required = AcReqGetRequired(fileNumber, (char*) CurrentParameter);

            // Find whether the parameter is marked as hidden

Hidden = AcReqGetHidden(fileNumber, (char*) CurrentParameter);

            // Find whether the parameter has been marked with HideText or not

HideText = AcReqGetHideText(fileNumber, (char*) CurrentParameter);

            // Find whether the parameter is Adhoc or not

Adhoc = AcReqGetAdhoc(fileNumber, (char*) CurrentParameter);

            // Get the type of the parameter

ParmType = AcReqGetParmType(fileNumber, (char*) CurrentParameter);

// Free the BSTRs

SysFreeString(Alias);

SysFreeString(ParmType);

SysFreeString(CurrentParameter);

// Get the next parameter in the group.

CurrentParameter = AcReqGetNextParameter(fileNumber, (char*) CurrentGroup);

       }

// Free the BSTRs

SysFreeString(CurrentGroup);

// Get the next parameter group for the report

CurrentGroup = AcReqGetNextGroup(fileNumber);

    }

    // Close the file

AcReqCloseFile (fileNumber);

}


Getting and setting report parameters

This code demonstrates getting and setting report parameters.

void CActReqDlg::OnTypes()

{

    int fileNumber;

    double inDouble, outDouble;

    int inInteger, outInteger;

BSTR outString;

    double inDate, outDate;

    CURRENCY inCurrency, outCurrency;

COleDateTime oleDate( 67, 12, 6, 0, 0, 0 );

COleCurrency oleCurrency( 123324, 567 );

    char inString[]="Hello In";

    inDouble = 0.0345;

    inInteger = 321;

    inDate = oleDate;

    inCurrency = oleCurrency;

// Open the parameter definition file from the report executable

// Check for errors

fileNumber = AcReqReadFile( szSourceRox );

    if ( AcReqGetError( fileNumber ) )

        AfxMessageBox( (char*)AcReqGetErrorStr( fileNumber ) );

// ROX file contained above contains parameters named aCurrency, aDate,

// aDouble, aInteger and aString of type currency, date, double, integer

// and string respectively

// Find the default values set by the developer for the currency parameter named aCurrency

outCurrency.int64 = AcReqGetDefaultValueCurrency(fileNumber, "aCurrency");

// Find the default values set by the developer for the date parameter named aDate

    outDate =	AcReqGetDefaultValueDate(fileNumber, "aDate");

// Find the default values set by the developer for the double parameter named aDouble

    outDouble = AcReqGetDefaultValueDouble(fileNumber, "aDouble");

// Find the default values set by the developer for the integer parameter named aInteger

    outInteger = AcReqGetDefaultValueInteger(fileNumber, "aInteger");

// Find the default values set by the developer for the string parameter named aString

    outString = AcReqGetDefaultValueString(fileNumber, "aString");

// outCurrency is currently of type int64.  Set it to type Currency

oleCurrency = outCurrency;

// outDate is currently of type Double.  Set it to type date

oleDate = outDate;

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

AcReqSetValueCurrency( fileNumber, "aCurrency", inCurrency.int64 );

// Set the date parameter to the value of the inDate variable

AcReqSetValueDate( fileNumber, "aDate", inDate );

// Set the double parameter to the value of the inDouble variable

AcReqSetValueDouble( fileNumber, "aDouble", inDouble );

// Set the integer parameter to the value of the inInteger variable

AcReqSetValueInteger( fileNumber, "aInteger", inInteger );

// Set the string parameter to the value of the inString variable

AcReqSetValueString( fileNumber, "aString", inString );

// Write out the new parameter value file

AcReqWriteFile( fileNumber, szMyTypesRov );

// Close the file

AcReqCloseFile( fileNumber );

// Open the parameter file just created and check for errors

fileNumber = AcReqReadFile( szMyTypesRov );

    if (AcReqGetError(fileNumber))

        AfxMessageBox( (char*) AcReqGetErrorStr(fileNumber) );

    // Find all the parameter values.  These should match the ones set above

outCurrency.int64 = AcReqGetValueCurrency(fileNumber, "aCurrency");

    outDate = AcReqGetValueDate(fileNumber, "aDate");

    outDouble = AcReqGetValueDouble(fileNumber, "aDouble");

    outInteger = AcReqGetValueInteger(fileNumber, "aInteger");

    outString = AcReqGetValueString(fileNumber, "aString");

// convert the outCurrency value to Currency and the outDate value to Date

oleCurrency = outCurrency;

oleDate = outDate;

// Close the file

AcReqCloseFile( fileNumber );

}


Examples included with the Developer Workbench

The Developer Workbench includes examples for the Requester API in the Devwb\Examples\request folder.


Requester API reference

This reference alphabetically lists the functions in the Requester API and LRX API. Unless otherwise noted, the functions apply to the Requester API only. For a conceptual discussion of the Actuate Requester API and LRX API, see Requester API user guide.


AcReqCloseFile

See also

Closes an open parameter values (.ROV) or a report executable (.ROX) file.

Syntax

Basic: Sub AcReqCloseFile( fileNumber As Long )

C/C++: void AcReqCloseFile( long fileNumber )

fileNumber

The file number of the .ROV or .ROX file you opened with AcReqReadFile.

Description

Use AcReqCloseFile to close an open .ROV or .ROX file when it is not needed. For example, you can close this file and free up memory after you finish setting and writing parameter values to a new .ROV file.


See also

AcReqReadFile


AcReqConnect

See also

Connects to the specified server.

Syntax

Basic: Function AcReqConnect( server As String, username As String, password As String ) As Long

C/C++: long AcReqConnect( LPCSTR server, LPCSTR username, LPCSTR password )

server

The name of the report server to connect to.

username

The user name to use to log in to the server.

password

The user password to use to log in to the server.

Description

To access files and generate reports on a server, you must call AcReqConnect to connect to the server. Once your program establishes a connection to the server, you can call any of the Requester API functions to access .ROV, .ROX, or .ROI files on the server.

When your program has finished executing tasks on the server, call AcReqDisconnect to disconnect from the server.

Return value

A number indicating the connection handle.

Zero if the connection failed.


See also

AcReqDisconnect


AcReqDisconnect

See also

Disconnects from the specified server.

Syntax

Basic: Sub AcReqDisconnect( connectionHandle As Long )

C/C++: VBBOOL AcReqDisconnect( long connectionHandle)

connectionHandle

The handle to the connection to close. This value is returned by AcReqConnect when a connection to the server is established.

Description

When your program has finished executing tasks on the server, call AcReqDisconnect to disconnect from the server. Call AcReqDisconnect before AcReqUninitialize, which clears the Requester API from memory.


See also

AcReqConnect


AcReqGenerateReport

See also

Generates a report (.ROI) from a report executable (.ROX) or a parameter values (.ROV) file.

Syntax

Basic: Function AcReqGenerateReport( filename As String, options As Long, fileNumber As Long ) As Long

C/C++: long AcReqGenerateReport( LPCSTR filename, long options, long fileNumber)

filename

The name of the .ROX or .ROV file to use to generate the report. Specify the full path name if the file is not in the current directory.

If the file resides on a server, use the following format:

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

For information about specifying server file names, see Specifying report server file names--Requester API.

options

A set of constants you can use to specify how the End User Desktop application runs. When specifying multiple options, logically add them using the plus (+) character. The following table lists and describes the constants.

Option	Description
AC_REQ_LAUNCH_ALWAYS	Runs a new instance of an End User Desktop application to generate the report. AC_REQ_LAUNCH_ALWAYS and AC_REQ_LOCAL are mutually exclusive.
AC_REQ_LOCAL	Generates the report in the current instance of the Developer Workbench or End User Desktop. AC_REQ_LAUNCH_ALWAYS and AC_REQ_LOCAL are mutually exclusive.
AC_REQ_GENERATE	Generates the report.
AC_REQ_VIEW	Displays the generated report.
AC_REQ_PRINT	Prints the generated report. This option is valid only if the report is on a local computer.
AC_REQ_ASYNC	Runs this process asynchronously; the function returns immediately and the report is generated in the background.
AC_REQ_HIDE	Does not display the End User Desktop application while it generates the report.
AC_REQ_STAY_OPEN	Keeps the End User Desktop application open after it generates the report. This option is ignored if the report is generated in the current instance of the End User Desktop.
AC_REQ_SHOW_PROG_WND	Displays the progress window of the End User Desktop or Developer Workbench while a report in generating.
AC_REQ_USE_HANDLE	Reserved.
Scope of options

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

Options	Local report Local launch	Server report Local launch	Server report Server launch
AC_REQ_LAUNCH_ALWAYS	Yes	Yes, if report viewing needed	No
AC_REQ_LOCAL	Yes, if using Actuate Basic	No	No
AC_REQ_VIEW	Yes	Yes	No
AC_REQ_PRINT	Yes	Yes	Yes
AC_REQ_ASYNC	Yes	Yes	Yes
AC_REQ_HIDE	Yes, if report viewing not needed	Yes, if report viewing not needed
AC_REQ_STAY_OPEN	Yes	Yes, if report viewing needed
If you do not specify any generation options, Actuate does the following by default:

•	Generates the report with the current instance of the End User Desktop application. If an End User Desktop application is not running, Actuate attempts to launch a new instance, but only if you specified the location with the AcReqSetEUDTPath function.

•	Runs the process synchronously. The function returns after the report is generated.

•	Displays the End User Desktop application as it generates the report only if the report is local.

fileNumber

If you are generating a report from an .ROV file, enter 0. If you are generating a report from an .ROX file, enter the file number returned by AcReqReadFile.

The following are examples of how you specify arguments for AcReqGenerateReport:

AcReqGenerateReport( "detail.rov", AC_REQ_VIEW, 0 )

AcReqGenerateReport( "detail.rov", AC_REQ_PRINT+AC_REQ_HIDE, 0)

AcReqGenerateReport( "detail.rox", AC_REQ_LOCAL, fileNum )

The first call passes the name of a parameter file, the constant representing the message to display the generated report, and the zero to generate a report from the parameter file. The second call is the same as the first except it passes two constants that represent a message to generate and print the generated report without displaying the End User Desktop. The third call passes an executable file, a constant that represents a message to generate the report in the current instance of the Developer Workbench or End User Desktop, and the file number returned by AcReqReadFile.

The following call generates the report on the server with a stored file.

rsMyRov = "rotp://" + RotpHost + RotpFolder + "/" + "mydetail" + ".rov"

requestHandle = AcReqGenerateReport(rsMyRov, AC_REQ_GENERATE, 0)

Description

Use AcReqGenerateReport to generate a report based on parameter values specified in an .ROV or .ROX file. With this function, you incorporate report generation in your application. The capability to generate reports programmatically is useful for batch creation of reports.

To generate a report from an .ROV file, Actuate runs the .ROX file associated with the .ROV file you specify. It looks for the .ROX file in the same directory where the .ROV file resides. If the .ROX file is not in the same directory as the .ROV file, Actuate displays "Can't access <file name>.rox" and displays an open file dialog box which you can use to find the .ROX file.

To run a report in batch mode, you need to specify the .ROX file programmatically. To do so, set the .ROX file name parameter--represented by the constant, AC_REQ_ROX-- to the name of the .ROX to use before you write the parameter values to a new .ROV file. The .ROX file name is a hidden parameter that can only be set programmatically; this parameter does not appear in the Requester dialog box. To set the .ROX file name parameter, use AcReqSetValueString as the following example shows.

AcReqSetValueString( fileNum, AC_REQ_ROX, "c:\test\myreport.rox" )

If the .ROX you want to run is in the same directory as the .ROV file, you do not have to set the .ROX file name parameter.

By default, the .ROI file that AcReqGenerateReport creates has the same root name as the .ROX file used to create the report, but you can change the .ROI file name with AcReqSetValueString. For more information, see AcReqSetValueString.

For more information and an example on generating a report, see Using the Requester API in Visual Basic: Programming examples.

Return value

The return value indicates the result of the report execution and any error codes, as shown below:

Return value	Specified generation options value	Indication
0	AC_REQ_ASYNC	Report executed successfully on a local client.
1 to 1023	AC_REQ_ASYNC	Report execution failed. The return value indicates the error code. This method returns the same error codes as AcReqGetError. For more information, see AcReqGetError.
1024 or greater	AC_REQ_ASYNC	Report executed successfully on the Report Server.
0 or less than 0	none	Report executed successfully on the Report Server.
greater than 0	none	Report execution failed.


See also

AcReqSetEUDTPath

AcReqSetRequestPriority


AcReqGetAdhoc

See also

Returns True or False, depending on whether the parameter is an ad hoc parameter or not.

Syntax

Basic: Function AcReqGetAdhoc( fileNumber As Long, parmName As String ) As Boolean

C/C++: VBBOOL AcReqGetAdhoc( long fileNumber, LPCSTR ParmName )

fileNumber

The file number of the .ROV or .ROX file you opened with AcReqReadFile.

parmName

The name of the parameter whose ad hoc attribute you want. If you do not know the names of the parameters, use AcReqGetFirstParameter and AcReqGetNextParameter to get the parameter names.

Description

Use AcReqGetAdhoc to find out if a parameter was designed as an ad hoc parameter. An ad hoc parameter accepts a conditional expression that extends the Where clause of a query when the report is generated.

Return value

True if the parameter is an ad hoc parameter.

False if the parameter is not an ad hoc parameter.


See also

AcReqGetFirstParameter

AcReqGetNextParameter


AcReqGetAfcNameForRox

Gets the name of the AFC executable required to view or print a report.

Syntax

Basic: Function AcReqGetAfcNameForRox( roxName As String ) as String

C/C++: BSTR AcReqGetAfcNameForRox( const char *roxName )

Description

Returns the name of the AFCxxx.ROX file required to view or print a report using the ROX file specified. Returns an empty string if the ROX file cannot be found. Specify the Actuate client with AcSelectClient before calling AcReqGetAfcNameForRox.

If this function is used with a file stored in the cache, then the "roxName" parameter should be the local cache file name returned from AcReqCopyToCache.

AcReqGetAfcNameForRox is a member of both the Requester and LRX APIs.

Return value

Name of the AFC executable.


AcReqGetAlias

See also

Returns the alternate name of the specified parameter.

Syntax

Basic: Function AcReqGetAlias( fileNumber As Long, parmName As String ) As String

C/C++: BSTR AcReqGetAlias( long fileNumber, LPCSTR parmName )

fileNumber

The file number of the .ROV or .ROX file you opened with AcReqReadFile.

parmName

The name of the parameter whose alias name you want. If you do not know the names of the parameters, use AcReqGetFirstParameter and AcReqGetNextParameter to get the parameter names.

Description

Use AcReqGetAlias to get the alias name of a parameter. When defining parameters, programmers use alias names to create descriptive prompts that appear in the Requester dialog box. For example, Customer Name is more descriptive than Cust_Name.

If you are building a custom requestor interface in a Visual Basic form, for example, you can use the alias names that AcReqGetAlias returns to create an interface similar to the Requester dialog box in the Developer Workbench.

Return value

The alias name of the specified parameter.

An empty string if there is no alias or if an error occurred.


See also

AcReqGetFirstParameter

AcReqGetNextParameter


AcReqGetDefaultValueCurrency

See also

Returns the default value of the specified parameter as a currency.

Syntax

Basic: Function AcReqGetDefaultValueCurrency( fileNumber As Long, parmName As String) As Currency

C/C++: REQCYTYPE AcReqGetDefaultValueCurrency( long fileNumber, LPCSTR parmName )

fileNumber

The file number of the .ROV or .ROX file you opened with AcReqReadFile.

parmName

The name of the parameter whose default value you want. If you do not know the names of the parameters, use AcReqGetFirstParameter and AcReqGetNextParameter to get the parameter names.

Description

Use AcReqGetDefaultValueCurrency to get the default value of a parameter as a currency. The default value is the value defined by the programmer at design time. This value is used if the user does not supply a value when the report is run. Parameters defined as required always have default values. A default value is constant and independent of the value set by a user through the Requester.

When calling AcReqGetDefaultValueCurrency, the parameter you specify as an argument must be of type Currency. If you specify a parameter of any other type, AcReqGetDefaultValueCurrency returns the default value for that type. If you want to pass an argument of any type, use AcReqGetDefaultValueStr. However, the value AcReqGetDefaultValueStr always returns a string.

Use AcReqGetParmType to check the data type of a parameter.

Return value

The default value of the specified parameter as a currency.


See also

AcReqGetDefaultValueStr

AcReqGetFirstParameter

AcReqGetNextParameter

AcReqGetParmType


AcReqGetDefaultValueDate

See also

Returns the default value of the specified parameter as a date.

Syntax

Basic: Function AcReqGetDefaultValueDate( fileNumber As Long, parmName As String ) As Date

C/C++: double AcReqGetDefaultValueDate( long fileNumber, LPCSTR parmName )

fileNumber

The file number of the .ROV or .ROX file you opened with AcReqReadFile.

parmName

The name of the parameter whose default value you want. If you do not know the names of the parameters, use AcReqGetFirstParameter and AcReqGetNextParameter to get the parameter names.

Description

Use AcReqGetDefaultValueDate to get the default value of a parameter as a date. The default value is the value defined by the programmer at design time. This value is used if the user does not supply a value when the report is run. Parameters defined as required always have default values. A default value is constant and independent of the value set by a user through the Requester.

When calling AcReqGetDefaultValueDate, the parameter you specify as an argument must be of type Date. If you specify a parameter of any other type, AcReqGetDefaultValueDate returns the default value for that type. If you want to pass an argument of any type, use AcReqGetDefaultValueStr. However, the value AcReqGetDefaultValueStr returns is always a string.

Use AcReqGetParmType to check the data type of a parameter.

Return value

The default value of the specified parameter as a date.

The following example shows how to work with dates expressed as C++ doubles:

    int fileNumber;

    double inDate, outDate;

    COleDateTime oleDate( 67, 12, 6, 0, 0, 0 ); // y   m  d  h  m  s

    inDate = oleDate;

    fileNumber = AcReqReadFile( szSourceRox );

    outDate = AcReqGetDefaultValueDate(fileNumber, "aDate");

    oleDate = outDate;

    AcReqSetValueDate( fileNumber, "aDate", inDate );

    AcReqCloseFile( fileNumber );


See also

AcReqGetDefaultValueStr

AcReqGetFirstParameter

AcReqGetNextParameter

AcReqGetParmType


AcReqGetDefaultValueDouble

See also

Returns the default value of the specified parameter as a double.

Syntax

Basic: Function AcReqGetDefaultValueDouble( fileNumber As Long, parmName As String ) As Double

C/C++: double AcReqGetDefaultValueDouble( long fileNumber, LPCSTR parmName )

fileNumber

The file number of the .ROV or .ROX file you opened with AcReqReadFile.

parmName

The name of the parameter whose default value you want. If you do not know the names of the parameters, use AcReqGetFirstParameter and AcReqGetNextParameter to get the parameter names.

Description

Use AcReqGetDefaultValueDouble to get the default value of a parameter as a double. The default value is the value defined by the programmer at design time. This value is used if the user does not supply a value when the report is run. Parameters defined as required always have default values. A default value is constant and independent of the value set by a user through the Requester.

When calling AcReqGetDefaultValueDouble, the parameter you specify as an argument must be of type Double. If you specify a parameter of any other type, AcReqGetDefaultValueDouble returns the default value for that type. If you want to pass an argument of any type, use AcReqGetDefaultValueStr. However, the value AcReqGetDefaultValueStr returns is always a string.

Use AcReqGetParmType to check the data type of a parameter.

Return value

The default value of the specified parameter as a double.


See also

AcReqGetDefaultValueStr

AcReqGetFirstParameter

AcReqGetNextParameter

AcReqGetParmType


AcReqGetDefaultValueInteger

See also

Returns the default value of the specified parameter as an integer.

Syntax

Basic: Function AcReqGetDefaultValueInteger( fileNumber As Long, parmName As String ) As Integer

C/C++: long AcReqGetDefaultValueInteger( long fileNumber, LPCSTR parmName )

fileNumber

The file number of the .ROV or .ROX file you opened with AcReqReadFile.

parmName

The name of the parameter whose default value you want. If you do not know the names of the parameters, use AcReqGetFirstParameter and AcReqGetNextParameter to get the parameter names.

Description

Use AcReqGetDefaultValueInteger to get the default value of a parameter as an integer. The default value is the value defined by the programmer at design time. This value is used if the user does not supply a value when the report is run. Parameters defined as required always have default values. A default value is constant and independent of the value set by a user through the Requester.

When calling AcReqGetDefaultValueInteger, the parameter you specify as an argument must be of type Integer. If you specify a parameter of any other type, AcReqGetDefaultValueInteger returns the default value for that type. If you want to pass an argument of any type, use AcReqGetDefaultValueStr. However, the value AcReqGetDefaultValueStr returns is always a string.

Use AcReqGetParmType to check the data type of a parameter.

Return value

The default value of the specified parameter as an integer.


See also

AcReqGetDefaultValueStr

AcReqGetFirstParameter

AcReqGetNextParameter

AcReqGetParmType


AcReqGetDefaultValueString

See also

Returns the default value of the specified parameter as a string.

Syntax

Basic: Function AcReqGetDefaultValueString( fileNumber As Long, parmName As String ) As String

C/C++: BSTR AcReqGetDefaultValueString( long fileNumber, LPCSTR parmName )

fileNumber

The file number of the .ROV or .ROX file you opened with AcReqReadFile.

parmName

The name of the parameter whose default value you want. If you do not know the names of the parameters, use AcReqGetFirstParameter and AcReqGetNextParameter to get the parameter names.

Description

Use AcReqGetDefaultValueString to get the default value of a parameter as a string. The default value is the value defined by the programmer at design time. This value is used if the user does not supply a value when the report is run. Parameters defined as required always have default values. A default value is constant and independent of the value set by a user through the Requester.

When calling AcReqGetDefaultValueString, the parameter you specify as an argument must be of type String. If you specify a parameter of any other type, AcReqGetDefaultValueString returns the default value for that type. If you want to pass an argument of any type, use AcReqGetDefaultValueStr. However, the value AcReqGetDefaultValueStr returns is always a string.

Use AcReqGetParmType to check the data type of a parameter.

Return value

The default value of the specified parameter as a string.


See also

AcReqGetDefaultValueStr

AcReqGetFirstParameter

AcReqGetNextParameter

AcReqGetParmType


AcReqGetDefaultValueStr

See also

Returns the default value of the specified parameter as a string.

Syntax

Basic: Function AcReqGetDefaultValueStr( fileNumber As Long, parmName As String ) As String

C/C++: BSTR AcReqGetDefaultValueStr( long fileNumber, LPCSTR parmName)

fileNumber

The file number of the .ROV or .ROX file you opened with AcReqReadFile.

parmName

The name of the parameter whose default value you want. If you do not know the names of the parameters, use AcReqGetFirstParameter and AcReqGetNextParameter to get the parameter names.

Description

Use AcReqGetDefaultValueStr to get the default value of any parameter as a string. The parameter you specify as an argument can be of any type. To get the default value as the type with which the parameter was declared, use type-specific functions such as AcReqGetDefaultValueInteger or AcReqGetDefaultValueCurrency.

The default value is the value defined by the programmer at design time. This value is used if the user does not supply a value when the report is run. Parameters defined as required always have default values. A default value is constant and independent of the value set by a user through the Requester.

Return value

The default value of the specified parameter as a string.


See also

AcReqGetDefaultValueCurrency

AcReqGetDefaultValueDate

AcReqGetDefaultValueDouble

AcReqGetDefaultValueInteger

AcReqGetDefaultValueString

AcReqGetFirstParameter

AcReqGetNextParameter

AcReqGetParmType


AcReqGetError

See also

Returns the error number of the last error that occurred during an API function call.

Syntax

Basic: Function AcReqGetError( fileNumber As Long ) As Long

C/C++: long AcReqGetError( long fileNumber )

fileNumber

The file number of an .ROV or .ROX file you opened with AcReqReadFile.

Description

Use AcReqGetError to check for error conditions and return the error number. The following table lists the error numbers that AcReqGetError can return. To get the error string, use AcReqGetErrorString.

Error number	Error string
00	No error.
01	Could not find file number.
02	File not an .ROX or .ROV file.
03	Could not save .ROV file.
04	Could not close file.
05	Error while generating report.
06	There are no groups in the file.
07	There are no more groups in the file.
08	There is no group by given name.
09	There are no parameters in group specified by given name.
10	There are no more parameters in group specified by given name.
11	There is no parameter by specified name.
12	Type of parameter not found. Using default of string.
13	Could not set printer name.
14	Could not set printer property.
15	Could not open .ROX file.
16	Could not open .ROV file.
17	Not connected with server.
18	Could not find object on server.
19	Could not connect to the server.
20	Invalid connection handle.
21	Invalid request handle.
22	Invalid file read from server.
23	Could not find .ROV file on server.
24	Could not find .ROI file on server.
25	Could not generate request on server.
26	Cannot run report locally, not in Actuate Environment.
27	Operation not supported in 16 bit.
28	Illegal combination of options.
29	File must be of type .ROI.
30	Could not print report.
31	Could not find related .ROX.
32	Error interfacing with an existing Actuate Viewer.
33	Operation not supported through the report server.
34	Unable to set .ROV dependency.
35	Error retrieving object properties.
36	Error while reading object from server.
37	Could not find related .ROX object.
38	Could not find .ROX file on server.
39	Error getting object ID.
40	Unable to submit print request.
Return value

The error number of the last error.


See also

AcReqGetErrorString


AcReqGetErrorString

See also

Returns a string that describes the last error that occurred during an API function call.

Syntax

Basic: Function AcReqGetErrorString( fileNumber As Long ) As String

C/C++: BSTR AcReqGetErrorString( long fileNumber )

fileNumber

The file number of an .ROV or .ROX file you opened with AcReqReadFile.

Description

Use AcReqGetErrorString to check for error conditions and return a description of the error. To get the error number, use AcReqGetError. For a list of the error strings that AcReqGetErrorString can return, see AcReqGetError.

Return value

The error string of the last error.


See also

AcReqGetError


AcReqGetFirstGroup

See also

Returns the name of the first parameter group in the specified parameter value (.ROV) file or parameter definition section of the specified .ROX file.

Syntax

Basic: Function AcReqGetFirstGroup( fileNumber As Long ) As String

C/C++: BSTR AcReqGetFirstGroup( long fileNumber )

fileNumber

The file number of the .ROV or .ROX file you opened with AcReqReadFile.

Description

Use AcReqGetFirstGroup in conjunction with AcReqGetNextGroup, AcReqGetFirstParameter, and AcReqGetNextParameter to get information about the organization of parameters in a specified .ROV or .ROX file. If you are building a custom requestor interface in a Visual Basic form, for example, you can use the strings that these functions return to create a structure similar to the Requester interface in the Developer Workbench.

Parameters are typically organized into groups for ease of use. For example, CustomerName, CustomerPhone, and Credit_Rank might be parameters in a Customer parameters group, and City and State might be parameters in an Office parameters group.

If there are no parameter groups, the parameters have an empty string (" ") as their group name.

Return value

The name of the first parameter group in the specified .ROV or .ROX file, if a group exists.

An empty string if there are no groups or if an error occurred.


See also

AcReqGetFirstParameter

AcReqGetNextGroup

AcReqGetNextParameter


AcReqGetFirstParameter

See also

Returns the name of the first parameter in the specified parameter group.

Syntax

Basic: Function AcReqGetFirstParameter( fileNumber As Long, parmGroup As String ) As String

C/C++: BSTR AcReqGetFirstParameter( long fileNumber, LPCSTR parmGroupName )

fileNumber

The file number of the .ROV or .ROX file you opened with AcReqReadFile.

parmGroup

The name of the parameter group in which to find the first parameter. If you do not know the name of parameter groups, use AcReqGetFirstGroup and AcReqGetNextGroup to get the group names. To get parameters that do not belong in a group, specify an empty string for this argument.

Description

Use AcReqGetFirstParameter in conjunction with AcReqGetNextParameter, AcReqGetFirstGroup, and AcReqGetNextGroup to get information about the organization of parameters in a specified .ROV or .ROX file. If you are building a custom requestor interface in a Visual Basic form, for example, you can use the strings that these functions return to create a structure similar to the Requester interface in the Developer Workbench.

Return value

The name of the first parameter in the specified parameter group.

An empty string if there are no parameters or if an error occurred.


See also

AcReqGetFirstGroup

AcReqGetNextGroup

AcReqGetNextParameter


AcReqGetHidden

See also

Returns True or False, depending on whether or not the parameter was defined as hidden.

Syntax

Basic: Function AcReqGetHidden( fileNumber As Long, parmName As String) As Boolean

C/C++: VBBOOL AcReqGetHidden( long fileNumber, LPCSTR parmName )

fileNumber

The file number of the .ROV or .ROX file you opened with AcReqReadFile.

parmName

The name of the parameter whose hidden attribute you want. If you do not know the names of the parameters, use AcReqGetFirstParameter and AcReqGetNextParameter to get the parameter names.

Description

Use AcReqGetHidden to find out if a parameter was defined as hidden. If a parameter is hidden, users can set the parameter value only through code instead of through the Requester. For example, programmers might define a path name parameter as hidden if they do not want users to change its value.

Return value

True if the parameter was defined as hidden.

False if the parameter was designed to appear in the Requester.


See also

AcReqGetFirstParameter

AcReqGetNextParameter


AcReqGetHideText

See also

Returns True or False, depending on whether the parameter was defined to display asterisks or actual text as users type the value in the Requester.

Syntax

Basic: Function AcReqGetHideText( fileNumber As Long, parmName As String ) As Boolean

C/C++: VBBOOL AcReqGetHideText( long fileNumber, LPCSTR parmName )

fileNumber

The file number of the .ROV or .ROX file you opened with AcReqReadFile.

parmName

The name of the parameter whose hide text attribute you want. If you do not know the names of the parameters, use AcReqGetFirstParameter and AcReqGetNextParameter to get the parameter names.

Description

Use AcReqGetHideText to find out if a parameter was defined to display asterisks or actual text as users type the value in the Requester. If the hide text attribute is True, Actuate displays asterisks as users type the parameter value.

Return value

True if the parameter was defined to display asterisks as users type the value.

False if the parameter was defined to display the text that users type.


See also

AcReqGetFirstParameter

AcReqGetNextParameter


AcReqGetNextGroup

See also

Returns the name of the next parameter group in the specified parameter value (.ROV) file or parameter definition section of the specified .ROX file.

Syntax

Basic: Function AcReqGetNextGroup( fileNumber As Long ) As String

C/C++: BSTR AcReqGetNextGroup( long fileNumber )

fileNumber

The file number of the .ROV or .ROX file you opened with AcReqReadFile.

Description

Use AcReqGetNextGroup in conjunction with AcReqGetFirstGroup, AcReqGetFirstParameter, and AcReqGetNextParameter to get information about the organization of parameters in a specified .ROV or .ROX file. You must call AcReqGetFirstGroup before calling AcReqGetNextGroup. To get all the names of the parameter groups, call AcReqGetNextGroup until it returns an empty string, indicating that it has returned the last parameter group.

If you are building a custom requester interface in a Visual Basic form, for example, you can use the strings that these functions return to create a structure similar to the Requester interface in the Developer Workbench.

Parameters are typically organized into groups for ease of use. For example, CustomerName, CustomerPhone, and Credit_Rank might be parameters in a Customer parameters group, and City and State might be parameters in an Office parameters group.

Return value

The name of the next group in the specified .ROV or .ROX file, if there is another parameter group.

An empty string if there are no more groups or if an error occurred.


See also

AcReqGetFirstGroup

AcReqGetFirstParameter

AcReqGetNextParameter


AcReqGetNextParameter

See also

Returns the name of the next parameter in the specified parameter group.

Syntax

Basic: Function AcReqGetNextParameter( fileNumber As Long, parmGroup As String ) As String

C/C++: BSTR AcReqGetNextParameter( long fileNumber, LPCSTR parmGroup)

fileNumber

The file number of the .ROV or .ROX file you opened with AcReqReadFile.

parmGroup

The name of the parameter group in which to find the next parameter. If you do not know the name of parameter groups, use AcReqGetFirstGroup and AcReqGetNextGroup to get the group names. To get parameters that do not belong in a group, specify an empty string for this argument.

Description

Use AcReqGetNextParameter in conjunction with AcReqGetFirstParameter, AcReqGetFirstGroup, and AcReqGetNextGroup to get information about the organization of parameters in a specified .ROV or .ROX file. You must call AcReqGetFirstParameter before calling AcReqGetNextParameter. To get all the names of the parameters in a group, call AcReqGetNextParameter until it returns an empty string, indicating that it has returned the last parameter.

If you are building a custom requestor interface in a Visual Basic form, for example, you can use the strings that these functions return to create a structure similar to the Requester interface in the Developer Workbench.

Return value

The name of the next parameter in the specified parameter group.

An empty string if there are no more parameters or if an error occurred.


See also

AcReqGetFirstGroup

AcReqGetFirstParameter

AcReqGetNextGroup


AcReqGetParmType

See also

Returns the data type of the specified parameter as a string.

Syntax

Basic: Function AcReqGetParmType( fileNumber As Long, parmName As String ) As String

C/C++: BSTR AcReqGetParmType( long fileNumber, LPCSTR parmName )

fileNumber

The file number of the .ROV or .ROX file you opened with AcReqReadFile.

parmName

The name of the parameter whose data type you want. If you do not know the names of the parameters, use AcReqGetFirstParameter and AcReqGetNextParameter to get the parameter names.

Description

Use AcReqGetParmType to find out the parameter's data type. You can use this information to determine how to set a parameter value. You can also use this information to determine which function to use to get a parameter's default value or its current value.

You set parameter values with functions such as AcReqSetValueDate, AcReqSetValueString, and so on. You get the default values for parameters with functions such as AcReqGetDefaultValueDate, AcReqGetDefaultValueString, and so on. You get a parameter's current value with functions such as AcReqGetValueDate, AcReqGetValueString, and so on.

Return value

The data type of the specified parameter.


See also

AcReqGetFirstParameter

AcReqGetNextParameter

AcReqGetType


AcReqGetRequired

See also

Returns True or False, depending on whether the parameter was defined as required or optional.

Syntax

Basic: Function AcReqGetRequired( fileNumber As Long, parmName As String ) As Boolean

C/C++: VBBOOL AcReqGetRequired( long fileNumber, LPCSTR parmName )

fileNumber

The file number of the .ROV or .ROX file you opened with AcReqReadFile.

parmName

The name of the parameter whose required attribute you want. If you do not know the names of the parameters, use AcReqGetFirstParameter and AcReqGetNextParameter to get the parameter names.

Description

Use AcReqGetRequired to find out if a parameter was defined as required or optional. If a parameter is required, Actuate does not generate the report without a value for the parameter.

Use the boolean value that AcReqGetRequired returns to determine if you need to set a parameter value before generating a report with AcReqGenerateReport. You set parameter values with functions such as AcReqSetValueString, AcReqSetValueDate, and so on.

Return value

True if the parameter is required to generate the report.

False if the parameter is optional.


See also

AcReqGetFirstParameter

AcReqGetNextParameter


AcReqGetRoxNameForRoi

Gets the name of the ROX file associated with a specified ROI file.

Syntax

Basic: Function AcReqGetRoxNameForRoi( roiName As String) as String

C/C++: BSTR AcReqGetRoxNameForRoi( const char *roiName )

roiName

The name of the ROI File.

Description

Use AcReqGetRoxNameForRoi to get the name of the ROX file needed to view or print the given ROI file.

AcReqGetRoxNameForRoi is a member of both the Requester and LRX APIs.

Return value

Returns the base name of the required ROX file or an empty string if the ROI file cannot be opened.


AcReqGetType

See also

Returns the data type of the specified parameter as an enumeration.

Syntax

Basic: Function AcReqGetType( fileNumber As Long, parmName As String ) As Long

C/C++: long AcReqGetType( long fileNumber, LPCSTR parmName )

fileNumber

The file number of the .ROV or .ROX file you opened with AcReqReadFile.

parmName

The name of the parameter whose data type you want. If you do not know the names of the parameters, use AcReqGetFirstParameter and AcReqGetNextParameter to get the parameter names.

Description

Use AcReqGetType to find out the parameter's data type. This method returns an enumeration of the data type rather than a text string. You can use the data type to determine how to set a parameter value. You can also use this information to determine which function to use to get a parameter's default value or its current value.

You get the default values for parameters with AcReqGetDefaultValueDate, AcReqGetDefaultValueString, and so on. You set parameter values with AcReqSetValueDate, AcReqSetValueString, and so on. You get a parameter's current value with AcReqGetValueDate, AcReqGetValueString, and so on.

Return value

An enumeration of the data type.

Data type	Enumeration
AC_REQ_UNKNOWN	0
AC_REQ_STRING	1
AC_REQ_INTEGER	2
AC_REQ_DOUBLE	3
AC_REQ_DATETIME	4
AC_REQ_CURRENCY	5


See also

AcReqGetFirstParameter

AcReqGetNextParameter

AcReqGetParmType


AcReqGetValueCurrency

See also

Returns the current value of the specified parameter as a currency.

Syntax

Basic: Function AcReqGetValueCurrency( fileNumber As Long, parmName As String) As Currency

C/C++: REQCYTYPE AcReqGetValueCurrency( long fileNumber, LPCSTR parmName )

fileNumber

The file number of the .ROV or .ROX file you opened with AcReqReadFile.

parmName

The name of the parameter whose current value you want. If you do not know the names of the parameters, use AcReqGetFirstParameter and AcReqGetNextParameter to get the parameter names.

Description

Use AcReqGetValueCurrency to get the current value of a parameter as a currency. The current value is the value last entered in the .ROV file. If you are accessing an .ROX file, the current value is the default value defined by the programmer at design time.

When calling AcReqGetValueCurrency, the parameter you specify as an argument must be of type Currency. If you specify a parameter of any other type, AcReqGetValueCurrency returns the default value for that type. If you want to pass an argument of any type, use AcReqGetValueStr. The value AcReqGetValueStr returns is always a string.

Use AcReqGetParmType to check the data type of a parameter.

Return value

The current value of the specified parameter as a currency.


See also

AcReqGetFirstParameter

AcReqGetNextParameter

AcReqGetParmType

AcReqGetValueStr


AcReqGetValueDate

See also

Returns the current value of the specified parameter as a date.

Syntax

Basic: Function AcReqGetValueDate( fileNumber As Long, parmName As String) As Date

C/C++: double AcReqGetValueDate( long fileNumber, LPCSTR parmName )

fileNumber

The file number of the .ROV or .ROX file you opened with AcReqReadFile.

parmName

The name of the parameter whose current value you want. If you do not know the names of the parameters, use AcReqGetFirstParameter and AcReqGetNextParameter to get the parameter names.

Description

Use AcReqGetValueDate to get the current value of a parameter as a date. The current value is the value last entered in the .ROV file. If you are accessing an .ROX file, the current value is the default value defined by the programmer at design time.

When calling AcReqGetValueDate, the parameter you specify as an argument must be of type Date. If you specify a parameter of any other type, AcReqGetValueDate returns the default value for that type. If you want to pass an argument of any type, use AcReqGetValueStr. The value AcReqGetValueStr returns is always a string.

Use AcReqGetParmType to check the data type of a parameter.

Return value

The current value of the specified parameter as a date.

The following example shows how to work with dates expressed as C++ doubles:

    int fileNumber;

    double inDate, outDate;

    COleDateTime oleDate( 67, 12, 6, 0, 0, 0 ); // y   m  d  h  m  s

    inDate = oleDate;

    fileNumber = AcReqReadFile( szSourceRox );

    outDate = AcReqGetValueDate(fileNumber, "aDate");

    oleDate = outDate;

    AcReqSetValueDate( fileNumber, "aDate", inDate );

    AcReqCloseFile( fileNumber );


See also

AcReqGetFirstParameter

AcReqGetNextParameter

AcReqGetParmType

AcReqGetValueStr


AcReqGetValueDouble

See also

Returns the current value of the specified parameter as a double.

Syntax

Basic: Function AcReqGetValueDouble( fileNumber As Long, parmName As String) As Double

C/C++: double AcReqGetValueDouble( long fileNumber, LPCSTR parmName )

fileNumber

The file number of the .ROV or .ROX file you opened with AcReqReadFile.

parmName

The name of the parameter whose current value you want. If you do not know the names of the parameters, use AcReqGetFirstParameter and AcReqGetNextParameter to get the parameter names.

Description

Use AcReqGetValueDouble to get the current value of a parameter as a double. The current value is the value last entered in the .ROV file. If you are accessing an .ROX file, the current value is the default value defined by the programmer at design time.

When calling AcReqGetValueDouble, the parameter you specify as an argument must be of type Double. If you specify a parameter of any other type, AcReqGetValueDouble returns the default value for that type. If you want to pass an argument of any type, use AcReqGetValueStr. The value AcReqGetValueStr returns is always a string.

Use AcReqGetParmType to check the data type of a parameter.

Return value

The current value of the specified parameter as a double.


See also

AcReqGetFirstParameter

AcReqGetNextParameter

AcReqGetParmType

AcReqGetValueStr


AcReqGetValueInteger

See also

Returns the current value of the specified parameter as an integer.

Syntax

Basic: Function AcReqGetValueInteger( fileNumber As Long, parmName As String) As Integer

C/C++: long AcReqGetValueInteger( long fileName, LPCSTR parmName )

fileNumber

The file number of the .ROV or .ROX file you opened with AcReqReadFile.

parmName

The name of the parameter whose current value you want. If you do not know the names of the parameters, use AcReqGetFirstParameter and AcReqGetNextParameter to get the parameter names.

Description

Use AcReqGetValueInteger to get the current value of a parameter as an integer. The current value is the value last entered in the .ROV file. If you are accessing an .ROX file, the current value is the default value defined by the programmer at design time.

When calling AcReqGetValueInteger, the parameter you specify as an argument must be of type Integer. If you specify a parameter of any other type, AcReqGetValueInteger returns the default value for that type. If you want to pass an argument of any type, use AcReqGetValueStr. The value AcReqGetValueStr returns is always a string.

Use AcReqGetParmType to check the data type of a parameter.

Return value

The current value of the specified parameter as an integer.


See also

AcReqGetFirstParameter

AcReqGetNextParameter

AcReqGetParmType

AcReqGetValueStr


AcReqGetValueString

See also

Returns the current value of the specified parameter as a string.

Syntax

Basic: Function AcReqGetValueString( fileNumber As Long, parmName As String) As String

C/C++: BSTR AcReqGetValueString( long fileNumber, LPCSTR parmName )

fileNumber

The file number of the .ROV or .ROX file you opened with AcReqReadFile.

parmName

The name of the parameter whose current value you want. If you do not know the names of the parameters, use AcReqGetFirstParameter and AcReqGetNextParameter to get the parameter names.

Description

Use AcReqGetValueString to get the current value of a parameter as a string. The current value is the value last entered in the .ROV file. If you are accessing an .ROX file, the current value is the default value defined by the programmer at design time.

When calling AcReqGetValueString, the parameter you specify as an argument must be of type String. If you specify a parameter of any other type, AcReqGetValueString returns the default value for that type. If you want to pass an argument of any type, use AcReqGetValueStr. The value AcReqGetValueStr returns is always a string.

Use AcReqGetParmType to check the data type of a parameter.

Return value

The default value of the specified parameter as a string.


See also

AcReqGetFirstParameter

AcReqGetNextParameter

AcReqGetParmType

AcReqGetDefaultValueStr


AcReqGetValueStr

See also

Returns the current value of the specified parameter as a string.

Syntax

Basic: Function AcReqGetValueStr( fileNumber As Long, parmName
As String ) As String

C/C++: BSTR AcReqGetValueStr( long fileNumber, LPCSTR parmName )

fileNumber

The file number of the .ROV or .ROX file you opened with AcReqReadFile.

parmName

The name of the parameter whose current value you want. If you do not know the names of the parameters, use AcReqGetFirstParameter and AcReqGetNextParameter to get the parameter names.

Description

Use AcReqGetValueStr to get the current value of a parameter as a string. The current value is the value last entered in the .ROV file. If you are accessing an .ROX file, the current value is the default value defined by the programmer at design time.

Use AcReqGetValueStr to get the current value of any parameter as a string. The parameter you specify as an argument can be of any type. To get the current value as the type with which the parameter was declared, use type-specific functions such as AcReqGetValueInteger or AcReqGetValueCurrency.

Return value

The current value of the specified parameter as a string.


See also

AcReqGetFirstParameter

AcReqGetNextParameter

AcReqGetParmType

AcReqGetValueCurrency

AcReqGetValueDate

AcReqGetValueDouble

AcReqGetValueInteger

AcReqGetValueString


AcReqInitialize

See also

Initializes the DLLs.

Syntax

Basic: Function AcReqInitialize( ) As Long

C/C++: long AcReqInitialize( )

Description

The first API function you call must be AcReqInitialize. AcReqInitialize initializes the DLLs and prepares the Requester API for use in your program. When you no longer need to use the Requester API, call AcReqUnInitialize to close the library and free resources used by the API.

AcReqInitialize is a member of both the Requester and LRX APIs.

Return value

A handle to the initialized session.


See also

AcReqUninitialize


AcReqInstallAfc

Installs the specified AFC file.

Syntax

Basic: Function AcReqInstallAfc( afcName As String) As Boolean

C/C++: VBBOOL AcReqInstallAfc( const char *afcName )

afcName

The fully qualified path and file name of the AFC file.

Description

Installs the given AFC file to Actuate's AFC directory. The function assumes that the base name of this file is to remain unchanged. For example, the file might be c:/temp/afc888.rox. This function will install afc888.rox into the product afc directory. If the file is on the same partition as the AFC directory, then Actuate moves the file into the cache. If the file is on a different partition, Actuate copies the file to the cache, then deletes the source file. Specify the Actuate client with AcSelectClient before calling AcReqInstallAfc.

AcReqInstallAfc is a member of both the Requester and LRX APIs.

Return value

True if the specified AFC file was successfully installed, False if not.


AcReqIsAfcInstalled

Asks if the specified AFC file is installed.

Syntax

Basic: Function AcReqIsAfcInstalled( afcName As String) As Boolean

C/C++: VBBOOL AcReqIsAfcInstalled( const char *afcName )

afcName

The name of an AFC file, such as AFC853.ROX.

Description

Asks if the given AFC file is installed in the Actuate installation. Since each Actuate executable has its own AFC directory, the application must have already set the executable name using the AcReqSetEUDTPath function. AcReqIsAfcInstalled is a member of both the Requester and LRX API.

Return value

Returns True if the file is installed in the AFC directory, False if not installed or if an error occurs.


AcReqPrintReport

See also

Prints the specified report (.ROI).

Syntax

Basic: Function AcReqPrintReport( filename As String, options As Long ) As Long

C/C++: long AcReqPrintReport( LPCSTR fileName, long options )

filename

The name of the report (.ROI) to print. Specify the full path name if the file is not in the current directory.

If the file resides on a server, use the following format:

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

For information about specifying server file names, see Specifying report server file names--Requester API.

options

A set of constants you can use to specify how the End User Desktop application runs. When specifying multiple options, use the plus (+) character between the options. The following table lists and describes the constants.

Constant	Description
AC_REQ_LAUNCH_ALWAYS	Runs a new instance of an End User Desktop application to print the report.
AC_REQ_LOCAL	Prints the report in the current instance of the Developer Workbench or End User Desktop.
AC_REQ_PRINT	Prints the generated report.
AC_REQ_ASYNC	Runs this process asynchronously; the function returns immediately and the report is printed in the background. If this constant is not specified, the function returns after the report is printed.
AC_REQ_HIDE	Does not display the End User Desktop application while it prints the report.
AC_REQ_STAY_OPEN	Keeps the End User Desktop application open after it prints the report. This option is ignored if the report is printed in the current instance of the End User Desktop.
The following are examples of how you specify options with AcReqPrintReport:

AcReqPrintReport( "detail.roi", AC_REQ_HIDE )

AcReqPrintReport( "detail.roi", AC_REQ_LAUNCH_ALWAYS+AC_REQ_HIDE )

The first call passes the name of the document file and a constant that represents a message to inhibit the display of the End User Desktop application while it prints the report. The second call also passes the name of the document file and constants that represent a message to run but not display a new instance of the End User Desktop application to print the report.

Description

Use AcReqPrintReport to print an existing report on a local system. To print a report immediately after you generate it with AcReqGenerateReport, use the AC_REQ_PRINT option in AcReqGenerateReport.

If you want to change the printer setup before printing the report, use the printer-related functions such as AcReqSetPrinterName, AcReqSetPrinterNumberCopies, and AcReqSetPrinterOrientation.

AcReqPrintReport is a member of both the Requester and LRX APIs. For the LRX API, you can use a printer defined on the local workstation.

Return value

0 if the report printed successfully.

Any number other than zero if the report did not print.


See also

AcReqSetPrinterCollate

AcReqSetPrinterColor

AcReqSetPrinterDuplex

AcReqSetPrinterFormName

AcReqSetPrinterName

AcReqSetPrinterNumberCopies

AcReqSetPrinterOrientation

AcReqSetPrinterPaperSize

AcReqSetPrinterScale


AcReqPrintReportEx

Prints a report when the ROX name for the ROI is different than the name stored within the ROI.

Syntax

Basic: Function AcReqPrintReportEx( roiName As String, options As Long, roxName As String) As Long

C/C++: long AcReqPrintReportEx( const char *roiName, long options, const char *roxName )

roiName

The name of the roi file.

options

Print options.

roxName

Optional name or Object ID of the ROX file for the ROI.

Description

ROI files store the absolute path name to their corresponding ROX file. Sometimes this name is not useful. For example, if the ROI comes from the server, the application must use the Object ID of the ROX to identify the ROX file instead of the ROX file name stored in the ROI.

Use this function to print an ROI when the ROX name for that ROI is different than the name stored within the ROI. The roxName parameter can either be an ROX name, or an Object ID. If the roxName is just an roxName itself with no path (e.g. "myReport.rox") then Actuate will first check for the ROX in the file cache, then in the current working directory. If the roxName contains a path, then Actuate does not check the cache. If the roxName is an object ID, then Actuate only checks the file cache.

AcReqPrintReportEx is a member of both the Requester and LRX APIs.

Return value

0 for success, error number for failure.


AcReqReadFile

Opens a parameter value (.ROV) file or a report executable (.ROX) file.

Syntax

Basic: Function AcReqReadFile( filename As String ) As Long

C/C++: long AcReqReadFile( LPCSTR fileName )

filename

The name of the .ROV or .ROX file to open. Specify the full path name if the file is not in the current directory.

If the file resides on a server, use the following format:

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

For information about specifying server file names, see Specifying report server file names--Requester API.

Description

Use AcReqReadFile to open an .ROV or .ROX file to change or get information about parameter values before generating a report. The .ROV contains parameter values that users set when they run a report. The .ROX file contains the parameter definitions. If you open an .ROX, the default values assigned to the parameters at design time are read into memory.

You can call AcReqReadFile multiple times to open multiple files. Each file is assigned a unique file number. Keep track of the file number--many API functions need this number as an argument.

Return value

The file number of the open file.


AcReqReportStatus

See also

Returns the status of a specified report-generation request on the server.

Syntax

Basic: Sub AcReqReportStatus( RequestHandle As Long ) As Integer

C/C++: UNSIGNED SHORT AcReqReportStatus( long RequestHandle )

RequestHandle

The value that identifies a specific report-generation request. This value is returned by AcReqGenerateReport when a request is issued successfully on a server. Only values greater than 1024 are valid.

Description

Call AcReqReportStatus to determine the status of a report-generation request on the server. For example, getting the generation status is useful before calling AcReqViewReport to display the completed report. The status information is also useful in error-handling routines.

Return value

Value	Description
0	The generation process is completed.
1	The generation process is active.
2	An error occurred during report generation.
3	An unknown, non-generation error occurred. For example, the argument passed to AcReqReportStatus is invalid.


See also

AcReqGetError

AcReqGetErrorString


AcReqSelectClient

See also

Select the client product to use for client-side viewing, printing, and running reports.

Syntax

Basic: Function AcReqSelectClient( clientCode As Integer, installDir As String) As Boolean

C/C++: VBBOOL AcReqSelectClient( int clientCode, const char *installDir )

clientCode

Client code, as follows:

AC_NS_LRX	LRX for Netscape Navigator and Communicator
AC_MS_LRX	LRX for Microsoft Internet Explorer
AC_EUDT	End User Desktop
AC_VIEWER	Free Viewer
AC_DWB	Developer Workbench
AC_ADT	Administrator Desktop
installDir

The directory into which Actuate was installed, often C:/Actuate. This parameter is optional for the LRX products, since the LRX's use registry entries to identify the install directory.)

Description

Use this function to select the Actuate client product to use for client-side viewing, printing and running reports. Not all products can perform all operations.

AcReqSelectClient supersedes AcReqSetEUDTPath. You must call this function before you use the file cache functions or the AFC installation functions. You must call this function or its predecessor, AcReqSetEUDTPath, before you call the functions for printing, viewing or running a report locally.

AcReqSetClient is a member of both the Requester and LRX APIs.

Return value

True if the client code and install directory are valid, False otherwise.


See also

AcReqSetEUDTPath


AcReqSetCacheSize

Changes the size of the Actuate cache.

Syntax

Basic: Function AcReqSetCacheSize( newSize as Integer) As Boolean

C/C++: VBBOOL AcReqSetCacheSize( unsigned int newSize )

newSize

Cache size for local files. The default is 20.

Description

Use this function to change the size of the Actuate cache. You can enlarge the cache size if your application would benefit by keeping more files locally. Specify the Actuate client with AcSelectClient before calling AcReqSetCacheSize.

AcReqSetCacheSize is a member of both the Requester and LRX APIs.

Return value

True if the cache size was successfully set, False if not.


AcReqSetDefaultPrinter

See also

Specifies that the system's default printer will be used for the next print job.

Syntax

Basic: Sub AcReqSetDefaultPrinter( )

C/C++: void AcReqSetDefaultPrinter( )

Description

Use AcReqSetDefaultPrinter to revert to the system's default printer after you send a print job to another printer specified with AcReqSetPrinterName.


See also

AcReqPrintReport

AcReqSetPrinterName


AcReqSetEUDTPath

See also

Specifies the location of the End User Desktop application to use to generate a report, or the location of the Viewer application to use to view a report.

Syntax

Basic: Sub AcReqSetEUDTPath( pathName As String )

C/C++: void AcReqSetEUDTPath( LPCSTR pathName )

pathName

The location of the End User Desktop or Viewer application to run.

The following are examples of how you specify the End User Desktop and Viewer application to run:

AcReqSetEUDTPath( "c:\actuate\eudt\bin\runview.exe" )

AcReqSetEUDTPath( "c:\actuate\viewer\bin\viewer.exe" )

Description

Use AcReqSetEUDTPath to specify the End User Desktop to run to generate a report. The following are the times when you need to call AcReqSetEUDTPath:

•	If you run the End User Desktop remotely, for example, from a Visual Basic application.

•	If you do not specify the AC_REQ_LOCAL option with AcReqGenerateReport. The AC_REQ_LOCAL option specifies that the report be generated in the current instance of the Developer Workbench or End User Desktop.

If you are opening a report for viewing, you can use AcReqSetEUDTPath to specify the End User Desktop or Viewer application to use.

AcReqSetEUDTPath is a member of both the Requester and LRX APIs.


See also

AcReqGenerateReport

AcReqViewReport

AcReqSelectClient


AcReqSetPrinterCollate

See also

Specifies whether or not the printer collates multiple copies of a document.

Syntax

Basic: Sub AcReqSetPrinterCollate( collate As Boolean )

C/C++: void AcReqSetPrinterCollate( VBBOOL collate )

collate

True collates multiple copies of a document.

Description

Before sending a print job, use AcReqSetPrinterCollate to specify whether to collate documents. Turn on the collate feature to print one complete copy before starting the next copy. To print a report, use AcReqPrintReport.


See also

AcReqPrintReport


AcReqSetPrinterColor

See also

Specifies if the report is printed in color.

Syntax

Basic: Sub AcReqSetPrinterColor( color As Boolean )

C/C++: void AcReqSetPrinterColor( VBBOOL color )

color

True prints the report in color.

Description

If you have a color printer, use AcReqSetPrinterColor to specify whether to print in color. To print a report, use AcReqPrintReport.


See also

AcReqPrintReport


AcReqSetPrinterDuplex

See also

Specifies if the printer prints on both sides or one side of the paper.

Syntax

Basic: Sub AcReqSetPrinterDuplex( duplex As Integer )

C/C++: void AcReqSetPrinterDuplex( short duplex )

duplex

The duplex mode. Specify one of the following integer values:

Value	Duplex mode
1	Simplex mode (no duplex)
2	Horizontal duplex mode
3	Vertical duplex mode
Description

If your printer supports duplexing, use AcReqSetPrinterDuplex before sending a print job to specify whether the printer prints on both sides or one side of the paper. AcReqSetPrinterDuplex works on local files or those stored on a Windows NT server. You cannot use this function on a UNIX server. To print a report, use AcReqPrintReport.


See also

AcReqPrintReport


AcReqSetPrinterFormName

See also

Specifies the paper size by its type, for example, Letter, Legal, or Executive.

Syntax

Basic: Sub AcReqSetPrinterFormName( formName As String )

C/C++: void AcReqSetPrinterFormName( LPCSTR formName )

formName

The type of paper, such as letter, legal, or others. Check your printer documentation for valid settings.

Description

Before sending a print job, use AcReqSetPrinterFormName to specify the paper size, by type, on which to print. To specify the paper size with actual size dimensions, use AcReqSetPrinterPaperSize. To print a report, use AcReqPrintReport.


See also

AcReqPrintReport


AcReqSetPrinterName

See also

Specifies the printer to use.

Syntax

Basic: Sub AcReqSetPrinterName( printerName As String )

C/C++: void AcReqSetPrinterName( LPCSTR printerName )

printerName

The name of the printer to use.

Description

Before sending a print job, use AcReqSetPrinterName to specify a different printer from the default one. If you want to use the system's default printer after sending a print job to the printer you specified with this function, call AcReqSetDefaultPrinter. To print a report, use AcReqPrintReport.

AcReqSetPrinterName is a member of both the Requester and LRX APIs. For the LRX API, specify a printer known to the local workstation.


See also

AcReqPrintReport

AcReqSetDefaultPrinter


AcReqSetPrinterNumberCopies

See also

Specifies the number of copies to print.

Syntax

Basic: Sub AcReqSetPrinterNumberCopies( numCopies As Integer )

C/C++: void AcReqSetPrinterNumberCopies( short numCopies )

numCopies

The number of copies to print.

Description

Before sending a print job, use AcReqSetPrinterNumberCopies to change the default setting for number of copies to print. Use AcReqSetPrinterCollate to collate multiple copies of a document.

To print a report, use AcReqPrintReport.


See also

AcReqSetPrinterCollate

AcReqPrintReport


AcReqSetPrinterOrientation

See also

Sets the printer's page orientation to portrait or landscape.

Syntax

Basic: Sub AcReqSetPrinterOrientation( orientation As Integer )

C/C++: void AcReqSetPrinterOrientation( short orientation )

orientation

Use 1 for portrait, 2 for landscape.

Description

Before sending a print job, use AcReqSetPrinterOrientation to specify a different page orientation from the default one. To print a report, use AcReqPrintReport.


See also

AcReqPrintReport


AcReqSetPrinterPaperSize

See also

Specifies the paper size through length and width settings.

Syntax

Basic: Sub AcReqSetPrinterPaperSize( size As Integer, length As Integer, width As Integer)

C/C++: void AcReqSetPrinterPaperSize( short size, short length, short width )

size

An enum value from 1 to 68. Each value represents a different paper size. If you set the size argument, set the length and width arguments to zero. The following table lists the enum values for the size argument and the corresponding paper sizes.

Enum value	Paper size
1	Letter 8 1/2 x 11 in
2	Letter small 8 1/2 x 11in
3	Tabloid 11 x 17 in
4	Ledger 17 x 11 in
5	Legal 8 1/2  x 14 in
6	Statement 5 1/2 x 8 1/2 in
7	Executive 7 1/4 x 10 1/2 in
8	A3 sheet 297 x 420 mm
9	A4 sheet 210 x 297 mm
10	A4 Small 210 x 297 mm
11	A5 sheet 148 x 210 mm
12	B4 sheet 250 x 354 mm
13	B5 sheet 182 x 257 mm
14	Folio 8 1/2 x 13 in
15	Quarto 215 x 275 mm
16	10 x 14 in
17	11 x 17 in
18	Note 8 1/2 x 11 in
19	Envelope #9 3 7/8 x 8 7/8 in
20	Envelope #10 4 1/8 x 9 1/2 in
21	Envelope #11 4 1/2 x 10 3/8 in
22	Envelope #12 4 3/4 x 11 in
23	Envelope #14 5 x 11 1/2 in
24	C sheet 17 x 22 in
25	D sheet 22 x 34 in
26	E sheet 34 x 44 in
27	Envelope DL 110 x 220 mm
28	Envelope C5 162 x 229 mm
29	Envelope C3 324 x 458 mm
30	Envelope C4 229 x 324 mm
31	Envelope C6 114 x 162 mm
32	Envelope C65 114 x 229 mm
33	Envelope B4  250 x 353 mm
34	Envelope B5  176 x 250 mm
35	Envelope B6  176 x 125 mm
36	Envelope 110 x 230 mm
37	Envelope Monarch 3.875 x 7.5 in
38	6 3/4 Envelope 3 5/8 x 6 1/2 in
39	US Std Fanfold 14 7/8 x 11 in
40	German Std Fanfold 8 1/2 x 12 in
41	German Legal Fanfold 8 1/2 x 13 in
42	B4 (ISO) 250 x 353 mm
43	Japanese Postcard 100 x 148 mm
44	9 x 11 in
45	10 x 11 in
46	15 x 11 in
47	Envelope Invite 220 x 220 mm
48	RESERVED--DO NOT USE
49	RESERVED--DO NOT USE
50	Letter Extra 9 \275 x 12 in
51	Legal Extra 9 \275 x 15 in
52	Tabloid Extra 11.69 x 18 in
53	A4 Extra 9.27 x 12.69 in
54	Letter Transverse 8 \275 x 11 in
55	A4 Transverse 210 x 297 mm
56	Letter Extra Transverse 9\275 x 12 in
57	SuperA/SuperA/A4 227 x 356 mm
58	SuperB/SuperB/A3 305 x 487 mm
59	Letter Plus 8.5 x 12.69 in
60	A4 Plus 210 x 330 mm
61	A5 Transverse 148 x 210 mm
62	B5 (JIS) Transverse 182 x 257 mm
63	A3 Extra 322 x 445 mm
64	A5 Extra 174 x 235 mm
65	B5 (ISO) Extra 201 x 276 mm
66	A2 420 x 594 mm
67	A3 Transverse 297 x 420 mm
68	A3 Extra Transverse 322 x 445 mm
length, width

The physical length and width of the paper in tenths of a millimeter. If you set the length and width arguments, set the size argument to zero. To convert inches to tenths of a millimeter, multiply the number by 254. For example, to specify a paper size of 8.5 by 11 inches, specify 2159 (8.5 * 254) for the width argument, and 2794 (11 * 254) for the length argument.

Description

Before sending a print job, use AcReqSetPrinterPaperSize to specify the paper size on which to print. When working with a report server running on a Windows NT platform, you can specify either logical or physical paper size. On a UNIX server, you can only specify logical paper size.To print a report, use AcReqPrintReport.


See also

AcReqPrintReport


AcReqSetPrinterScale

See also

Specifies the size of the image to print.

Syntax

Basic: Sub AcReqSetPrinterScale( scale As Integer )

C/C++: void AcReqSetPrinterScale( short scale )

scale

The percentage of the original size at which to print. Check your printer documentation for the valid range.

Description

Before sending a print job, use AcReqSetPrinterScale to specify the size of the image to print. To print a report, use AcReqPrintReport.


See also

AcReqPrintReport


AcReqSetPrinterTray

See also

Specifies the printer tray for the paper source.

Syntax

Basic: Sub AcReqSetPrinterTray( tray as Short)

C/C++: void AcReqSetPrinterTray( short tray)

tray

The number of the printer tray.

Description

Before sending a print job, use AcReqSetPrinterTray to specify the paper tray for printing. To print a report, use AcReqPrintReport.


See also

AcReqPrintReport


AcReqSetRequestPriority

See also

Specifies the priority for report generation on the Report Server.

Syntax

Basic: Sub AcReqSetRequestPriority( priority as Long)

C/C++: void AcReqSetRequestPriority( long priority )

priority

The priority for report generation: from 0 - 1000.

Description

Call AcReqSetRequestPriority before generating a report to specify the priority level on the Report Server. The higher the number the greater the priority. The Report Server may restrict the priority to the range permitted for the current user.


See also

AcReqGenerateReport


AcReqSetValueCurrency

See also

Sets the value of the specified parameter as a currency.

Syntax

Basic: Sub AcReqSetValueCurrency( fileNumber As Long, parmName As String, value As Currency )

C/C++: void AcReqSetValueCurrency( long fileNumber, LPCSTR parmName, REQCYTYPE value )

fileNumber

The file number of the .ROV or .ROX file you opened with AcReqReadFile.

parmName

The name of the parameter whose value you want to set. If you do not know the names of the parameters, use AcReqGetFirstParameter and AcReqGetNextParameter to get the parameter names.

value

The currency value to assign to the parameter.

Description

Use AcReqSetValueCurrency to assign a currency value to a parameter. The parameter whose value you want to set must be of type Currency. Use AcReqGetParmType to check the data type of a parameter before setting its value.


See also

AcReqGetFirstParameter

AcReqGetNextParameter

AcReqGetParmType


AcReqSetValueDate

See also

Sets the value of the specified parameter as a date.

Syntax

Basic: Sub AcReqSetValueDate( fileNumber As Long, parmName As String, value As Date )

C/C++: void AcReqSetValueDate( long fileNumber, LPCSTR parmName, double value )

fileNumber

The file number of the .ROV or .ROX file you opened with AcReqReadFile.

parmName

The name of the parameter whose value you want to set. If you do not know the names of the parameters, use AcReqGetFirstParameter and AcReqGetNextParameter to get the parameter names.

value

The date value to assign to the parameter.

Description

Use AcReqSetValueDate to assign a date value to a parameter. The parameter whose value you want to set must be of type Date. Use AcReqGetParmType to check the data type of a parameter before setting its value.

The following example shows how to work with dates expressed as C++ doubles:

    int fileNumber;

    double inDate, outDate;

    COleDateTime oleDate( 67, 12, 6, 0, 0, 0 ); // y   m  d  h  m  s

    inDate = oleDate;

    fileNumber = AcReqReadFile( szSourceRox );

    outDate = AcReqGetDefaultValueDate(fileNumber, "aDate");

    oleDate = outDate;

    AcReqSetValueDate( fileNumber, "aDate", inDate );

    AcReqCloseFile( fileNumber );


See also

AcReqGetFirstParameter

AcReqGetNextParameter

AcReqGetParmType


AcReqSetValueDouble

See also

Sets the value of the specified parameter as a double.

Syntax

Basic: Sub AcReqSetValueDouble( fileNumber As Long, parmName As String, value As Double )

C/C++: void AcReqSetValueDouble( long fileNumber, LPCSTR parmName, double value )

fileNumber

The file number of the .ROV or .ROX file you opened with AcReqReadFile.

parmName

The name of the parameter whose value you want to set. If you do not know the names of the parameters, use AcReqGetFirstParameter and AcReqGetNextParameter to get the parameter names.

value

The double value to assign to the parameter.

Description

Use AcReqSetValueDouble to assign a double value to a parameter. The parameter whose value you want to set must be of type Double. Use AcReqGetParmType to check the data type of a parameter before setting its value.

For an example of how to set dates from C++ as doubles, see Using the Requester in a C++ application.


See also

AcReqGetFirstParameter

AcReqGetNextParameter

AcReqGetParmType


AcReqSetValueInteger

See also

Sets the value of the specified parameter as an integer.

Syntax

Basic: Sub AcReqSetValueInteger( fileNumber As Long, parmName As String, value As Integer )

C/C++: void AcReqSetValueInteger( long fileNumber, LPCSTR parmName, long value )

fileNumber

The file number of the .ROV or .ROX file you opened with AcReqReadFile.

parmName

The name of the parameter whose value you want to set. If you do not know the names of the parameters, use AcReqGetFirstParameter and AcReqGetNextParameter to get the parameter names.

value

The integer value to assign to the parameter.

Description

Use AcReqSetValueInteger to assign an integer value to a parameter. The parameter whose value you want to set must be of type Integer. Use AcReqGetParmType to check the data type of a parameter before setting its value.


See also

AcReqGetFirstParameter

AcReqGetNextParameter

AcReqGetParmType


AcReqSetValueString

See also

Sets the value of the specified parameter as a string.

Syntax

Basic: Sub AcReqSetValueString( fileNumber As Long, parmName As String, value As String )

C/C++: void AcReqSetValueString( long fileNumber, LPCSTR parmName, LPCSTR value )

fileNumber

The file number of the .ROV or .ROX file you opened with AcReqReadFile.

parmName

The name of the parameter whose value you want to set. If you do not know the names of the parameters, use AcReqGetFirstParameter and AcReqGetNextParameter to get the parameter names.

value

The string value to assign to the parameter.

Description

Use AcReqSetValueString to assign a string value to a parameter. The parameter whose value you want to set must be of type String. Use AcReqGetParmType to check the data type of a parameter before setting its value.


See also

AcReqGetFirstParameter

AcReqGetNextParameter

AcReqGetParmType


AcReqUninitialize

See also

Closes the Requester API library and frees resources.

Syntax

Basic: Function AcReqUninitialize( sessionHandle ) As Boolean

C/C++: VBBOOL AcReqUnInitialize( long sessionHandle )

sessionHandle

The handle to the session to uninitialize. This value is returned by AcReqInitialize when the Requester API is initialized.

Description

When you are finished using the Requester API, call AcReqUninitialize to close the library and free resources it used. Call AcReqUninitialize at the end of your program.

AcReqUninitialize is a member of both the Requester and LRX APIs.

Return value

True if the Requester API was cleared from memory properly.

False if the API failed to clear from memory.


See also

AcReqInitialize


AcReqViewReport

See also

Displays the specified report (.ROI).

Syntax

Basic: Function AcReqViewReport( filename As String, options As Long ) As Long

C/C++: long AcReqViewReport( LPCSTR filename, long options )

filename

The name of the report (.ROI) to display. Specify the full path name if the file is not in the current directory.

If the file resides on a server, use the following format:

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

For information about specifying server file names, see Specifying report server file names--Requester API.

options

A set of constants you can use to specify how the End User Desktop application runs. When specifying multiple options, use the plus (+) character between the options. The following table lists and describes the constants.

Constant	Description
AC_REQ_LAUNCH_ALWAYS	Runs a new instance of an End User Desktop application to display the report.
AC_REQ_LOCAL	Displays the report in the current instance of the Developer Workbench or End User Desktop.
AC_REQ_VIEW	Displays the generated report.
AC_REQ_ASYNC	Runs this process asynchronously; the function returns immediately and the report is displayed in the background. If this constant is not specified, the function returns after the report is displayed.
The following examples show how to specify options with AcReqViewReport:

AcReqViewReport("detail.roi", AC_REQ_LAUNCH_ALWAYS)

AcReqViewReport("detail.roi", AC_REQ_LAUNCH_ALWAYS+AC_REQ_ASYNC)

Description

Use AcReqViewReport to display an existing report. To display a report immediately after you generate it with AcReqGenerateReport, use the AC_REQ_VIEW option in AcReqGenerateReport.

AcReqViewReport is a member of both the Requester and LRX APIs.

Return value

0 if the report was displayed.

Any number other than zero if the report was not displayed.


See also

AcReqGenerateReport


AcReqWriteFile

See also

Creates a parameter value (.ROV) file.

Syntax

Basic: Sub AcReqWriteFile( fileNumber As Long, filename As String )

C/C++: void AcReqWriteFile( long fileNumber, LPCSTR filename )

fileNumber

The file number of the .ROV or .ROX file you opened with AcReqReadFile.

filename

The name of the .ROV file to create. The file name must include the .ROV filename extension.

If the file resides on a server, use the following format:

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

For information about specifying server file names, see Specifying report server file names--Requester API.

Description

Use AcReqWriteFile to write to an .ROV file the parameter values you set through functions such as AcReqSetValueString or AcReqSetValueInteger. Before you call AcReqWriteFile or any of the functions to change or inspect parameter values, you must first call AcReqReadFile to open the appropriate .ROX or .ROV file.

After you create the .ROV file, you can call AcReqGenerateReport to create a report from that .ROV file.


See also

AcReqReadFile


Undocumented functions

The following functions are undocumented and intended for internal use only. Actuate reserves the right to change these functions without notice and does not recommend their use for any purpose.

AcReqGetPrinterCapabilities

AcReqInfo

AcReqGetCacheFile

AcReqAddToCache

AcReqDropFromCache


Search Extension API reference

This reference alphabetically lists the functions in the Search Extension API. For a conceptual discussion of the Actuate Search Extension API, see Search Extension API user guide.

When using this reference, recognize that the function descriptions typically explain the code the developer must write to implement the function rather than prebuilt functionality. Developers must implement all functions marked as required.


Close

See also

Close files or APIs and perform other cleanup operations. This function is required.

Syntax

BOOL Close(long event)

event

The reason for closing the Search Extension

0 - The search completed normally

1 - The search was stopped by the user

2 - The search was stopped due to the application closing

3 - The search was not started

Description

Actuate calls Close when the Search Extension is closing and passes a parameter that indicates the event that terminated the search. For normal completion, the extension should implement code to close files, APIs, and other cleanup operations.

For all other cases, the results of the search are missing or incomplete. The extension should implement cleanup code, but should not launch a third-party application or create a partial report.

Return value

Return TRUE if the operation is successful; otherwise return FALSE.


See also

Open


GetColumnDelimiter

See also

Specify the delimiter character that separates columns of search data. This function is required.

Syntax

const char* GetColumnDelimiter( )

Description

The GetColumnDelimiter function returns the delimiter to be used when Actuate formats a row. Actuate passes the formatted row to the extension in PutRow. The extension can modify the row delimiter before passing it on to the external application, when necessary.

Return value

A null terminated character string that defines the row delimiter.


See also

PutRow


GetName

Specify a user friendly name for the search extension. This function is required.

Syntax

const char* GetName( )

Description

The GetName function returns the name that Actuate uses to identify the extension. Actuate displays this name in the External Applications combo box on the Search options dialog box.

Return value

A character string that represents the name of the extension. Select a short name that is descriptive of the application the extension supports, like Word or Excel.


GetParameters

See also

Specifies the extension-specific parameters for the search operation. GetParameters is optional.

Syntax

const char* GetParameters( )

Description

GetParameters returns a string that specifies the extension-specific parameters for the search operation. This information is typically the options collected during the InputParameters call. This function works in conjunction with SetParameters to allow the extension to store and retrieve information from the search definition file. Actuate returns this same string to the extension application through the SetParameter argument. Actuate calls GetParameters before it saves the search definition file.

Return value

A null-terminated character string containing search parameters. The content and format are defined by the search extension application. An empty string is the default if GetParameters is not implemented.


See also

InputParameters

SetParameters


IncludeHeader

See also

Specifies whether the search data should include a header or not. This function is optional.

Syntax

BOOL IncludeHeader( )

Description

The IncludeHeader function returns a Boolean indicating if the first row sent to the extension should be a header containing the names of the columns separated with the column delimiter.

Return value

Returns TRUE to include headers or FALSE to exclude headers. TRUE is assumed if the function is not implemented.


See also

PutRow


InputParameters

See also

Collects extension-specific parameters from the user. InputParameters is optional.

Syntax

BOOL InputParameters( )

Description

InputParameters is called when the user clicks the Options button in the Search Extract Option dialog box. Typically the search extension application opens a dialog box that prompts the user for additional extension-specific parameters.

Return value

The function returns TRUE if any parameters have been modified; FALSE if not. FALSE is assumed if the function is not implemented.


See also

GetParameters

SetParameters


Open

See also

Open files or APIs used in the search process. This function is required.

Syntax

BOOL Open( )

Description

Actuate calls Open function when the search process begins. The extension should implement code to open files or APIs based on parameters or other relevant information.

Return value

Return TRUE if the function is successful; otherwise return FALSE.


See also

Close


PutRow

See also

Transfers each row as it is created during the search process. This function is required.

Syntax

BOOL PutRow( long rowIdx, const char* row )

rowIdx

A number indicating the row index for the search.

char

A null terminated string containing all the data columns separated with the column delimiter.

Description

This function is called for each row generated during the search process. The first row is a header row if the IncludeHeader function returned TRUE.

Return value

Return TRUE to indicate acceptance of the row; otherwise return FALSE.


See also

IncludeHeader

GetColumnDelimiter


SetParameters

See also

Passes extension-specific search definition parameters to the search extension DLL. SetParameters is optional.

Syntax

void SetParameters( const char* parms )

params

A character string containing the extension-specific search parameters. This string matches the one returned by GetParameters.

Description

The SetParameters function is used to restore the extension-specific parameters retrieved from a search definition file. This function works in conjunction with the GetParameters function to allow the extension to store and retrieve information from the search definition file. Actuate calls SetParameters after it reads the search definition file.


See also

GetParameters

InputParameters


Search Extension API user guide

The Search Extension API works in conjunctions with the Developer Workbench, Administrator Desktop, End User Desktop, LRX plugins, and ActiveX controls to provide two features:

•	Store ReportQuery definitions in the local file system.

•	Extract and transfer the result from a ReportQuery to external applications

Actuate offers prebuilt search extensions for the third party applications such as Microsoft Excel and Brio Technology BrioQuery. Using the Search Extension API, you can add custom extensions for additional third party applications or build custom analysis tools.

See also

About the Search Extension API
Search Extension API functions by programming task
Developing a search extension
Installing a custom search extension
Example application


About the Search Extension API

The Search Extension API supports these three fundamental use scenarios:

•	Extract the results of a search and bring it up in another tool

•	Record a set of searches and extractions run on a regular basis

•	Run a saved search and extract the data to an external application

Actuate products implement this functionality through the Search Extension API. As users configure and launch search operations from the desktop, Actuate calls functions in the Search Extension API. A custom application that implements the Search Extension functions tailors the search for a particular third party analysis tool. You cannot initiate a search from the API. Rather, a Search Extension application customizes searches initiated from an Actuate user interface.


Search Extension API functions by programming task

This section categorizes and lists the functions in the Search Extension API by the following general programming tasks:

•	Writing startup and cleanup code

•	Setting search parameters

•	Processing search results

For a complete description of each function, see Search Extension API reference.

See also

Writing startup and cleanup code
Setting search parameters
Processing search results


Writing startup and cleanup code

The following table lists the functions for starting and ending a search session.

Programming task	API function
Close files or APIs and perform other cleanup operations. This function is required.	Close
Specify a user friendly name for the search extension. This function is required.	GetName
Open files or APIs used in the search process. This function is required.	Open
GetName and Open are startup operations called at the beginning of the search process. Close is called when the search is complete.


Setting search parameters

The following table lists the functions for working with search parameters.

Programming task	API function
Specifies the extension-specific parameters for the search operation. GetParameters is optional.	GetParameters
Collects extension-specific parameters from the user. InputParameters is optional.	InputParameters
Passes extension-specific search definition parameters to the search extension DLL. SetParameters is optional.	SetParameters
InputParameters is called whenever the user presses the Options button on the Search Extract Option dialog box. Actuate calls GetParameters when it saves a search definition and SetParameters when it reads a search definition.

Actuate stores search parameters, including the extension-specific parameters, in a .ROS file. The default directories for search definitions and search extensions are SrchDef and SrchExt, respectively. These directories are at the same level as the product directory, usually C:\Actuate. You can change the default directories by adding two entries to the Windows registry:

HKEY_CURRENT_USER/Software/Actuate/SearchDefDir

HKEY_CURRENT_USER/Software/Actuate/SearchExtDir

Each registry entry is a new string value that contains the fully qualified path to the search definition or extension folder. These registry entries are optional and are not set when the product is installed. Make these additions carefully because improper changes to the registry can render your software or computer inoperative. For more information on working with the Windows registry, refer to Windows help.


Processing search results

The following table lists the functions for processing search results.

Programming task	API function
Specify the delimiter character that separates columns of search data. This function is required.	GetColumnDelimiter
Specifies whether the search data should include a header or not. This function is optional.	IncludeHeader
Transfers each row as it is created during the search process. This function is required.	PutRow
GetColumnDelimiter and IncludeHeader define data format and are called before the search. PutRow transfers the search results to the extension.


Developing a search extension

The Search Extension API is a C++ API that is implemented as a standard Windows DLL. Development of a custom search extension includes the following tasks:

•	Write search extension code

•	Create a definition file for the exports

•	Create a header file defining the DLL exports

•	Compile the code into a DLL

See also

Writing search extension code


Writing search extension code

Write your search extension application as follows:

1	Provide a name for the extension

The name returned by GetName appears in the Search Extract Option dialog box as one of the available extensions.

2	Implement startup tasks

Startup code, implemented in the Open function, typically opens files on the local file system.

3	Process search parameters (optional)

If your extension requires extension-specific parameters, develop code for handling those parameters. Use GetParameters, SetParameters, and InputParameters for this purpose.

4	Set up search settings

Specify the column delimiter character and specify handling of header information using GetColumnDelimiter and IncludeHeader.

5	Process the search results

Using PutRow, process the search results. Processing may include reformatting for third party applications.

6	Implement cleanup tasks

Close any open files and perform any necessary cleanup operations using the Close function.

Except for the functions related to parameters, you must implement all functions in the interface.

See also

Creating a definition file
Creating a header file
Compiling the code


Creating a definition file

The following lines of code are from a definition file used during the link process of a specific search extension (DLL file). Each function is named by the entries in the left column. The actual function names are in the right column. Actuate uses this name mapping to find the functions for a specific implementation of the Search Extension API:

EXPORTS

GetName	=ExcelGetName

GetParameters	=ExcelGetParameters

SetParameters	=ExcelSetParameters

InputParameters	=ExcelInputParameters

GetColumnDelimiter	=ExcelGetDelimiter

IncludeHeader	=ExcelIncludeHeader

Open	=ExcelOpen

Close	=ExcelClose

PutRow	=ExcelPutRow


Creating a header file

The following lines of code are from an include file for a specific implementation of a search extension. The function names match the names in the right hand column in the .DEF file.

#define DllExport	extern __declspec( dllexport )

DllExport 	const char* FAR PASCAL ExcelGetName();

DllExport 	const char* FAR PASCAL ExcelGetParameters();

DllExport 	void   FAR PASCAL ExcelSetParameters( const char* parms );

DllExport 	BOOL FAR PASCAL ExcelInputParameters();

DllExport 	const char* FAR PASCAL ExcelGetDelimiter();

DllExport 	BOOL FAR PASCAL ExcelIncludeHeader();

DllExport 	BOOL FAR PASCAL ExcelOpen();

DllExport 	BOOL FAR PASCAL ExcelClose();

DllExport 	BOOL FAR PASCAL ExcelPutRow( long rowIdx, const char* row );


Compiling the code

Compile the search extension with Visual C++ version 4.1, 4.2 or 5.0.


Installing a custom search extension

A client station using a Search Extension API requires two components:

•	Developer Workbench, Administrator Desktop, End User Desktop, LRX plugins, or ActiveX controls

•	Custom DLL that implements the Search Extension API

The Actuate Viewer is free but other components require a valid license.

You can use the Actuate Viewer to display reports for your API application if you set up the client station as follows:

1	Install the Developer Workbench, Administrator Desktop, End User Desktop, LRX plugins, or ActiveX controls.

2	Copy the Search Extension DLL to the search extension directory. The default search extension directory is SrchExt, located in the directory where you installed the Actuate product. For an installation using the defaults, the directory is C:\Actuate\SrchExt. You can override this location by setting the registry value HKEY_CURRENT_USER/Actuate/SearchExtDir to a new directory.

Actuate will detect your DLL and present it as an option in the Search Extract Option dialog box.


Example application

The following application implements a procedure that saves search results to a file. In this simple example, the results are hard-coded to send results to C:\temp\rqeFile.txt. In an more flexible implementation, let the user specify the file name and location using the Option button on the Search Extract Option dialog box by implementing the InputParameters function.

See also

Example
Definition file
Header file


Example

/*****************************************************************

*

* rqefile.cpp - Sample Report Query Extension for file output.

*

* 5/26/98  DBE  Copyright Actuate Software Corporation

*

 *****************************************************************/

#include <windows.h>

#include "rqefile/rqefile.h"

#include <sys/stat.h>

#include <fcntl.h>

#include <io.h>

#include <string.h>

char	g_RQEFileNm[256] = { 0 };

int	g_RQEFileFD = -1;

const char* FAR PASCAL RQEFileGetName()

{

return "File Output";

}

const char* FAR PASCAL RQEFileGetParameters()

{

return g_RQEFileNm;

}

void FAR PASCAL RQEFileSetParameters( const char* parms )

{

strncpy( g_RQEFileNm, parms, sizeof( g_RQEFileNm ) );

}

const char* FAR PASCAL RQEFileGetDelimiter()

{

return ",";

}

BOOL FAR PASCAL RQEFileIncludeHeader()

{

return TRUE;

}

BOOL FAR PASCAL RQEFileOpen()

{

if ( strlen( g_RQEFileNm ) == 0 )

strncpy ( g_RQEFileNm, "c:\\temp\\rqeFile.txt", sizeof( g_RQEFileNm ) );

g_RQEFileFD = open( g_RQEFileNm, O_CREAT|O_TRUNC|O_RDWR,
    S_IREAD|S_IWRITE );

if ( g_RQEFileFD < 0 )

return FALSE;

return TRUE;

}

BOOL FAR PASCAL RQEFileClose()

{

if ( g_RQEFileFD < 0 )

return FALSE;

close( g_RQEFileFD );

g_RQEFileFD = -1;

return TRUE;

}

BOOL FAR PASCAL RQEFilePutRow( long rowIdx, const char* row )

{

if ( g_RQEFileFD < 0 )

return FALSE;

int rowLen = strlen( row );

if ( write( g_RQEFileFD, row, rowLen ) < rowLen )

return FALSE;

if ( write( g_RQEFileFD, "\n", 1 ) < 1 )

return FALSE;

return TRUE;

}

// End of file.


Definition file

The project definition file, RQEFILE.DEF, contains the following:

; rqefile.def : Declares the module parameters for the DLL.

; $Revision: 1 $

; $Archive: $

;

; 5/26/98 Actuate Software Inc.

DESCRIPTION  'RQE File Interface'

EXPORTS

GetName	=RQEFileGetName

GetParameters	=RQEFileGetParameters

SetParameters	=RQEFileSetParameters

GetColumnDelimiter	=RQEFileGetDelimiter

IncludeHeader	=RQEFileIncludeHeader

Open	=RQEFileOpen

Close	=RQEFileClose

PutRow	=RQEFilePutRow


Header file

// $Revision: $

// $Archive: $

#ifndef __RQEFILE_H__

#define __RQEFILE_H__

/*****************************************************************

*

*  rqefile.h - Sample Report Query Extension for file output.

*

*	5/26/98  DBE  Copyright Actuate Software Corporation

*

*****************************************************************/

#define DllExport extern __declspec( dllexport )

#define TRUE	1

#define FALSE	0

typedef int BOOL;

/////////////////////////////////////////////////////////////////////////////

DllExport const char* FAR PASCAL RQEFileGetName();

DllExport const char* FAR PASCAL RQEFileGetParameters();

DllExport void FAR PASCAL RQEFileSetParameters( const char* parms );

DllExport const char* FAR PASCAL RQEFileGetDelimiter();

DllExport BOOL FAR PASCAL RQEFileIncludeHeader();

DllExport BOOL FAR PASCAL RQEFileOpen();

DllExport BOOL FARPASCAL RQEFileClose();

DllExport BOOL FAR PASCAL RQEFilePutRow( long rowIdx, const char* row );

#endif /* __RQEFILE_H__ */