Error Handling

	IMPORTANT
	This entry is outdated and requires revision.

---

Introduction

Error handling is the method used to react to and process fatal and non-fatal errors that occur during the operation of the softMC. You can handle non-fatal faults, but not fatal faults. Fatal faults cause a WatchDog timer to be triggered. All errors have corresponding default actions to be taken when they occur.

There are three contexts in which an error can occur and be handled: task, system, and terminal. The following definitions will help you while reading through this chapter:

Term	Definition
Internal error action	Immediate action taken by the system software when an error occurs. This action cannot be turned off or bypassed.
Default system error action	Action taken by the system according to the context and severity of the error if the user does not handle the error. All default system error actions can be bypassed by defining error handler functions.
Synchronous error	Error caused by the user task and detected by the interpreter. This type of error is associated with a specific line of program code in the user-defined task. Examples include division by zero and out of range parameters in a MOVE command. The task that caused the error is stopped.
Asynchronous error	An error caused by the user task not associated with a specific line of program code. Examples include following error and motion overspeed.

Context

When an error occurs in the softMC system, it occurs in one of three contexts: task, system or terminal. It is important to recognize the differences among these three since the action taken by the system varies, depending on the context.

Task Context

Errors occurring as a result of an executing task take place in the task context. Asynchronous and synchronous errors occur in this context. A specific line of code causes synchronous errors. An asynchronous error that occurs in a task is not associated with a particular line of program code. A good example of an asynchronous error caused by a task is a following error. This occurs due to a difference between commanded position and actual position. This error may occur when an element being commanded to move comes up against a mechanical obstacle. The following figure shows the process flow that occurs in the task context.

During the internal error action, the synchronous error is logged in the softMC and the task is idled. The default system error handler stops all motion and all attached tasks.

In the figure above, there are two mechanisms for trapping and dealing with errors: OnError and Try/Finally blocks. These two error-handling mechanisms allow you to write your program to respond to errors.

OnError

The OnError block is handled like an event handler. An event handler lets your program respond to events. The OnError block allows your program to catch errors. OnError overrides default system error action if OnError traps error. Main program execution is stopped while the OnError block is executing and must be resumed if that is desired. An example of this is shown later in this section.

Add an OnError code block to your program between the Program and End Program section of your program.

The number of Catch statements in an OnError block is not explicitly limited. Catch Else may optionally be used. If you want a task to resume after an error has occurred, use CONTINUETASK.

You can use GoTo within the error handler. However, because OnError interrupts the main program, you cannot use GoTo to branch outside the error handler. You cannot place an OnError block in the middle of program flow. The scope of OnError is that of the task withing which it is contained. It only handlers errors that occur within that task.

Try/Finally

Unlike an OnError block, the Try/Finally block may appear anywhere in the main program section of the task. It can be used to take specific action with relation to a particular area of your program code. This type of error handler block only traps synchronous errors in the task context. The block is started using the Try keyword and is terminated with the End Try keyword.

Try blocks can be nested. The program lines between the line causing the error and the matching catch statement are skipped. The interpreter tries to trap an error starting with the innermost catch statement. If there is no matching catch statement, the error is handled as a regular synchronous error. Errors trapped inside the Try block are not logged. The Finally statement is executed only if an error occurred and was caught inside the Try block.

System Context

System context is the lowest level of the three contexts. It refers to errors not directly related to specific tasks. Errors that occur in this context affect all running tasks. The default system error handler processes these errors. Examples of system context errors include Floating Point Unit errors, CPU errors, SERCOS communication errors and errors that occur on motion elements not attached to specific tasks.

OnSystemError

OnSystemError traps and processes all errors in the system context. It is the upper-level of the hierarchical error processing structure formed by the combination of Try, OnError and OnSystemError. OnSystemError may be written in the body of any task, but only one instance may exist in the system at any time. It traps both synchronous and asynchronous errors in all tasks, as well as errors that occur within the context of the system.

A system error is not associated with a specific task. An example of a system error is a position following error that occurs due to some external force being applied to an axis not attached to a task. When an error is trapped, the specified error processing code runs and the task is stops. The task is in state 4. It is possible to continue task execution by explicitly entering CONTINUETASK within the error processing code, but the task continues only after the error has been corrected.

OnSystemError traps errors not specifically trapped by Try or by OnError. It then executes either an orderly shutdown of the system, or an orderly recovery procedure.

ErrorPrintLevel

SYSTEM.ERRORPRINTLEVEL controls which types of system errors are printed to the message log window. There are four levels of system errors: fatal faults, errors, and notes.

0 (SILENTLEVEL) – Notes, errors, and fatal faults are not printed.

1 (FAULTLEVEL) – Notes and errors are not printed. Fatal faults are printed.

2 (ERRORLEVEL) – Notes are not printed. Errors and fatal faults are printed.

3 (NOTELEVEL) – Notes, errors, and fatal faults are printed.

SYSTEM.ERRORPRINTLEVEL only affects printing to the message log window. Fatal faults and errors continue to be logged, and can be viewed using ?ERRORHISTORY. ERRORPRINTLEVEL applies only to asynchronous errors. Synchronous errors are not affected.

Terminal Context

Terminal context is similar to task context, as commands are processed similarly. The error action is different from a task as there is no interpreter to be idled when an error occurs.

UEA (User Error Assertion)

The purpose of User Error Assertion (UEA) is to let the application developer extend existing system (internal) errors. You can define application (additional) errors (exceptions) so the system handles them like it would its own. The application exception may be trapped with TRY/Catch, OnError or OnSystemError. Unprocessed application exceptions are treated as any known internal error. The system reacts by stopping the task/motion according to exception severity. The system provides a range for the application errors and prevents an overlap between internal and application error codes. The application is able to define an exception name and ASCII message to print. User exceptions start from number 20001 and you are able to define 1000 exceptions. UEA may have “Note” and “Error” seventies.

Exceptions

Declaration

The application developer can declare an exception and supply the corresponding error message. An exception may be declared on the both system and task levels. Declaration of exceptions at the subroutine level is not supported. User exceptions are divided into two sub ranges 20001-20499 and 20500-20999. Applications developed may use the first sub range for explicit definitions of exception number (see below example), while the second sub range is used by the system for automatic assignment of exception numbers. Double use of the same exception number is forbidden as the System gives an error. The exception can be defined with the following declaration:

Dim|common shared <name> as <severity> <ASCII message> [<num>]

where:

Parameter	Description	Remarks
Severity	Note/Error
Num (optional parameter)	Integer number 20001..20499, which will be assigned to exception. This parameter is optional, if omitted the system will assign some value in range 20500..20999. softMC will report an error if number given by the application developer is already used.
ACII Msg	ASCII text that will appear at error history and error message.

For example:

Dim shared Error1 as Note ”Emergency” 20001
Dim shared Error2 as Note ”Fault” 20002
Common shared MyNote as Note ”My Note”
Common shared MyError as Error ”My Error”

If the exception number is not specified, the system associates exceptions with some numeric value, which can be queried. However, the system will not guarantee that this value is the same from load to load. Do not make any assumption about this number. It is a mechanism to maintain the exception database.

Deletion

All exceptions declared at task level are lost when the task is killed. The exception declared at the system level (Common Shared) can be deleted if not in use – similar to numeric variables. For example:

DeleteVar MyNote

Assertion

The application asserts (throws) an exception from within an application. The system behaves like it is a regular (predefined in firmware) application error. You are able to catch application exception with TRY/Catch, OnError or OnSystemError.

Exception assertion is possible with THROW. THROW accepts the name of any defined exception. Other expressions are not allowed to be arguments to THROW.

The scope of THROW is not limited. It can be executed inside of Try, Catch, Finally, outside the Try block in OnError and OnEvent. For example:

Dim shared LimitError as Error msg= ”Over travel” 
Program
 Attach a1
 Jog a1 100
 While 1
‘check the axis position and assert and error,
‘the system should stop the task and motion
   If a1.pfb > 1e10 Then
     Throw LimitError
   End If
 End while
End program 

Another example:

Dim shared Error1 as Error msg= ”” ‘ no message
Program
 Try 
‘ check Input #1 and do not continue 
‘ if it’s “1”
  If Sys.din.1=1 Then
    Throw Error1
  End if
  Move a1 1e3
 Catch Error1
  Print “I/O error”
 End try
End program 

Log

User exceptions are printed and logged according to existing rules: A note is printed but not logged, Unhandled errors are printed and logge, etc. In addition, the application developer can log an error without any error handling. Application exception is printed and logged but neither task generated such an exception nor motion associated with that task stops.

User exceptions are logged according to the existing rules. Errors and faults are printed and logged while notes are only printed.

You can use LOGGER to lsend exceptions directly to the logger, bypassing any error handler. The exception can be logged with the following command:

Logger <Exception name>

For example:

Logger MyError

Query

You can query exception numbers and messages, but changing these parameters is forbidden. The exception number and text are set during exception definition and stay constant until the exception is deleted or the defined task is killed. For example:

-->?MyError.num
20007
-->?MyError.Msg
My Error

Print

Exceptions are printed and logged with timestamp, task name, and line number, severity and other error attributes. In contrast to internal (predefined) errors, an exception number is not constant and may vary from time to time (from task load to task load). Also, the error log may keep exceptions from tasks not in memory and there is no way to associate an exception number with its message. The error logger keeps exception messages in RAM and files.

Limitations

1. VARLIST and SAVE do not show exceptions.
2. WATCH is not supported.
3. Arrays of exceptions not supported.
4. Definition of exceptiosn in subroutines is not supported.
5. Arithmetical operations are not supported for exceptions. Comparing exceptions makes sense only if the application developer explicitly gives exception numbers. If the softMC assigns exception numbers, the result is unpredictable.
6. The library can assert an exception defined as DIM SHARED or COMMON SHARED. Realize that exceptions defined in the library do not have constant numbers (if numbers were not assigned explicitly).