How to: Use the Report Output Application's Reference Collection

  • Article

At run time, the default Report Output Application (ReportOutput.app) maintains a reference collection of ReportListener object references. ReportOutput.app scopes the collection globally, by declaring the reference variable with the PUBLIC keyword. The collection allows the Report Engine to use a single ReportListener-derived object on multiple REPORT FORM or LABEL commands. For more information, see Understanding the Report Output Application.

You can use this collection to set properties on ReportListener object instances before REPORT FORM and LABEL commands, or to check the results of a report run afterwards, without assigning a variable to hold the reference explicitly.

ReportOutput.app uses a consistent collection key-naming scheme so you can easily find the appropriate reference.

Note

Some of the code in this topic uses the _REPORTOUTPUT System variable to invoke ReportOutput.app. _REPORTOUTPUT may contain the name of a different Report Output Application in your environment. In this case, substitute HOME() + ReportOutput.app, or similar code, to invoke the default Report Output Application. Where the instructions designate the name and position of a custom registry table, substitute your preferred name and location.

Initializing the Reference Collection and Creating Reference Collection members

To create a Reference Collection member

  1. You can create a Reference Collection member while running a report, and without using an explicit variable reference. Issue the following command, where <N> is the type of output you want from the REPORT FORM command. For example, use the value 1 as <N> to preview the report.

    REPORT FORM ? OBJECT TYPE <N>

  2. You can also create a Reference Collection member without running a report. Issue the following command, where <N> is a type of output you want for subsequent REPORT FORM commands. For example, use the value 0 as <N> to print the report:

    DO (_REPORTOUTPUT) WITH <N>

  3. You can also create a Reference Collection member representing the Report Output Application's current registry table, initializing the collection at the same time. This method does not create any ReportListener object references immediately. Initializing the collection in this manner, and specifying a configuration table as the collection's single member, is the default behavior of the Report Listener Application when you call the application with no parameters:

    #DEFINE OUTPUTAPP_CONFIG_READ -200
DO (_REPORTOUTPUT) WITH OUTPUTAPP_CONFIG_READ
* or pass a variable by reference in the second 
* parameter, as you normally do for ReportListener 
* references, to receive the name of the current
* registry table:
LOCAL lcFile
DO (_REPORTOUTPUT) WITH OUTPUTAPP_CONFIG_READ, lcFile
* or simply initialize the collection with no parameters: 
DO (_REPORTOUTPUT) 
? _oReportOutput[TRANSFORM(OUTPUTAPP_CONFIG_READ)]

Examining Reference Collection members

To retrieve a ReportListener object reference from ReportOutput's collection

  1. Use the string value of the numeric value representing the type of output for a ReportListener reference as the collection key value. In the command below, <N> represents the type of output provided by this ReportListener object reference.

    ? _oReportOutput[TRANSFORM(<N>)].Class

  2. Use the Reference Collection member after running a report. For example, check the total number of pages in the report run:

    REPORT FORM ? OBJECT TYPE 0
? _oReportOutput["0"].PageTotal

  3. Use the Reference Collection member, before running a report to customize its behavior. For example, prevent user feedback before generating XML output:

    DO (_REPORTOUTPUT) WITH 4
_oReportOutput["4"].QuietMode = .T.

    Tip

    As shown above, special negative values used by ReportOutput.app for configuration purposes may also be used as keys in this collection, although they do not provide ReportListener-derived object references. For additional examples, see "Verifying the Report Output Application's current Registry Table" in How to: Specify an Alternate Report Output Registry Table.

Changing the Default Reference Collection Variable Name

In the instructions above, you used the variable name _oReportOutput when addressing the reference collection. To change this variable name in your applications, recompile ReportOutput.app with instructions to use the variable name that you prefer.

To recompile ReportOutput.app with a different reference collection variable name

  1. Expand the ReportOutput subfolder in the zip file located in Visual FoxPro's Tools\Xsource folder. For more information about Xsource, see XSource Folder.

  2. Navigate to the folder in which you expanded the ReportOutput component source files. Modify the ReportOutput.H (header) file.

    CD <your source folder>
MODIFY COMMAND ReportOutput.H

  3. Locate the following two lines of code in the header file:

    #DEFINE OUTPUTAPP_REFVAR        _oReportOutput
#DEFINE OUTPUTAPP_REFVARCLASS  "Collection"

  4. Edit the value _oReportOutput, replacing it with the variable name you want your application to use. You can also edit the value "Collection", replacing it with the Collection-derived class name you want ReportOutput.app to use when creating an instance of the collection.

    Note

    If you change the value of OUTPUTAPP_REFVARCLASS, the class definition you designate in this constant must be in scope before you invoke ReportOutput.App. For more information, see SET CLASSLIB Command and SET PROCEDURE Command.

  5. Save your changes.

  6. Rebuild the ReportOutput.App file, being sure to use the RECOMPILE switch:

    BUILD APPLICATION ReportOutput FROM ReportOutput RECOMPILE

  7. Store the name and location of your new ReportOutput.app to the _REPORTOUTPUT System variable, either in the CONFIG.FPW file for your application or in your setup code. For more information, see Setting Configuration Options at Startup.

    _ReportOutput = <your ReportOutput.app filename and location>

  8. Distribute the new ReportOutput.App file with your applications.

See Also

Tasks

How to: Build Applications

Reference

PUBLIC Command
Collection Class
ReportListener Object
_REPORTOUTPUT System Variable
REPORT FORM Command