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.

WatchDog

The softMC provides a WatchDog timer to help determine if the host PC connection is operational. To use the WatchDog, configure the softMC to expect WatchDog messages. During normal operation, the host PC must reset the WatchDog timer before the end of the specified interval to avoid a WatchDog fault.

Normally, the WatchDog is cycled indirectly through fast I/O. WDCYCLE directly resets the WatchDog, but this is not recommended because it requires 15 to 20 ms per WatchDog cycle. Given that WatchDog timers are often reset every 100 ms, this implies that the WatchDog function could consume 15 to 20% of the softMC processor time. Events triggered by the fast I/O can avoid this problem. The following commands configure the softMC to expect WatchDog cycles:

WDINIT establishes a WatchDog timer. When selecting the reset time, it should be long enough that the WatchDog function does not consume undue amounts of processing time. The time also should be short enough so that if the communication link between softMC and host is lost, the softMC can shut the axes down in a timely manner. Different applications require different times, but 100 to 1000 ms (<Cycles> = 5 to 50) are commonly used.

WDCYCLE cycles the WatchDog timer.

WDDELETE deletes the WatchDog timer. WDDELETE is seldom used in normal operation because once a WatchDog timer is started, it is seldom stopped intentionally.

WatchDog Setup

To set up the softMC to enable the WatchDog, follow these steps:

1. Create a new task solely for the WatchDog. Use ControlStudio with File, New.
2. Define a local variable as a Long. For the example below, we use MyVar.
3. Initialize the WatchDog timer in the main program. Store the return value of the initialization step in the local variable from Step 1.
4. Write an event inside the task to reset the WatchDog timer. The event is fired with fast I/O (SYSTEM.VIN.1 to 32).
5. Set the task to run infrequently so it does not consume more computational resources than necessary. The following example demonstrates a

WatchDog timer task:

Dim Shared MyVar as Long
Program
‘Event which runs once for each WatchDog cycle
OnEvent WDevent System.Vin.1 = 1 ScanTime = 4 ‘Check every 4th cycle
 WDCycle(MyVar)‘Cycle the WatchDog
 System.Vin.1 = 0 ‘Reset the WatchDog bit
End OnEvent
 EventOn WDEvent ‘Enable the Wdog Event
 MyVar = WDInit(5) ‘Set Wdog time for 5 Wdog cycles or 100 ms
 WDCycle(MyVar) ‘You must cycle the Wdog once to begin
 While 1 = 1 ‘Infinitely loop so event will be active
   Sleep 1e6 ‘Use sleep to conserve CPU time
 End While
End Program

With this example, the WatchDog must be reset every fifth cycle (every 100 ms) to avoid a fault.

Cycle the WatchDog

The last step in using the softMC WatchDog is to issue watch cycle commands from the host PC. These are issued more frequently than the specified maximum cycle time in WDINIT. For example, if the maximum cycles are specified as 5 (equivalent to 100 ms), reset the WatchDog every 50 or 60 ms. In Visual Basic, this is as simple as setting the fast I/O to 1 based on a 50 ms timer.

Reset the WatchDog

You can reset the WatchDog directly from the host PC using WDCYCLE This is simpler than the method presented above because you need not generate a task. However, this is not normally recommended because it is much slower than the fast-I/O method as it requires 15 to 20 ms to precompile commands issued directly from the API to the softMC. However, should you decide to use the direct method, you need only use the following steps directly from the API:

1. Create a global variable.
2. Initialize the WatchDog timer.
3. Reset the WatchDog with an API command based on a timer. Run the following Visual Basic code once upon initialization:

Include KMAPI.BAS in your project
KMExecuteCmd(MC, “MyVar=WDInit(5)”)
KMExecuteCmd(MC, “WDCycle(MyVar)”)

4. Run the following Visual Basic code from a timer set for 50 ms:

KMEXecuteEmd(MC, “WDCycle(MyVar)”)

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).