Handling Errors During Report Runs

Visual FoxPro 9.0 provides significant enhancements to the process of creating output, including new opportunities to invoke application code during the native Report System's internal data-handling and output-rendering procedures. To adequately provide users with the ability to develop such programs, Visual FoxPro 9.0 also enhances error-reporting and debugging during a report run.

This topic covers error-handling features with special significance for reporting, and examines different strategies for handling abnormal conclusions of report runs.

Strategies for error-handling during a report run

Because Visual FoxPro's output processing sequence can include extensive user code, you may need to end a report run before it finishes due to a code error. You may also want to end a report run prematurely because an end-user wants to interrupt the report. Additionally, an external error handler may detect a reason to end your application, while a report run is in process.

In all these situations, you can call the ReportListener CancelReport method to make sure Visual FoxPro does any special cleanup, such as closing a print queue, necessary to end the report, and your application, safely. See CancelReport Method for more information.

The ReportListener User Feedback Foundation Class provides a good model for canceling a report in response to an end-user request. See the DoMessage Method topic for the code in this class' CancelReport Method. Notice that the method issues a NODEFAULT if the end-user opts to resume running the report in response to a dialog box. Your code can follow a similar strategy in response to recoverable errors. For critical errors, you may prefer to end the report unilaterally, and end the application following report clean-up.

You can check to see whether the report ended normally using the SYS(2024) function. This function will return "Y" during a report run, through the conclusion of the Unload Event, if the report did not complete its run normally. At this point, the internal Visual FoxPro Report System processing has concluded. If you determine that the abnormal end to the report run did not occur as a response to an end-user's request, you can safely CANCEL or QUIT or request similar handling from an external application object. For more information, see Microsoft Visual FoxPro Technical Support.

Example 1: Cancelling a report

In the following example, an error occurs in a ReportListener's BeforeReport event, and its Error event responds by calling the class' CancelReport method. The UnLoadReport event code reports the value of SYS(2024) as "Y," as a result of the Error event's action.

DEFINE CLASS errorListener as ReportListener
  PROCEDURE BeforeReport()
    REPORT FORM ? 
  ENDPROC
  PROCEDURE Error(nError, cMethod, nLine)
     WAIT WINDOW MESSAGE() 
     * MESSAGE() will report:
     * Report contains a nesting error.
     THIS.CancelReport()
  ENDPROC
  PROCEDURE UnloadReport()
     WAIT WINDOW SYS(2024)
     * SYS(2024) will report: "Y"
  ENDPROC
ENDDEFINE

Example 2: Ending an application as a result of report error

In the example above, the ReportListener-derived class handles the error. You may prefer to bubble the error event to an external application handler for determination of appropriate action. In this case, the external application needs to know that a report run was in progress when the error occurred, so it can cancel the report properly before ending the application.

To determine that a report run is in progress in external code, use the SYS(2040) function. For more information, see SYS(2040) - Detect Report Status.

The following example checks the return value of SYS(2040) in an ON ERROR Command handler.

PUBLIC oApp
oApp = CREATEOBJECT("MyApp")
ON ERROR oApp.ErrorHandler()
WAIT WINDOW "Some processing here..."
REPORT FORM ? OBJECT oApp.oE
WAIT WINDOW ;
  "Some more processing here, " + ;
  "will not occur because of error..."  

DEFINE CLASS MyApp AS Custom
   oE = NULL
   PROCEDURE Init
      THIS.oE = CREATEOBJECT("errorListener")
   ENDPROC
   PROCEDURE ErrorHandler
     MESSAGEBOX("Error! " + MESSAGE())   
     IF SYS(2040) # "0"
       THIS.oE.cancelReport()
     ENDIF
    IF _VFP.StartMode = 0
       CANCEL
    ELSE
       QUIT
    ENDIF
  ENDPROC
ENDDEFINE    

DEFINE CLASS errorListener as ReportListener
  PROCEDURE BeforeBand()
    * parameters are missing
  ENDPROC
  PROCEDURE CancelReport()
    DODEFAULT()
    MESSAGEBOX("Cancelling Report!")
  ENDPROC
ENDDEFINE

Example 3: Canceling a report during application shutdown

You can use a similar strategy in an ON SHUTDOWN handler if it is possible for this handler to be called during a report run. The ON SHUTDOWN handler needs a reference to the appropriate ReportListener object, just as the application object in the example above does. For more information, see ON SHUTDOWN Command.

You can use the following simple example to verify this capability.

PUBLIC rl
ON SHUTDOWN DO MyShutdown

rl = CREATEOBJECT("reportListener")
REPORT FORM ? OBJECT rl  && use a long report!
* use the close box on the main Visual FoxPro
* window while the report runs.

PROCEDURE MyShutDown
  IF SYS(2040) # "0"
     MESSAGEBOX("Now Cancelling Report!")
     rl.CancelReport()
  ENDIF
  ON SHUTDOWN
  IF _VFP.StartMode = 0
     CANCEL
  ELSE
     QUIT
  ENDIF
ENDPROC

Example 4: Using a ReportListener's Error event

In two of the three examples above, the ReportListener class does not have Error event code. If you include Error event-handling in a ReportListener class, as shown in the first example, this code can decide to handle, or bubble, any error it receives.

If the Error event handles an error, it can safely use CANCEL or QUIT. You can use these commands in other ReportListener events or methods as well. Be sure to invoke the ReportListener's CancelReport() method before issuing the CANCEL or QUIT statement, however.

In the next example, the ReportListener class uses its Error event to handle the error, and then ends the report immediately.

LOCAL oE
oE = CREATEOBJECT("errorListener")
WAIT WINDOW "Some processing here..."
REPORT FORM ? OBJECT oE
WAIT WINDOW ;
  "Some more processing here, " + ;
  "will not occur because of error..."  
  
DEFINE CLASS errorListener as ReportListener
  PROCEDURE BeforeBand()
    * parameters are missing
  ENDPROC
  PROCEDURE Error(nError, cMethod, nLine)
   WAIT WINDOW "Error occured! " + CHR(13) + ;
               "SYS(2024) before CancelReport: " + SYS(2024) 
   THIS.CancelReport()  
   CANCEL
  ENDPROC
  PROCEDURE CancelReport()
    IF SYS(2040) # "0"
       MESSAGEBOX("Cancelling Report!") 
       DODEFAULT()
       WAIT WINDOW "SYS(2024) is now: " + SYS(2024) 
    ENDIF
  ENDPROC
ENDDEFINE

Example 5: Using structured error handling with reports

As a final strategy, you can use structured error handling with reports. When you run the sample code below, however, notice that your code does not get to the CATCH construct until after the report run has ended, from the Report System's perspective. Although you can use the CancelReport method, the user code you run in this method should be designed to run safely whether or not a report is actually in progress.

LOCAL oE

TRY
  oE = CREATEOBJECT("errorListener")
  WAIT WINDOW "Some processing here..."
  REPORT FORM ? OBJECT oE
  WAIT WINDOW ;
  "Some more processing here, " + ;
  "will not occur because of error..."  
CATCH WHEN .T.
   WAIT WINDOW "An error occured! " + CHR(13) + ;
               "SYS(2024)=" + SYS(2024) + CHR(13) + ;
               "SYS(2040)=" + SYS(2040)
   * SYS(2024) will report "N"
   * SYS(2040) will report "0"
   oE.CancelReport()
ENDTRY
   
DEFINE CLASS errorListener as ReportListener
  PROCEDURE BeforeBand()
    * parameters are missing
  ENDPROC
  PROCEDURE CancelReport()
    IF SYS(2040) = "0"
       MESSAGEBOX("No report in progress, " + CHR(13) + ;
                  "but this method can still do user cleanup!")
       NODEFAULT
    ELSE
       MESSAGEBOX("Cancelling Report!") 
       DODEFAULT()
    ENDIF
  ENDPROC
ENDDEFINE

Errors during a report run that do not occur in lines of code

In Visual FoxPro 9.0 and all earlier versions, it is possible for errors to occur during report runs that are not specifically associated with a traceable line of user code. Such errors include report expressions or report variables that the Report Engine cannot resolve, as well as difficulties initializing the report's Data Environment.

Visual FoxPro 9.0 maintains backward-compatibility with its handling of such errors, as described in this section.

When an error occurs outside user code, Visual FoxPro's internal error handling does not offer you an opportunity to suspend the report, because there is no line of code on which to suspend.

If you do not have an ON ERROR handler or a TRY… ENDTRY construct in place, Visual FoxPro does not invoke your error handling until after it does its internal cleanup and ends the report run.

As demonstrated in the examples in this topic, the value of the MESSAGE() function is available if it occurs in ReportListener code or other user code you invoke during a report run. However, if the error is not associated with a line of code, MESSAGE() is not assigned until after the Report Engine concludes its cleanup.

If an error is not associated with a line of code, the value of MESSAGE() is not assigned at all unless you have some form of error-handling in place at the time the REPORT FORM or LABEL command occurs. If you do not have an error handler, and if you have used the CLEAR ERROR command before the report run, MESSAGE() is still empty after the report run. If you have not used CLEAR ERROR, MESSAGE() retains its previous value.

Commands not supported during a report run

To error-handle well, you should start by planning to use only commands that are safe to use during a report run.

The Visual FoxPro commands in the table below are all unsupported during internal output processing, between the BeforeReport event and AfterReport event (inclusive).

Not all the errors in this table will generate an immediate error, but use of these commands during output processing leads to unpredictable results.

These commands are unsupported whether they occur:

• Directly in ReportListener event code.

• In additional code invoked by a ReportListener, such as code in a procedure library.

• In the command window while execution is suspended.

• Using code invoked directly in report or label expressions, such as user-defined functions (UDFs).

In some cases, as indicated in the table, the commands are also not supported in the ReportListener's LoadReport Event and UnloadReport Event. These two framing events provide user hooks at each end of the internal processing run.

As a final, exceptional case, while the OutputPage Method may be running after the report run concludes, if called by a PreviewContainer object, this method may need access to resources built into the application, such as image files, to perform its task. For this reason, using commands such as CLEAR ALL that might unload the calling application from memory are not supported until the preview concludes. When the REPORT FORM or LABEL command includes the NOWAIT keyword, the preview concludes at the time the preview window closes, unless the user chooses to print from preview. If the user chooses to print, the preview concludes at the time Visual FoxPro finishes sending the report output to the printer.

Errors associated with the Visual FoxPro Report System

The following table provides a list of errors that can occur for reasons specific to the run-time processing of reports and labels.

See Also

Reference

TRY...CATCH...FINALLY Command
Debugging and Error-Handling Language
Error Event (Visual FoxPro)
CANCEL Command
QUIT Command
MESSAGE( ) Function
CLEAR Commands

Concepts

Structured Error Handling
Class and Object Error Handling
Handling Run-Time Errors
Error Handler Priority