Visual Basic Concepts

  • Article

Data Report Events

Like the standard Visual Basic form, the life of a Data Report designer is marked by certain key events. Those events, and the order in which they occur, are shown in the following table:

Event Description
Initialize Occurs after the query has completed, and controls are sited on the form.
Resize Occurs when the designer is first displayed or when the window state of an object changes.
Activate Occurs when the designer becomes the active window.
ProcessingTimeout Occurs approximately once every second until all processing has ended. Use this event to determine if processing has taken too long, and to cancel the processing.

Note   This event will not occur until the query has completed. See below.
[Deactivate] Occurs when the designer is no longer the active window. Use this event to determine if the user has clicked another form or designer.
QueryClose Occurs before the designer is terminated. Set the Cancel argument to True to cancel termination. The CloseMode argument returns the type of action that is causing the termination.
Terminate Occurs when all references to the designer have been set to 0.

Timeout and Asynchronous Call Events

In addition to the designer's lifetime events, the DataReport object also features events that allow you to trap errors and monitor synchronous and asynchronous function calls.

ExportReport and PrintReport: Query, Synchronous and Asynchronous Processes

When either the ExportReport or PrintReport method is invoked, the process is divided into three stages—the query, synchronous processing, and asynchronous printing or exportation:

  1. Query—When the data report is first created, a query is sent to the data provider.

  2. Processing—The data retrieved by the query is processed by Visual Basic to create the report. The data is cached in a temporary file on the computer. This process is synchronous.

  3. Asynchronous Printing or Exporting—After creating the report, the report is exported or printed. This process is asynchronous.

When the Show method is invoked, the data report executes the query and then processes the data in a synchronous process before displaying the report.

Because these methods combine both synchronous and asynchronous processes, there are separate events to monitor each kind of process.

The ProcessTimeOut Event—for Synchronous Functions

Processing a large data report may take some time. If you want to allow your users to cancel out of a lengthy operation (such as Show, ExportReport, or PrintReport), you can use the ProcessingTimeout event to monitor how many seconds have passed, and set the cancel argument to True at the user's command. The code below shows an example.

Private Sub DataReport_ProcessingTimeout(ByVal Seconds As Long, _
Cancel As Boolean, ByVal JobType As MSDataReportLib.AsyncTypeConstants, _
ByVal Cookie As Long)
   Select Case Seconds
   Case 30
      If MsgBox("This has taken " & Seconds & "seconds. Cancel?", _
         vbRetryCancel) = vbCancel Then
            Cancel = True
      End If
   Case 45
      If MsgBox("This has taken " & Seconds & "seconds. Cancel?", _
         vbRetryCancel) = vbCancel Then
            Cancel = True
      End If
   Case 60
      'Cancel automatically after 60 seconds.
      Cancel = True
   End Select
End Sub

Note   It is not guaranteed that the ProcessingTimeout event will occur at the intervals specified above. For example, other Visual Basic code running in the background may prevent the event from occurring. In that case, set the Case statement to a range of values; when the event occurs, set a module-level flag to True, and check it on subsequent occurrences.

Error Event—For Asynchronous Functions

To trap errors that occur when no Visual Basic code is executing (that is, an asynchronous function), use the Error event. For example, if the PrintReport or ExportReport method fails in the asynchronous stage, the Error event will occur. The example below traps asynchronous errors:

Private Sub DataReport_Error(ByVal JobType As _
MSDataReportLib.AsyncTypeConstants, ByVal Cookie As Long, _
ByVal ErrObj As MSDataReportLib.RptError, ShowError As Boolean)
   Select Case JobType ' The JobType identifies the process.
   Case rptAsyncPrint
      ' Trap PrintReport errors here.
   Case rptAsyncReport
      ' Trap ExportReport errors here.
   End Select
End Sub

You can also use the Error event to trap specific cases, such as the lack of a printer on the computer, as shown in the code below:

Private Sub DataReport_Error(ByVal JobType As _
MSDataReportLib.AsyncTypeConstants, ByVal Cookie As Long, _
ByVal ErrObj As MSDataReportLib.RptError, ShowError As Boolean)
   Select Case ErrObj.ErrorNumber
   Case rptErrPrinterInfo ' 8555
      MsgBox "A printing error has occurred. " & _
      "You may not have a Printer installed."
      ShowError = False
      Exit Sub
   Case Else
      ' handle other cases here.
      ShowError = True
   End Select
End Sub

The AsyncProgress Event

The AsyncProgress event is not designed to trap errors, but to allow you to monitor the state of the asynchronous function. By the time this event occurs, all of the data has been processed; thus two of the event's arguments are PagesCompleted and TotalPages. The event also includes arguments that identify the asynchronous operation: the JobType and Cookie arguments can then be used to monitor the progress of any process.