Diagnose a Scanner - DEPRECATED

The ScanningManager diagnostic facility is invaluable to support personnel and is used to determine whether or not the scanner hardware is functioning properly. All embedded application developers are advised to include scanner diagnostics with their applications.

When ScanningManager.Diagnose is called, it will scan in a test sheet and examine the OMR buffer read by the scanner. To appreciate the information returned by Diagnose you must remember that Scantron OMR Scanners read OMR bubbles using 256 levels of gray and then map them down to 16 levels of gray (0- F).

Depending on the value passed in the mode parameter, the Diagnose method will execute in one of two ways:

• an event driven fashion (asynchronously) - it will scan in a sheet and return immediately. It will then call the event handler for DiagDataAvailable event when data is available. The bubble or read level information can then be displayed. The SessionComplete event will be fired at the end of the diagnostic session.
• synchronously - it will scan in a sheet and then display the bubble or read level information found on both sides of the sheet in a window. This method will not return until the window is closed. Diagnostic information display to the solution end user is automatic.

Should there be a problem feeding or reading the sheet, this method will present the Scanner Error Dialog (or call the event handler for ScanError event if you have chosen custom error handling via a call to ScanningManager.SetKernelErrorMode).

The steps for implementing Diagnose differ slightly depending on whether it is event driven or synchronous.

Event Driven (Asynchronous) Diagnose

To implement event driven diagnostics, do the following:

1. Create an instance of ScanningManager. By default ScanningManager assumes that you do not want to customize error handling. If you want to customize Scanner Errors, call ScanningManager.SetKernelErrorMode and set up appropriate event handlers.
2. Call ScanningManager.SetClientWindowHandle with a window handle over which you would like all ScanTools Plus dialogs to be displayed. This is the only way to ensure that all dialogs and messages displayed by ScanTools Plus are visible to the user. You could pass in a value of –1 instead of a window handle and request ScanTools Plus to create System Modal.dialogs and message boxes.
3. Call ScanningManager.Diagnose with mode and port. The first parameter is mode, which you must set to L_DIAGMODE_NODISPLAY. The second parameter is the scanner port. If your scanner is configured, use L_PORT_USE_CURRENT or the enumerated value corresponding to the scanner you want to diagnose. This call will return immediately and let the event handler take care of the rest.

NOTE: If you call Diagnose with a port other than the active scanner, ScanningManager will first call AutoConfigureScanner on that port and then attempt to Diagnose. If the call to Diagnose returns an exception (Description = "No Scanner Found", Number = 0x 8004F702) you must reconfigure the scanner or pick a different port before issuing the call again.

4. Set up an event handler for DiagDataAvailable event. This event handler has one parameter of type ScanEventArgs. The diagnostic data is available from ScanEventArgs.OmrHelper.OmrBuffer.
5. Within the DiagDataAvailable event hander, examine OmrBuffer.FrontTimingMarks and OmrBuffer.BackTimingMarks to obtain the number of timing marks detected on the front and back of the test sheet. Look at OmrBuffer.FrontBuffer to obtain the read level for each cell of each timing mark, for the front side of the test sheet. OmrBuffer.BackBuffer contains the same information for the back side of the test sheet. If you have predefined test sheets you can programmatically compare the data returned with the expected string. You can also display the data by calling OmrBuffer.Display; this call produces same graphical presentation of the data as a synchronous call to ScanningManager.Diagnose.

Synchronous Diagnose

To implement synchronous diagnostics, do the following:

1. Create an instance of ScanningManager. By default ScanningManager assumes that you do not want to customize error handling. Even if a call to SetKernelErrorMode has been made with mode = L_CLIENTHANDLES_GENERRORS, L_CLIENTHANDLES_SCANERRORS, L_CLIENTHANDLES_SCANERRORS_BASIC, or L_CLIENTHANDLES_SCANERRORS_ADVANCED, ScanningManager will ignore these values and behave as if it were called with a value of 0 during a synchronous scanning session.
2. Call ScanningManager.SetClientWindowHandle with a window handle over which you would like all your dialogs to be displayed. This is the only way to ensure that all dialogs and messages displayed by ScanTools Plus are visible to the user. You could pass in a value of –1 instead of a window handle and force all dialogs and messages come up as DeskTop Modal.
3. The first parameter to the Diagnose method is mode. Choose between L_DIAGMODE_DISPBUFFER and L_DIAGMODE_DISPREADLVL for the value of the mode parameter. The first will display the circles where bubbles are found. (values < 4 are not displayed, 4 – 8 are displayed in gray and 8 –F are displayed in black). The latter will show you the actual read level detected as a hex number between 0 and F.
4. The second parameter to Diagnose is the scanner port. If your scanner is configured, use L_PORT_USE_CURRENT or the enumerated value corresponding to the scanner you want to diagnose.

NOTE: If you call Diagnose with a port other than the active scanner, ScanningManager will first call AutoConfigureScanner on that port and then attempt to Diagnose. If the call to Diagnose returns an exception (Description = "No Scanner Found", Number = 0x 8004F702) you must reconfigure the scanner or pick a different port before issuing the call again.

5. Call ScanningManager.Diagnose with mode and port. The method will return only after the window displaying diagnose data is closed.

See also

How to Manage the Connection to ScanTools Plus Link Runtime