_REPORTOUTPUT System Variable

  • Article

Specifies the Visual FoxPro handler application providing ReportListener derived classes to be used with the REPORT FORM command, maintaining a registry of ReportListener derived classes for different output results.

_REPORTOUTPUT = cProgramName

Parameters

cProgramName

Specifies the name of an application or program that the Visual FoxPro Report System calls when a suitable REPORT FORM command occurs.

Remarks

The Visual FoxPro Report System invokes the application specified by this value when one of the following conditions occur:

  • You invoke the REPORT FORM or LABEL command with an explicit OBJECT TYPE<N> clause. The Report Engine passes the numeric value you use to the application named in _REPORTOUTPUT.

  • You invoke a REPORT FORM command after having used the command SET REPORTBEHAVIOR 90. This setting indicates that you want to use object-assisted mode for all REPORT FORM or LABEL commands. The Report Engine uses the other keywords on the output command (such as TO PRINT or PREVIEW) to establish the appropriate numeric value for the equivalent OBJECT TYPE<N> clause.

In both scenarios, the Report Engine also passes a variable to the application specified in _REPORTOUTPUT. The application stores a reference to an appropriate ReportListener object to this variable. In the subsequent report or label processing run, the Report Engine partners with this object to handle output rendering.

By default, _REPORTOUTPUT specifies the path and file name for the ReportOutput.app located in the main Visual FoxPro directory, as indicated by the HOME() function.

You can also specify a report output application using the File Locations tab in the Options dialog box. For more information, see File Locations Tab, Options Dialog Box.

When distributing applications, you may find it convenient to explicitly set _REPORTOUTPUT in the Visual FoxPro configuration file, Config.fpw. You can also set the _REPORTOUTPUT value to the name of a program built into your application. For more information, see Including Report Files for Distribution and Setting Configuration Options at Startup.

Note

If you use a REPORT FORM or LABEL command and include the OBJECT TYPE <N> clause, or have previously used the command SET REPORTBEHAVIOR 90, without a valid value in _REPORTOUTPUT, Visual FoxPro generates an error.

Requirements

The application you specify with _REPORTOUTPUT must fulfill the following conditions:

  1. It must accept at least two parameters. The Report Engine passes a numeric value, indicating the type of output required, as the first parameter. The Report Engine passes a variable, to hold a reference to an appropriate ReportListener, as the second parameter.

  2. It must store a NULL value (.NULL.) to the second parameter if it cannot understand the value in the first parameter, or does not have the ability to supply a reference to a ReportListener-derived object meeting the requirements of the first parameter.

  3. It must be able to provide ReportListener-derived object references for (at minimum) numeric types matching the native ListenerType values supported by Visual FoxPro. For more information, see ListenerType Property.

  4. If successful in obtaining a ReportListener object reference according to the numeric type requested by the ReportListener, it must store this reference to the second parameter. It must also store the numeric type supplied by the Report Engine or calling application to this object's OutputType property. For more information, see OutputType Property (Visual FoxPro).

  5. It must be modal, because it must provide an appropriate reference back to the Report Engine. If it provides any user interface elements, for example allowing the user to select an appropriate ReportListener from a list, this interface should be modal as well.

Recommendations

The following additional conditions are not required for an application to function as _REPORTOUTPUT. However, fulfilling these conditions is highly recommended for any application in this capacity:

  1. The application should maintain some type of ReportListener registry, to allow users to specify classes they prefer to use for various types of output.

  2. The application should bubble errors to the calling application in a manner that permits the caller to determine what action to take when the Report Output Application cannot meet its responsibilities.

Example

The following example sets the value of the _REPORTOUTPUT system variable to the default Report Output application.

_REPORTOUTPUT = HOME() + "ReportOutput.app"

See Also

Reference

HOME( ) Function
ReportListener Object

Other Resources

Extending Report Output Functionality