|
Custom Output Object Interface |
|
The Report Writer interfaces with optional user-created output objects that can be used to output the data generated by a report definition. When a report is defined, the user will be able to select Custom Output from the list of Output Destinations accessed from the File menu. This may be either a default custom output destination or one specific to the report. If Custom Output is selected for a report, a specific custom output object may be specified for the report (File > Specify Custom Destination). If none is specified, a default custom output object will be used.
To define a custom output destination, the custom object must either reside under the *rpt directory and be named *rpt/useroutput.pvc, or the global variable %RW_UserOutput$ must be pre-loaded with the object name before the Report Writer object (*rpt/pvxreport) is created. The object named in %RW_UserOutput$ will take precedence.
If the report is defined as using Custom Output and the output destination does not exist, the report will not be generated, and a status of 0 will be returned by the SetOutputDevice( ) method or RunReport( ) method, depending on the methodology for generating the report. A user-created custom output object must have properties and methods as specified in the table below.
To specify that a report is to be sent to a custom output object, the Custom Output item must be selected from the File > Output Destination menu. In this case, the default output object will be used, unless a different object is specified in the Custom Output Object Interface accessed from the File > Specify Custom Destination menu or from the Options menu or tool bar button. See Custom Interfaces.
*rpt/useroutput.pvc
A custom output object must be defined with specific properties and functions, although additional properties and On_Create/On_Delete logic may be included as desired. The required methods may contain simple stubs if there is no additional logic associated with them.
The user interface must include the following properties and methods:
|
property MaxLines |
This property contains the maximum number of lines that can be printed on a page. Example: The *rpt/rptprinter object sets 'lpi'(6) (six lines per inch) and then determines the maximum number of lines using the MXL( ) function. This value is used to determine the location of the footer, as well as for paging. In the case where vertical location is irrelevant, such as Clipboard or HTML output, this should be set to zero. |
|
property NoChannel |
Boolean value indicating output is not being sent to an output channel, such as Clipboard output. 1 - No output channel |
|
property NoPaging |
Boolean value to indicate whether paging is to occur or not. 1 - No Paging |
|
property PrinterCompatible |
Boolean value indicating whether or not the output is printer compatible, and if page properties (such as orientation and margins) are to be set up when the output device is opened. This is applicable for output to *winprt*, *pdf* and *viewer*. For example, this should be set to zero for HTML or Clipboard output. |
|
property Destination$ |
This property contains the destination file name to be opened for output. May contain "*winprt*", "*viewer*", "*pdf*", a file pathname, or blank for output to the Clipboard. |
|
property DestinationOption$ |
Set this property with the desired output option, i.e. AsIs, Default, Normal, Display, Overwrite, etc. |
|
property DestinationFile$ |
Use this property to set the output file to be specified in the FILE= clause of the open option for *winprt* or *pdf*. Leave blank if not applicable. |
|
function Initialize(Rpt) |
The object handle for the report object (*rpt/pvxreport) is passed as an argument for this function. This makes report information available to the custom output object. This method can be used to initialize variables or do various setup procedures required by the object. For example, set properties, set default font, clear the Clipboard, output HTML header information, etc. The *rpt/pvxreport object will invoke this method in its StartReport( ) method. |
|
function Getiolist$(Groupidx,Lineidx) |
Builds and returns an IOList to be used to output the line specified by the group index and line index. The contents of the IOList are based on information stored in the *rpt/rptcell objects belonging to the line. This method is invoked in the StartReport( ) method of the *rpt/pvxreport object. |
|
function FormFeed( ) |
Output a form feed. If the output does not contain form feeds, such as output to the Clipboard, this method can be defined using a simple stub. Example: function FormFeed( )=1 |
|
function TranslateSpecialChars$(Record$) |
This method can be used to modify raw record data. For example, it can be used to translate or replace certain characters in the data content to be output. In the case of HTML output, for instance, characters such as "&", "<" and ">" have special meaning within the HTML tags, so they must be translated in a special way within the data so that they are recognized and handled properly when the HTML output is processed. |
|
function PrintLine(Line$) |
Output a line of the report. |
|
function Close( ) |
Can be used to perform any wrap-up procedures that are required. For example, output closing tags for HTML output, output the final report to the Clipboard, etc. This method is invoked by the FinishReport( ) method of the *rpt/pvxreport object. |
*rpt/rptoutputTemplate
The following template is supplied for the *rpt/useroutput object, constructed with stubs for all required methods.
! *rpt/rptoutput.pvc - Template for the UserOutput object
! ________________________________________________________
!
def class "*rpt/rptoutput"
!
local Rpt ! *rpt/pvxreport object handle
!
property MaxLines
!
property NoChannel
property NoPaging
property PrinterCompatible
!
property Destination$ ! *winprt*, *viewer*, *pdf* or a file name
property DestinationOption$ ! AsIs, Default, Normal, Display, Overwrite, etc.
property DestinationFile$ ! Specified in FILE= option for *winprt* or *pdf*)
!
function Initialize(Rpt)
enter Rpt
return 1
!
function GetIolist$(Groupidx,Lineidx)=""
function FormFeed()=1
function TranslateSpecialChars$(r$)=r$
function PrintLine(Line$)=1
function Close()=1
!
end def
When creating the *rpt/useroutput object, it is recommended that the class definition include a LIKE "*rpt/rptuseroutput" statement. This means that stubs are present for methods that are not required, and the user need only supply properties and methods for which there is additional logic. It also ensures that stubs will be present for new methods that may be required in future enhancements.
Alternately, custom output objects can be based on any of the existing output objects, *rpt/rptprinter.pvc, *rpt/rpthtml.pvc or *rpt/rptclipboard.pvc.
Example:
The following sample object, which outputs a PDF file, is based on *rpt/rptprinter.pvc:
def class "outputpdf"
like "*rpt/rptprinter"
property Destination$="*pdf*"
property DestinationFile$=%PDFfile$
end def
To generate a report defined using the above sample output object, "outputpdf" would have to be specified as the custom output object for that report when the report was defined. Then, code such as the following can generate the report directly to a PDF file and display it:
%PDFfile$="c:\tmp\sample.pdf"
r=new("*rpt/pvxreport")
r'RunReport("MyReport.pvr")
drop object r
system_help %PDFfile$