ReportListener Utility and File-handling Foundation Class

The UtilityReportListener class adds run-time configuration options and file handling (filename verification, file writing) to the core services provided by its parent class, _ReportListener. This class also supplies access to an instance of FrxCursor, a class leveraged from the Report Builder Application, with appropriate error handling if it cannot be found.

Note

UtilityReportListener does not require FrxCursor to function; it just provides transparent management of an instance of this class when requested by a subclass. It is up to subclasses to decide when and if they need this instance, and whether or not they can survive its absence if it is not available at run time.

Category	Reporting
Default Catalog	Visual FoxPro Catalog\Foundation Classes\Output\Report Listeners
Class	UtilityReportListener
Base Class	ReportListener
Class Library	_REPORTLISTENER.vcx
Parent Class	FXListener (ReportListener FXListener Foundation Class)

UtilityReportListener and its Configuration Table

UtilityReportListener reads records from a configuration table to initialize various ReportListener values and behavior. You can choose to have UtilityReportListener perform these tasks when the class initializes, at the start of each report run, or both. You can also call its setConfiguration method explicitly at other times.

UtilityReportListener's run-time configuration features leverage the same configuration table format as the Report Output Application uses to register custom ReportListeners for different ListenerType values. For information about how the Report Output Application uses this table, see Report Output Application.

Note

The classes use the same configuration table format as Report Output Application, but not necessarily the same table. To determine the behavior you want for an instance of a class deriving from UtilityReportListener, use the properties and methods of the class to specify that behavior in the table the object uses, not the table Report Output Application uses.

If you instantiate this class outside the Report Output Application, and if the configuration table does not appear to be available, it creates the appropriate table structure. If the class is built into a module (APP, DLL, EXE), it creates this table in the same directory as the module; otherwise, it will create the table in the same directory as the class library (VCX).

UtilityReportListener and its subclasses use the OBJTYPE field in the configuration table to determine which records belong to them, and to what use the records should be put. These classes reserve a range of values in the OBJTYPE field, set at 1000 to 1999.

Each subclass uses a single value in this range, determined by UtilityReportListener's configurationObjType property, to designate records in the table it wishes to use for configuration purposes. UtilityReportListener uses a constant value in REPORTLISTENER.H to set its own value.

Configuration tasks can set any property or invoke any method in your UtilityReportListener subclass. Records in the configuration table with the correct configurationObjType value set class properties or invoke class method code according to the following configuration table usage.

Field	Usage	Remarks
OBJTYPE	THIS.ConfigurationObjType	Determines which records in the table UtilityReportListener reads to set configuration values or trigger configuration method code.
OBJCODE	Precedence	Determines the order in which UtilityReportListener executes the configuration records' instructions.
OBJNAME	Property or Method	UtilityReportListener checks OBJNAME for PEMSTATUS (existence and type).
OBJVALUE	Value or Arguments	If the OBJNAME value is a valid property name, UtilityReportListener uses this code to set the property value using OBJVALUE: STORE EVAL(ObjValue) TO (“THIS.”+ObjName) If the OBJNAME value is a valid method name for the class, UtilityReportListener executes this code: EVAL(“THIS.”+ObjName+”(“+ObjValue+”)”
OBJINFO	Not used	Reserved for user docs, comments. See the Tip below for an example.

UtilityReportlistener ignores records with blank OBJNAME or OBJVALUE, and records marked DELETED(), whether they have the correct OBJTYPE value or not.

Tip

When UtilityReportListener generates a configuration table it provides two deleted records to show proper syntax for configuration records, using the following code:

INSERT INTO (ALIAS()) VALUES ;
  (OUTPUTCLASS_OBJTYPE_CONFIG,0,
   'DoMessage','"Welcome to the demo run!",64',
   'Sample initialization/config method call')
DELETE NEXT 1
INSERT INTO (ALIAS()) VALUES ;
  (OUTPUTCLASS_OBJTYPE_CONFIG,0,
   'TargetFileName','"xxx"',
   'Sample initialization/config property')
DELETE NEXT 1

Remarks

You will probably not instantiate this class directly; you will instantiate one of the classes that derive from it, such as HtmlListener. These derived classes take advantage of UtilityReportListener's base features, which are file-handling and access to an FrxCursor object instance. They also expose UtilityReportListener's configuration table feature so you can customize their behavior at run time, in many cases, without needing to specify these changes in your code or deriving subclasses from them.

The following table lists public properties and methods added by this class to its parent class, _ReportListener.

Properties and methods	Description
configurationObjtype Property	Holds the reserved value used to indicate that a configuration table row provides dynamic configuration information at run time. Default 1000
createConfigTable Method	Creates a configuration table on demand. Syntax:createConfigTable(cDBF [, lOverWrite] ) Return Values: cDBF Parameters: cDBF is the fully-qualified filename of the configuration table. lOverWrite indicates whether you want to overwrite the configuration table if it already exists.
frxCursor Property	Holds a reference to an FRXCursor helper object to aid in run-time calculations related to FRX metadata and structure. Default .NULL.
getConfigTable Method	Assesses and provides the name of the current configuration table, optionally creating it on disk if it is not available. Syntax: getConfigTable(lForceExternal) Return Values: cDBF Parameters: If you set lForceExternal to .T., this indicates that you want to have an external table written to disk, even if the class can find a built-in version of the table in its code module (APP, EXE, or DLL).
getPathForExternals Method	Determines the location at which the current configuration table and any other required external files will be expected. Syntax: getPathForExternals() Return Values: cPath Parameters: None
loadFrxCursor Property	Determines whether this class should dynamically load an instance of the helper class. Default .F.
readConfiguration Property	Indicates the conditions under which SetConfiguration code will run. 0=never 1 = when the class instance Init runs 2 = when the class instance runs BeforeReport 3 = at both Init and BeforeReport Default 0
setConfiguration Method	Checks the current configuration table for dynamic information in records of appropriate type, and executes these instructions if found. Syntax: SetConfiguration() Return Values: None Parameters: None
targetFileExt Property	Provides the default file extension for file output. Default "TXT"
targetFileName Property	Provides the filename to which output will be written. A unique name is generated for the class instance, which will be overwritten for successive report runs if not adjusted by the user. Default FORCEPATH (SYS(2015),SYS(2023))
targetHandle Property	Provides a low-level file handle, to which output is written directly when the class provides raw data to the file, otherwise reserves the file during the report run so other applications do not write to it. Default -1
verifyConfigTable Method	Ascertains that the format and contents of the configuration meet requirements, adjusting it if necessary. Syntax: verifyConfigTable(cAlias [, cFailureMsgTable [, cFailureMsgIndexes]]) Return Values: logical Parameters: cAlias is the alias of the table you want to validate. The table must already be opened under this alias when you call the method. cFailureMsgTable provides an optional alternative message to display if the nominated table cannot be verified as having valid configuration table format. If you do not supply this message, UtilityReportListener uses a string constant #DEFINEd in REPORTLISTENERS_LOCS.H. cFailureMsgIndexes provides an optional alternative message to display if the table does not have appropriate indexes. If you do not supply this message, UtilityReportListener uses a string constant #DEFINEd in REPORTLISTENERS_LOCS.H.
verifyTargetFile Method	Assures that the nominated filename and its network location are available at the beginning of a file-based report run. Syntax: verifyTargetFile() Return Values: None Parameters: None

See Also

Reference

Visual FoxPro Foundation Classes A-Z
ReportListener Base Foundation Class
ReportListener Object

Concepts

Guidelines for Using Visual FoxPro Foundation Classes