Handle Scanner Errors Overview

ScanTools Plus Link allows you to customize the handling of scanner errors in your program. These errors occur in the context of a scanning session initiated by a call to the Scan or Diagnose method of the ScanningManager class.

ScanTools Plus Link expects you to commit to one of the following before initiating a scanning session:

• Indicate that the solution does not want to receive events for scanning errors
• Not Handling Scanning Errors
  1. Call ScanningManager.SetKernelErrorMode with 0 as the argument. This call instructs ScanningManager to not fire any ScanError events but to instead display the scanner error dialog.  
  2. Make the call to ScanningManager.Scan or ScanningManager.Diagnose

  ScanTools displays the scanner error dialog as needed, transparent to the solution program

• Indicate that you want to handle errors in a basic fashion. You want ScanTools to clear the transport if possible before firing the ScanError event.
• Indicate that you want to take more control of handling scanning errors, including whether and when to clear the transport.

By default, ScanTools Plus Link assumes that the solution does not handle scanning events.

There are two broad categories for scanning errors, depending on whether the transport is stopped or still running. To customize the handling of scanner errors in your program, follow one of these paths:

Basic Scanner Error Handling

Basic scanner error handling customization scenarios are those where you want the transport stopped and sheet(s) flushed from the scanner bed before taking a custom action:

• You want to localize the scanning error dialog for a culture other than English.
• You want to end a batch when the input hopper goes empty without displaying the scanner error dialog. However you do want the user to see the scanner error dialog in other cases.
• You want to capture images for later review when a specific scanning error occurs.
• You want to monitor and/or log errors but defer display of the scanner error dialog to ScanTools Plus.
• You want to suppress the ScanTools error dialog for a specific subset of the errors.
• You want to handle Scanning Errors After the Transport is Stopped
  1. Call ScanningManager.SetKernelErrorMode with L_CLIENTHANDLES_SCANERRORS_BASIC.
  2. Set up an event handler for the ScanError event. Like all the other events, this event has a single parameter of type ScanEventArgs. ScanEventArgs.Errors is a collection of ScanError objects.
  3. Respond to the scanner error within the ScanError event handler and return. Control passes back to ScanTools. Otherwise, proceed to the next step. (This involves more effort on your part.)
  4. Display custom scanner error dialog. You should now exit the event handler. Scanning will not resume automatically upon exit from the event handler. Scanning will resume only after the user has responded to the error by either:

  • Responding to the modeless dialog described above. See step 5.
  • Pressing the Start button on the scanner. See step 6.

  5. Respond to user input within the custom scanner error dialog.
  6. Set up an event handler for the ScannerButtonPressed event. This handler is called when a scanner error is active and the user presses the Start button on the scanner. When this event is called, you must terminate your custom scanner error dialog to prevent it from being displayed forever.

   

Basic Scanner Error Handling Flow Chart

Advanced Scanner Error Handling

Advanced scanner error handling customization scenarios are those where you may want to explicitly stop the transport in some cases and continue running in others, depending on the program’s ability to resolve the situation on its own. This is especially true with high-throughput scanners or if you want to enhance the user experience in some way with small scanners.

• You want to silently ignore header sheets without the operator’s intervention so as not to slow down the scanner.
• You want to identify a document that has a form identification error.
• You want to handle unscannable documents in a particular way.
• You want to handle Scanning Errors While the Transport is Still Potentially Running
  1. Call ScanningManager.SetKernelErrorMode with L_CLIENTHANDLES_SCANERRORS_ADVANCED.
  2. Set up an event handler for the ScanError event. Like all the other events, this event has a single parameter of type ScanEventArgs. ScanEventArgs.Errors is a collection of ScanError objects.
  3. Within the error handler, examine ScanEventArgs.Errors.CanIgnoreError.

  If this is true, further examine ScanEventArgs.Errors collection and decide a course of action:

  • Handle ignorable errors within the ScanError event handler itself and return.
  • Call ScanningManager.SetScanErrorResolution (L_SCANERROR_RESOLUTION_ENUM. L_SCANERROR_RESOLUTION_CLEAR_TRANSPORT_AND_UPDATE_ERRORS) right away within this event handler. Error recovery information is updated so that corrective action can be displayed to the user. Proceed to Step 4.
  • Respond to the scanner error within the ScanError event handler and return. Control will pass back to ScanTools.

  If ScanEventArgs.Errors.CanIgnoreError is false, examine ScanEventArgs.Errors collection and decide a course of action:

  Respond to the scanner error within the ScanError event handler and return. Control will pass back to ScanTools. Otherwise proceed to Step 4.

  • Display custom scanner error dialog. You should now exit the event handler. Scanning will not resume automatically upon exit from the event handler. Scanning will resume only after the user has responded to the error by either:
    • Responding to the modeless dialog described above. See step 5, below.
    • Pressing the Start button on the scanner. See step 6 below.
  • Respond to user input within the custom scanner error dialog.
  • Setup an event handler for the ScannerButtonPressed event. This handler is called when a scanner error is active and the user presses the Start button on the scanner. When this event is called, you must terminate your custom scanner error dialog to prevent it from being displayed forever.

Advanced Scanner Error Handling Flow Charts

Error NOT IGNORABLE

Error IGNORABLE

Common Use Cases

• Handle Ignorable Errors Within the ScanError Event Handler and Return

  • To ignore the sheet, call:

  ScanningManager.SetScanErrorResolution (L_SCANERROR_RESOLUTION_ENUM. L_SCANERROR_RESOLUTION_IGNORE_SHEET) within this event handler and simply return.

  • To ignore the error, call:

  ScanningManager.SetScanErrorResolution (L_SCANERROR_RESOLUTION_ENUM. L_SCANERROR_RESOLUTION_IGNORE_ERROR) within this event handler and simply return.

• Respond to User Input on the Custom Scanner Error Dialog

  To have ScanTools Plus display its Scanner Error Dialog, call ScanningManager.SetScanErrorResolution (L_SCANERROR_RESOLUTION_ENUM.L_SCANERROR_RESOLUTION_DISPLAY) within this event handler and simply return. The scanner transport will be flushed and ScanTools Plus will display its standard Scanner Error Dialog and the operator can attend to the scanning errors as desired.

• Display Custom Scanner Error Dialog Within the ScanError Event Handler and Return Control to ScanTools

  ScanTools waits indefinitely for a scanner error resolution from the solution.

  Create a modeless dialog. Within ScanEventArgs and ScanEventArgs.Errors, you have access to all the information that would have otherwise been displayed on the ScanTools Scanner Error Dialog:

  • RecoveryString property describes what you must do to recover from the error condition.
  • ExpectedSheetString property returns the next sheet that the scanner expects as a string.
  • ExpectedSheetNo property returns the numerical version of ExpectedSheetString.
  • Each individual element ScanError in the ScanErrors collection has detailed information about one possible error condition. The property ScanError.Category (of type L_ERRCAT_ENUM) uniquely identifies the possible error while ScanError.Description returns the same description of the error that would have been displayed in the Scanner Error Dialog.

  The dialog should also have 3 buttons that correspond to the three possible ways in which the error condition may be resolved.

  • Resume button - to resume scanning the current booklet from the next expected sheet.

  NOTE: If a litho-code mismatch error occurs, rename the Resume button to "Rescan".

  If ScanError.Category is L_ERRCAT_ENUM. L_LITHO_OMR, use ScanningManager.SetScanErrorResolution set to L_SCANERROR_RESOLUTION_RESUME to ignore the error.

  See Document.Litho code property.

  • Rescan button - to discard scanned data and rescan the current booklet from sheet 1.
  • Stop button - to stop the scanning session.

  When you display a custom error dialog, your solution code can hold a reference to ScanEventArgs for use after the ScanError event handler has returned.

• Implement Attachments

  • Use ClipHelper to capture a full-sheet image.

  See the following topics:

  GetClip5_method

  GetClipAsStream4_method

  WriteClipToFile4_method

  WriteClipToStream4_method

  NOTE: Specify world coordinates.

  • Call SetScanErrorResolution to request that ScanTools ignore this sheet.

• Respond to User Input on the Custom Scanner Error Dialog

  • When the user presses one of the buttons on the custom scanner error dialog, you should call ScanningManager.SetScanErrorResolution to communicate the user's decision to ScanningManager.

  • SetScanErrorResolution takes one parameter of type L_SCANERROR_RESOLUTION_ENUM that corresponds to the desired resolution.

  • On a litho-code mismatch error, use L_SCANERROR_RESOLUTION_RESUME.

• Lithocode Errors

  If a litho-code match error occurrs, it is ignored by ScanTools. Determine if a litho-code error occurred by enumerating the ScanErrors collection. Otherwise ScanTools continues as if the current sheet was not scanned. This is the same as L_SCANERROR_RESOLUTION_IGNORE_SHEET.

  NOTE:On a litho-code error, be sure to change the labels of the buttons as follows:

  • Resume becomes Rescan (Document).

  • Rescan becomes Ignore Error.

See Also

Scanner Differences