ixActuateReport

: Constructor
: Identifying And Finding Report Components
: Handling Parameter Sets
: Handling Parameters by Group
: Handling Parameters Individually
: Setting Print Characteristics
: Report Invocation

The ixActuateReport class is a class that connects to the components in the ARS environment. An ixActuateReport object:

organizes the runtime parameters in parameter sets.
fetches, creates, or saves a parameter set.
creates an ixActuateParm object for each parameter that the user wants to have presented, examined, or changed.
allows printer configuration and setup.
launches report generation with or without subsequent viewing or printing.
launches viewing or printing of any previously generated report.

To generate and print a report, you need to instantiate an ixActuateReport object, specify the name of the parameter file that contains the parameter set, and call the print() function of the object.

If you want to direct the output to a particular printer, or change any print characteristics, you can call the setPrinter() function before calling the print() function. If you need to examine or change a runtime parameter setting, you must call the fetchParmSet() function before calling the print() function.

To gain access to a single parameter in an open parameter set, you can call the getParmByName() function. This function returns an ixActuateParm object, representing the parameter. Using the member functions of the ixActuateParm object, you can inspect the property values, default value, and latest current value, and you can set a new current value.

The print() function automatically saves the parameter set before the report generation is launched (but you can call the saveParmSet() function explicitly, if desired).

Class Member Functions

Constructor

ixActuateReport(
parmFileName CHAR ():NULL,
execFileName CHAR ():NULL,
reportFileName CHAR (*):NULL)

This function is the class constructor. It creates and instantiates the member variables.

parmFileName is the name of the runtime parameter value file (.rov) that contains the current parameter set. This file is necessary input to the report Factory process.

If you request the generation of a new report, with or without subsequent viewing or printing, you must specify this filename before you can call the generate(), view(), or print() functions. If you are only viewing or printing a report file that was created previously, it is not needed.

execFileName is the name of the ARS executable file (.rox) used by the Factory to generate the report. This variable is stored in the parameter set when the parameter set is saved. The executable file also contains descriptions and default values for the runtime parameters.

execFileName must be supplied when a new parameter set is created.

If execFileName is NULL when a parameter set is fetched, it receives the value from the parameter set.

reportFileName is the name of a ARS report file (.roi) created by the Actuate Factory. This variable is stored in the parameter set when the parameter set is saved. When generating a report, the Factory uses the name stored in the parameter set. If you are only viewing or printing a report file that was created previously, you must specify this name before you call the view() or print() function.

If reportFileName is NULL when a parameter set is fetched, it receives the value from the parameter set.

If reportFileName is NULL when a new parameter set is created, it defaults to the name stored in the executable file.

The function can be called with no arguments. If so, you must specify the necessary file names with the setParmFileName(), setExecFileName(), and setReportFileName() functions before you can have the report generated or printed.

Although you can supply entire paths in the filename variables, the setParmPath(), setExecPath() and setReportPath() functions provide the opportunity to specify directory pathnames separately. This can be useful when the application is installed on several clients with different directory structures. This way, client-specific paths can be provided.

If execFileName or reportFileName have no values (if they are NULL) when a parameter set is fetched, they will receive filename values (without path information) from the parameter set. Otherwise they will retain the value that has been explicitly set by the program.

If the execPath and reportPath variables are NULL when a parameter set is fetched, they will receive values from the parameter set. Otherwise they will retain the value that has been explicitly set by the program.

Identifying And Finding Report Components

Handling Parameter Sets

fetchParmSet() RETURNING SMALLINT

This function retrieves the last current parameter set stored in the parameter file (.rov).

If a parameter value file is already open, it will be closed, without saving, before the parameter set is fetched. If the parameter file (.rov) does not exist, the createParmSet() function is called to create a default parameter file, which then is opened.

If reportFileName or execFileName are not set when the function is called, filenames and paths are taken from the parameter value file.

saveParmSet() RETURNING SMALLINT

This function prepares and sets the filenames (.rox and .roi) to be stored with the parameter set and saves and closes the parameter value file (.rov).

If the parameter value file is not open (rovFileNumber = 0), this is an error condition. The filenames are prepared and the validity of the executable filename and path is checked.

createParmSet() RETURNING SMALLINT

This function creates and opens a new parameter value file (.rov) with current values equal to the default values based on the information in the executable file (.rox).

If a parameter value file is already open (rovFileNumber > 0), it will be closed, without saving, before the parameter set is fetched. If parmFileName is not set, this is an error condition.

If execFileName is not set, execFileName is assumed to be the same as parmFileName. If execFileName does not exist, this is an error condition.

discardParmSet() RETURNING SMALLINT

This function closes the open parameter set without saving.

Handling Parameters by Group

selectFirstGroup() RETURNING CHAR(*)

This function retrieves the name of the first parameter group from the current parameter file (.rov), making this parameter group current. If the parameter file is not open, it is opened and read automatically.

The function returns the parameter group name. If there are no groups, the function returns NULL.

selectNextGroup() RETURNING CHAR(*)

This function retrieves the name of the next parameter group from the parameter file (.rov), making this parameter group current. If no parameter group has been previously selected (currentParmGroup = NULL), it selects the first parameter group.

The function returns the parameter group name. If there are no more groups, the function returns an empty string.

getFirstParm() RETURNING ixActuateParm

This function retrieves the name of the first parameter in the currently selected parameter group and calls getParmByName() to create an ixActuateParm object. If no parameter group is currently selected (currentParmGroup = NULL), it selects the first parameter group and its first parameter.

The function returns a pointer to the ixActuateParm object. If no object could be created, it returns a NULL pointer.

getNextParm() RETURNING ixActuateParm

This function retrieves the name of the next parameter in the currently selected parameter group and calls getParmByName() to create an ixActuateParm object. If no parameter group is currently selected (currentParmGroup = NULL), it selects the first parameter group and its first parameter.

If no parameter has been retrieved from the currently selected parameter group (currentParmGroup != NULL and currentParmName = NULL), it retrieves the first parameter in the group.

The function returns a pointer to the ixActuateParm object. If no object could be created, it returns a NULL pointer.

Handling Parameters Individually

getParmByName(parmName CHAR (*):NULL) RETURNING ixActuateParm

This function creates a new ixActuateParm object by calling ixActuateParm (parmName, parmFileNumber). It is called by the getFirstParm () and getNextParm () functions.

The function returns a pointer to the ixActuateParm object. If no object could be create, it returns a NULL pointer.

Setting Print Characteristics

setPrinter(printerName CHAR ():NULL,
numCopies SMALLINT:1,
twoSided BOOLEAN:FALSE,
collate BOOLEAN:FALSE,
landscape BOOLEAN:FALSE,
scale INTEGER:100,
formName CHAR ():NULL,
size SMALLINT:0,
length SMALLINT:0,
width SMALLINT:0,
color BOOLEAN:FALSE) RETURNING SMALLINT

This function tests the argument list for non-NULL values and performs one or more calls to AcRequester to change the parameters corresponding to the non-NULL arguments. If called with no arguments, the function resets the printer setup to default.

The value for printerName is the name given in the client's printer setting, not the name for which it is known by the network.

If duplex is not NULL, it should be either:

1 - simplex mode
2 - horizontal duplex mode
3- vertical duplex mode

Size can be an integer value from 1 to 68 as defined in the Actuate API Guide. The most common values are:

1 - Letter - 8 1/2 x 11"
2 - Legal - 8 1/2 x 14"
9 - A4 - 210 x 297 mm
11- A5 - 148 x 210 mm
55 - A4 transverse

If size is NULL, length and width must both be non-NULL. If size is non- NULL, length and width must both be NULL.

The Requester does not validate the arguments for the particular type of printer nor does it perform any other validations. This function always returns zero.

setWinPrinter() RETURNING SMALLINT

This function brings up the standard Windows print setup dialog box and calls the setPrinter() function with the user-defined settings. A non-zero return code indicates that the print setup dialog box was cancelled by the user.

Report Invocation

generate(wait BOOLEAN: FALSE) RETURNING SMALLINT

This function starts the generation of a report file (.roi). The EndUser Desktop can either generate a complete report file (wait=TRUE) before the function returns or it can generate a report file in the background (wait=FALSE). Any open parameter set is saved and closed automatically before report generation is launched.

view(browseOnly BOOLEAN: FALSE) RETURNING SMALLINT

This function invokes the EndUser Desktop to show a report on screen. It can either show an existing report file (browseOnly = TRUE) or generate and show a new report file (browseOnly = FALSE).

Any open parameter set is saved and closed automatically before report generation and viewing is launched.

print(printOnly BOOLEAN: FALSE) RETURNING SMALLINT

This function invokes the EndUser Desktop to print a report. It can either print an existing report file (printOnly = TRUE) or generate and print a new report file (printOnly = FALSE). An error condition exists if viewerPath does not contain the EndUser Desktop.

A non-zero return code indicates that the EndUser Desktop was not invoked.

startTrack() RETURNING VOID

This function starts the creation of a log file, ixaccl.log, containing information about all subsequent call from the application to ACCL functions and critical calls from ACCL to AcRequester.

The log file is created in the current directory. If a file with this name already exists, the new information is appended to the file. A function call can result in several lines in the log file since function calls can be nested.

stopTrack() RETURNING VOID

This function halts the tracking function and closes the log file.

getVersion() RETURNING CHAR

This function returns the ACCL version number.

Return to Table of Contents.

ixActuateReport

Class Member Functions

Constructor

ixActuateReport(parmFileName CHAR (*):NULL,execFileName CHAR (*):NULL,reportFileName CHAR (*):NULL)

Identifying And Finding Report Components

getParmFileName() RETURNING CHAR (*)

setParmFileName(parmFileName CHAR (*):NULL) RETURNING VOID

getExecFileName() RETURNING CHAR (*)

setExecFileName(execFileName CHAR (*):NULL) RETURNING VOID

getReportFileName() RETURNING CHAR (*)

setReportFileName(reportFileName CHAR (*):NULL) RETURNING VOID

getParmPath() RETURNING CHAR (*)

setParmPath(parmPath CHAR (*):NULL) RETURNING VOID

getExecPath() RETURNING CHAR (*)

setExecPath(execPath CHAR (*):NULL) RETURNING VOID

getReportPath() RETURNING CHAR (*)

setReportPath(reportPath CHAR (*):NULL) RETURNING VOID

getViewerPath() RETURNING CHAR (*)

setViewerPath(viewerPath CHAR (*):NULL) RETURNING VOID

getParmFileNumber() returning smallint

Handling Parameter Sets

fetchParmSet() RETURNING SMALLINT

saveParmSet() RETURNING SMALLINT

createParmSet() RETURNING SMALLINT

discardParmSet() RETURNING SMALLINT

Handling Parameters by Group

selectFirstGroup() RETURNING CHAR(*)

selectNextGroup() RETURNING CHAR(*)

getFirstParm() RETURNING ixActuateParm

getNextParm() RETURNING ixActuateParm

Handling Parameters Individually

getParmByName(parmName CHAR (*):NULL) RETURNING ixActuateParm

Setting Print Characteristics

setPrinter(printerName CHAR (*):NULL, numCopies SMALLINT:1, twoSided BOOLEAN:FALSE, collate BOOLEAN:FALSE, landscape BOOLEAN:FALSE, scale INTEGER:100, formName CHAR (*):NULL, size SMALLINT:0, length SMALLINT:0, width SMALLINT:0, color BOOLEAN:FALSE) RETURNING SMALLINT

setWinPrinter() RETURNING SMALLINT

Report Invocation

generate(wait BOOLEAN: FALSE) RETURNING SMALLINT

view(browseOnly BOOLEAN: FALSE) RETURNING SMALLINT

print(printOnly BOOLEAN: FALSE) RETURNING SMALLINT

startTrack() RETURNING VOID

stopTrack() RETURNING VOID

getVersion() RETURNING CHAR

ixActuateReport(
parmFileName CHAR ():NULL,
execFileName CHAR ():NULL,
reportFileName CHAR (*):NULL)

setPrinter(printerName CHAR ():NULL,
numCopies SMALLINT:1,
twoSided BOOLEAN:FALSE,
collate BOOLEAN:FALSE,
landscape BOOLEAN:FALSE,
scale INTEGER:100,
formName CHAR ():NULL,
size SMALLINT:0,
length SMALLINT:0,
width SMALLINT:0,
color BOOLEAN:FALSE) RETURNING SMALLINT