How to: Specify an Alternate Report Output Registry Table

Article
06/24/2008

The default Report Output Application supports a registry table in which you can specify the ReportListener-derived classes for different types of output results. This topic describes mechanisms available to:

Create a new registry table.
Tell the Report Output Application to use this table at run time.
Find out what registry table the Report Output Application is currently using.

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.

For more information about using the registry table with your own classes and output extensions, see How to: Register Custom ReportListeners and Custom OutputTypes in the Report Output Registry Table.

For more information about the format of the registry table, see Understanding the Report Output Application.

Creating a Report Output Registry Table

You can use either ReportOutput.app or a ReportListener Foundation Class to create the table, because they use the same configuration table format.

Note

These two methods may generate different sample and configuration records in the table, and they can potentially include different sets of indexes. If you share a registry table between different reporting components, each component using the table verifies the contents of the table against its own requirements. If necessary, each component is capable of adding its own records and indexes on-the-fly.

To create a new Report Output registry table using ReportOutput.app

In the Command Window or in a program (.prg), use the following line of code:
```
* #DEFINE OUTPUTAPP_CONFIG_WRITE -100
DO (_REPORTOUTPUT) WITH -100
```
The Report Output Application creates a table named OutputConfig.DBF, and associated memo (.fpt) and structure index (.cdx) files, in the same location as ReportOutput.App (normally, Visual FoxPro's main or HOME() directory).
The Report Output Application presents a BROWSE of this new table, so you can check the contents. The contents will include the records required by the ReportListener XML Foundation Class, plus some deleted records which serve as examples of different types of registry records
You see a deleted record for debugListener, the ReportListener Debug Foundation Class. This record shows you what a ReportListener registry record looks like, according to the requirements of the Report Output Application.
You also see deleted records for two records with ObjType values of 1000. This value is in the range reserved for use by utilityReportListener, the ReportListener Utility and File-handling Foundation Class. One record shows you how to create a configuration record to set a class property and the other shows you how to create a configuration record to invoke a class method. For more information about how this class and its descendents use configuration records, see ReportListener Utility and File-handling Foundation Class.
You can rename the three OutputConfig.* files and place them somewhere else on your disk for later use.

To create a new Report Output registry table using a ReportListener Foundation class

Create an instance of the ReportListener Utility and File-handling Foundation Class, or any of the ReportListener Foundation Classes derived from it. You can create an instance of this class using the class library (vcx) built into ReportOutput.app, or you can create an instance of the class using the copy of the class library available in Visual FoxPro's FFC folder.
```
* "borrow" a copy directly from ReportOutput.App:
#DEFINE CONFIG_REPORTLISTENER_CLASS "utilityReportListener"
oRL = NEWOBJECT(CONFIG_REPORTLISTENER_CLASS, ;
                "listener.vcx", ;
                _REPORTOUTPUT)
* - OR -
* access the Foundation Class library directly:
#DEFINE FFC_HOME HOME()+"FFC\"
oRL = NEWOBJECT(CONFIG_REPORTLISTENER_CLASS, ;
                FFC_HOME + "_reportListener.vcx")
```
Tip

All the ReportListener Foundation Classes providing file-based output, such as the ReportListener HTML Foundation Class, derive from ReportListener Utility and File-handling Foundation Class. Some of these classes require a registry table. Any class that requires a table checks for the availability of the table when you initialize it. If the table is not available, it creates a copy of the table, in its default location, during initialization procedures. For more information, see ReportListener Utility and File-handling Foundation Class.
Request a new configuration table from the ReportListener instance. You can specify its name and location:
```
* if SAFETY is ON, prompt for overwrite if the file exists:
oRL.createConfigTable("c:\temp\myconfig.dbf")
*- OR -
* use the second parameter to explicitly overwrite:
oRL.createConfigTable("c:\temp\myconfig.dbf", .T.)
```
Tip

The classes respect the setting of SAFETY in your environment, in that they will prompt you to confirm an overwrite of the table if SET SAFETY is ON and if you do not specify the second parameter of the createConfigTable method as True (.T.). For more information, see SET SAFETY Command. If you decline to overwrite the table when prompted, the classes still take some actions; they investigate the table to ensure that required indexes are available and add any records they need to the table.

Assigning your own Registry Table to the Report Output Application

In the last section, you saw that, to create a registry table, you can invoke ReportOutput.app using a negative number (-100) as the first parameter you send to the program. ReportOutput.app understands negative values in this parameter as special instructions to perform maintenance chores, rather than instructions to perform its normal task of supplying ReportListener references.

ReportOutput.app reserves a second value, -200, to allow you to designate the name and location of your registry table, as shown below.

To designate your custom registry table for ReportOutput.app's use

Execute the following line of code, substituting the name and path of your custom registry table:
```
* #DEFINE OUTPUTAPP_CONFIG_READ -200
DO (_REPORTOUTPUT) WITH -200,"c:\temp\myconfig.dbf"
```

Verifying the Report Output Application's current Registry Table

At run time, ReportOutput.app maintains a reference collection of ReportListener object references. For more information, see How to: Use the Report Output Application's Reference Collection. ReportOutput.app uses a special member of this collection to hold the name of its registry table. You can use the reference collection to find out what registry table is currently in use by the Report Output Application. You can also verify the name of the current registry table by calling Report Output Application directly.

To verify the name of the current Report Output Application registry table using the reference collection

If you have issued a CLEAR ALL statement or RELEASEd the reference collection public variable after the last time you successfully invoked the Report Output Application, or if you have not yet invoked it in this session of Visual FoxPro, the collection may not yet exist. Verify that the collection exists and then check the value of the appropriate collection member
```
#DEFINE OUTPUTAPP_CONFIG_READ -200
IF VARTYPE(_oReportOutput) = "O"
  lcFile = _oReportOutput[TRANSFORM(OUTPUTAPP_CONFIG_READ)]
ENDIF
```
Examine the results you received in the variable lcFile. If it is a fully-qualified (pathed) filename, the Report Output Application is using a registry table on disk. If lcfile does not include a path, Report Output Application is using a registry table built into an application (.app or .exe).

To verify the name of the current Report Output Application registry table by calling Report Output Application

Initialize a variable to hold the name of the registry file
```
LOCAL lcFile
```
Call the Report Output Application with the special configuration value you used earlier, using the variable you initialized as its second parameter. This is similar to how you call the Report Output Application to receive a reference to a ReportListener:
```
#DEFINE OUTPUTAPP_CONFIG_READ -200
DO (_REPORTOUTPUT) WITH OUTPUTAPP_CONFIG_READ, lcFile
```
Examine the results you received in the variable lcFile. If it is a fully-qualified (pathed) filename, the Report Output Application is using a registry table on disk. If lcfile does not include a path, Report Output Application is using a registry table built into an application (.app or .exe).

Note

The reference collection is created automatically when you use this syntax.

Share via