CancelReport Method
Allows the user or a program to abnormally terminate a report run, similar to pressing Esc.
oReportListener.CancelReport()
Parameters
None.
Return Value
None.
Remarks
Applies To: ReportListener Object.
Using CancelReport, you can terminate a report early. When you invoke this method, the baseclass ReportListener provides necessary cleanup code, for example closing the print queue, after checking to see whether a report is running before attempting its cleanup chores.
.gif "Important note") Important Note: |
|---|
If you are debugging report code or handling errors during a report run, you should invoke this method before you issue a CANCEL or QUIT command. You should also check for an active report run in procedures invoked by an ON SHUTDOWN handler. You can use the SYS(2040) function to check for an active report. See SYS(2040) - Detect Report Status for more information. |
You can add to Visual FoxPro's internal cleanup code in this method. However, you should provide for the possibility that this method is called by external sources such as error handling routines attempting to exit an application gracefully. For this reason, your code in this method should not fail even if a report is not actively running, similar to ReportListener's native behavior.
For example, if your code sets a global property indicating that a report has failed to run, it should make sure the ReportListener was actually in the process of running a report before setting the flag.
When you invoke CancelReport, normal reporting events continue until the end of the current page. After this, the native cleanup code runs, followed by the AfterReport and UnloadReport events. For more information about the reporting event sequence, and the time period during which you can successfully cancel a report, see Understanding Visual FoxPro Object-Assisted Reporting.
You can check whether a CancelReport call occurred, abnormally terminating the report, by using the SYS(2024) function. For more information, see SYS(2024) - Detect Report Cancellation.
Tip
You can provide an opportunity for users to cancel a report in this method, but also offer them the choice to continue running the report. Use NODEFAULT in the CancelReport method to continue the report run. The ReportListener User Feedback Foundation Class takes this approach. Refer to the DoMessage Method for the complete text of this class's CancelReport method code. See ReportListener User Feedback Foundation Class for more information.
See Also
Concepts
Handling Errors During Report Runs