Error Handling

 

When an error occurs during the execution of a GISDK macro, Caliper Script normally displays a message with reference information and aborts execution of the GISDK macro in which it occurs and any calling GISDK macro. The reference information has three parts:

• the name of the resource file in which the error occurred

• the line number at which the error occurred

• an error code, as shown in the table below

The message gives you the opportunity to launch the GISDK Debugger, if appropriate. Execution of the resource file is set back to just before the error occurred. For more information, see Using the GISDK Debugger.

 

Caliper Script provides four statements for customized error and exception handling, with these formats:

 

on exceptions goto label

on exceptions default

on exceptions do

     <statements go here>

     goto label

     end

on exceptions do

     <statements go here>

     Return()

     end

 

Once error handling is enabled for an exception type, the error handler remains in place throughout the GISDK macro or dialog box item, until it is replaced by another error handler, or canceled by the "on exceptions default" statement.

 

As of Version 2018, if a macro has no error handler, but a calling macro does, then that error handler will capture the error.

 

Here is an example:

 

on notfound do

     ShowMessage("There is no States layer in this map!")

     goto no_states

     end

SetLayer("States")       // If this fails, the error handler runs

SetBorderColor(, clr1)   // A notfound here will use the same error handler!

SetFillColor(, clr2)     // Same here

no_states:

on notfound default      // Cancels the special error handling

 

Normally each handler will be for one exception:

 

on error do

Return()

end

 

on notfound do

Return()

end

 

If you have two handlers that do the same thing, such as these examples, you can have one handler for a list of exceptions:

 

on error, notfound do

Return()

end

 

The exception types are:

 

Exception Type	Code	Meaning
Error	0	An error not described by one of the other exception types has occurred
NotFound	1	The object of a Caliper Script statement or function is not found (e.g., a nonexistent layer or data field is referenced)
Escape	2	The end user presses the Escape key or clicks both mouse buttons during an input operation
NonUnique	3	Multiple identical values are encountered where a single value is expected
Missing	4	A missing value is encountered in a data field
DivideByZero	5	A division by zero is encountered
EndOfFile	6	The end of an input file is encountered
Locked	7	A time-out is experienced because a required file is locked
LanguageError	8	There is an error in a Caliper Script statement, such as the wrong types passed to a function or used with an operator