_ReportListener’s RunCollector (TMM)

Visual FoxPro 9.0 SP2

This conceptual topic supplies information about a new-in-SP2 FFC VFP Reporting System extension feature.

Overview

As the description for this member in the _ReportListener class tells you, runCollector is a "Placeholder available to hold extension output generated during a report run. Property may contain an alias for a cursor holding property names and values, a collection object reference, or an empty-type object reference."

At the beginning of a report run, your report-assisting objects can evaluate report conditions (including Document Properties), and decide how to use them. This information represents potential metadata for runCollector. During the run, your objects can act on this information and store the evaluated, run-time results in your runCollector cursor, object, or alias. During and after the run, you can make use of the information you have collected.

For example, ReportBuilder exposes an in-the-box Document Property, Document.Keywords. The property provides a place for you to store an expression to be evaluated during the report run. The runCollector provides a place for you to store the result of evaluating the expression, during the report run.

_ReportListener does nothing with the runCollector itself, except for setting its value to NULL during its .Destroy method to help manage object references for you. The member exists in the _ReportListener ancestor class, rather than FXListener or a different derived class, because it is so basic to reporting extensions, and can be useful to everybody. There are also abstract PROTECTED methods available in this ancestor class for some basic actions that derived classes should implement: fillrunCollector and resetRunCollector.

Note
_ReportListener's runCollector member property is PROTECTED, too. External objects participating in a report run should give instructions for what to store, but they should not dictate how the information is stored. Any ReportListener-derived class that implements a run collection should have complete freedom in this respect. In the Document.Index example, as described in the Document Properties TMM docoid, you could implement a method such as .CreateCursorFromRunCollection(<alias>,<session>) to expose the index result as the data source for your index report. (In this scenario, the index report is probably the final report in a report chain, consisting of one or more "chapters" in a book.) You would publish the structure of the cursor that this method would create. You would not necessarily publish how the data had been stored internally, or how the reportlistener hosting the collection copied the data to your cursor. Similarly, XMLListener publishes and serializes the full runCollection as part of the VFP RDL schema, so that the results of the report run include this data along with the standard report output from the the bands and layout controls.

Note

_ReportListener's runCollector member property is PROTECTED, too. External objects participating in a report run should give instructions for what to store, but they should not dictate how the information is stored. Any ReportListener-derived class that implements a run collection should have complete freedom in this respect.

In the Document.Index example, as described in the Document Properties TMM docoid, you could implement a method such as .CreateCursorFromRunCollection(<alias>,<session>) to expose the index result as the data source for your index report. (In this scenario, the index report is probably the final report in a report chain, consisting of one or more "chapters" in a book.) You would publish the structure of the cursor that this method would create. You would not necessarily publish how the data had been stored internally, or how the reportlistener hosting the collection copied the data to your cursor.

Similarly, XMLListener publishes and serializes the full runCollection as part of the VFP RDL schema, so that the results of the report run include this data along with the standard report output from the the bands and layout controls.

The FXListener derived class carries the concept of runCollector slightly further, by exposing a PUBLIC property: runCollectorResetLevel. This property allows classes derived from FXListener, which might make use of the runCollector, an opportunity to indicate how often the runCollector should be "reset". The #DEFINEd numeric values representing "never", "at the conclusion of a report chain", or "on every report" .

If you use the Document.Keywords property, you might decide to set this level at "on every report" or "at the conclusion of a chain". If, on the other hand, you were implementing a Document.Index, and if you were using the data in the collection as the basis for another report, you might set it to "never".

Although FXListener introduces this "reset level" idea, to help you explore some of the potential of runCollector, it does not implement resetRunCollector because it does not implement runCollector, or have any intrinsic use for runCollector, itself. In your implementation, you might choose to have a completely different set of values for "reset levels", you might choose to reset only some values and not others, et cetera.

FFC's XMLListener class provides a worked example of runCollector use, using Document Properties as the reason you would want to use it. Please see the separate docoid on Using Document Properties and the Run Collection in XMLReportListener and its Derived Classes for this implementation.