12.7 Exceptions and Errors

All public methods exposed by the ClientLib APIs can throw Exceptions.

Each of these indicate that some unexpected condition has occured either in the ClientLib itself, or on the a currently connected SP-ICE-3 Card.

Note
Please refer to 12.1 ClientLib and NativeLib API Implementations for details of the Error reporting mechanism implemented by the NativeLib.

How the ClientLib reports exceptions occuring locally.

When the ClientLib itself is the source of the exception (of any type), the exception will be thrown without change to the calling application in the usual manner.

How the ClientLib reports exceptions occuring on the SP-ICE-3 Card.

An exception thrown by the card's firmware will be passed back to the ClientLib in serialized form via the RPC protocol.

Once the ClientLib has de-serialized the exception, it will be thrown without change to the calling application in the usual manner.

The application can then catch it, examine its information fields, and decide upon an appropriate course of action.

The SP-ICE-3 Card's firmware may throw Standard or SP-ICE-3-Specific exceptions.

The exception will normally carry at least a simple message describing the nature of the problem.

If possible, it will also give you the exact context in which everything went pear-shaped:

the name of the failing command,
the passed values of any parameters,
the command's position within the currently executing List (if applicable),
and a reasonably complete Stack Trace.

When the ClientLib reports exceptions occuring on the SP-ICE-3 Card.

Problems are generally reported as soon as they are detected during a call of a combined ClientLib/SP-ICE-3 Card method.

Sometimes, however, the problem is not, or even cannot be, detected until run-time, when a CommandList is being executed.

This is the case, for instance, with:

bad values of CommandCode Parameters;
calculated values of scanner co-ordinates which fall outside the available scanning field;
etc.

Exception Categories

Exceptions thrown by functions in the ClientLib API may be divided into three broad categories:

Standard
RPC-related
SP-ICE-3-specific

Standard Exceptions

The C# Language and Runtime Framework define many standard exceptions.

These include: ArgumentOutOfRangeException; NullReferenceException; etc, etc.

Since all of the standard exceptions are adequately documented elsewhere, we will not concern ourselves further with them here.

RPC Exceptions

The MsgPack-RPC library usually makes its presence felt only when something completely bogus occurs within the RPC protocol between the ClientLib and the SP-ICE-3 Card.

For instance: trying to call a function which does not exist on the card - although this should be practically impossible, assuming you're using the ClientLib to talk to the card, and given the compatibility checking which takes place automatically when the ClientLib first makes contact with the card.

SP-ICE-3-specific Exceptions

The RAYLASE.SPICE3 namespace defines several specialised exception types, which allow precise reporting of problems within the context and execution model of the combined ClientLib and SP-ICE-3 Card system.

Here is a list of all the currently defined specialised exceptions, together with some general hints on how to avoid them:

Exception	Typically Thrown By	Possible Remedies
AbortedException	ListAPI.TryWaitForXXX(), ListAPI.WaitForXXX()	Do not press the abort button again...
ExecutionException	ListAPI.TryWaitForXXX(), ListAPI.WaitForXXX()	Use the information contained in the error message to modify properties of ProcessVariables or contents of CommandLists as necessary.
FatalException	ListAPI.TryWaitForXXX(), ListAPI.WaitForXXX()	Please refer to SP-ICE-3 Fatal Exceptions. Use the information contained in the error message to modify properties of ProcessVariables or contents of CommandLists as necessary.
ListLabelException	ListAPISet	Check how your application constructs its CommandLists.
ListExecutionException	ListAPI.TryWaitForXXX(), ListAPI.WaitForXXX()	Use the information contained in the error message to modify properties of ProcessVariables or contents of CommandLists as necessary.
ListNotFoundException	ListAPIExecute	Verify the ListID's used by your application.
NotConnectedException	Any API method that attempts to communicate with the SP-ICE-3 Card.	Verify the method your application uses to connect to the card(s). Verify that the card is operating normally, and (if applicable) is currently reachable via the network.
OutOfFieldException	ListAPI.TryWaitForXXX(), ListAPI.WaitForXXX()	Verify ScannerConfigFieldSize and MotfConfig parameters, and the coordinates used in your CommandLists.
PowerOverflowException	ListAPI.TryWaitForXXX(), ListAPI.WaitForXXX()	Use the information contained in the error message to modify properties of ProcessVariables or contents of CommandLists as necessary.
ScannerCommunicationException	ScannerCommunicationAPIReceiveEnhanced, ScannerCommunicationAPITransceiveEnhanced, ScannerCommunicationAPITransceiveRaylase	Verify the physical power and data connections to the scanner( s). Or Check that the correct ScanHeadFormat has been selected by your application.
VersionMismatchException	ClientAPIConnect	Use a ClientLib whose API-version matches that of the card's firmware. Please refer to: 17.7 How to check Firmware and ClientLib compatibility for further information. Or Update the Adapter Board's firmware to match the card's, or vice versa.

SP-ICE-3 Fatal Exceptions

FatalExceptions are thrown by the SP-ICE-3 Card when it detects certain unrecoverable error conditions during command execution.

The FatalException carries an Error property that indicates the underlying error condition.

Here are possible causes and remedies for some currently defined FatalExceptionErrors:

Error: FifoUnderflow

Causes

As explained in Parsing and Execution of List Commands, parsing a command and calculating the associated output data entails a significant processing overhead compared with simply incrementing the position for each step period.

When the FPGA has taken the last available data item from the FIFO, but the firmware fails to push at least one new data item into the FIFO within the 10µs step period, the FPGA will signal the FifoUnderflow error.

The command parsing overhead becomes increasingly significant as the length represented by vector commands (JUMP, MARK, etc) decreases, or in other words, as the required number of step periods per vector command decreases.
Some functionality inherently increases the command parsing overhead: Power Ramping , or Dashed Lines, for example.

Polling via the ClientAPI to obtain current execution status or to monitor the scanners while list-execution is in progress can cause a significant extra workload for the SP-ICE-3 Card's CPU.

Please refer to 12.6 Best Programming Practices.

Possible Remedies

Adjust appropriate parameters of the generating program so that the macro-vectors are "longer".

For instance:

Action	Effect
Decrease the marking speed.	Increases the number of step periods needed to traverse the complete vector.
Reduce the number of straight-line segments used to approximate curves.	Increases the number of step periods needed for each such segment.

If possible, avoid the use of Power Ramping in combination with very short vectors.
Do not use any form of polling to obtain the current execution status, or to monitor the scanners, or to retrieve any other kind of dynamic data asynchronously from the card.
Instead, use an event-driven programming model in your application to retrieve such data via the ClientAPI.