ISIS Documentation
Error Handling FacilityGuide to the various aspects of the Error Handling Facility | Home |
Errors will occur when running ISIS applications. For example, the user may have entered invalid parameters or I/O to a file may have failed due to insufficient disk space. This document discusses the various aspects of the ISIS Error Handling Facility.
When an error occurs several elements can be reported. They include:
How these elements are presented and where they are written is user selectable as described in the ISIS Preference Dictionary.
The standard form of an error message is
**CLASS** MESSAGE in FILE at LINETwo examples are given below,
**USER ERROR** Parameter [TO] must be entered in IsisAml.cpp at 1613 **I/O ERROR** Unable to open cube [moon.cub] in IsisCube.cpp at 203
The CLASS
is a general identifier that can help the user narrow down the scope of the problem. Other
CLASSES
include
SYSTEM ERROR
,
PROJECTION ERROR
, and
CAMERA ERROR
.
Because there are a variety of error
CLASSES
we have developed the
ISIS Error Dictionary. This dictionary gives
users additional context regarding the error, which may direct them to a solution.
The MESSAGE
gives more specific information regarding the error. It is standard practice to place the offending
problem in square brackets. This will help the user narrow the scope of the problem even further.
The FILE
at
LINE
is an element
of the message more useful for programmers. This allows the programmer to track down problems more easily.
Some users may desire to turn this feature off and can do so by modifying their personal
ISIS Preference file.
Group = ErrorFacility FileLine = On | Off EndGroup
The standard form can be overridden by modifying the Preference file.
Group = ErrorFacility Format = Standard | PVL EndGroupThis forces the output of errors messages to be in Parameter Value Language format. Our previous standard form example,
**I/O Error** Unable to open cube [moon.cub] in IsisCube.cpp at 203would be presented in the following format,
Group = Error Program = highpass Class = "I/O ERROR" Code = -3 Message = "Unable to open cube [moon.cub]" Source = IsisCube.cpp Line = 203 EndGroup
Screen shot of illustrating a GUI error message. |
When an error occurs in the GUI it is written to the error dialog box. Because the GUI is interactive, the user has a chance to correct the problem and continue program execution.
[Future Option] Any of the message text appearing inside of brackets will be show in red, further highlighting the offending problem.
When an error occurs under the command line or batch-processing mode. The error report is written to the
STDERR
stream.
Unlike the GUI, the program immediately terminates with a status code.
Output to "standard error" allows redirection of erros to files using standard Unix commands. For example,
highpass from=bad.cub >& error.txt
Under the command line, programs that run successfully will exit with a zero status. If an error is generated
then the program will exit with a non-zero status. The status has a 1-to-1 correlation with the
CLASS
of
error (e.g., User,
I/O ERROR
).
To find out the various CLASS
versus CODE
relationships you should examine
the ISIS Error Dictionary.
Under the GUI, the program always exits successfully as the user has the opportunity to correct errors.
When an error occurs it will be written in the standard or PVL form to the Session Log. That is, it may be written to the log file and/or the terminal screen depending upon the log settings in the user preference file.
Dealing with errors in ISIS is generally quite simple. Application programs will automatically trap errors using C++ expections. For example, the following program has no required error checking. It will automatically report invalid user input or I/O errors such as opening or allocating cubes.
using namespace std;
#include "Isis.h"
#include "IsisProcessByLine.h"
#include "IsisSpecialPixel.h"
void mirror (IsisBuffer &in, IsisBuffer &out);
void IsisMain() {
// We will be processing by line
IsisProcessByLine p;
// Setup the input and output cubes
p.SetInputCube("FROM");
p.SetOutputCube ("TO");
// Start the processing
p.StartProcess(mirror);
p.EndProcess();
}
// Line processing routine
void mirror (IsisBuffer &in, IsisBuffer &out) {
// Loop and flip pixels in the line.
int index = in.size() - 1;
for (int i=0; i<in.size(); i++) {
out[i] = in[index - i];
}
}
On occasions the programmer may be required report an error. This can be facilitated in the following manner:
IsisCubePacket *from = p.SetInputCube("FROM");
if (from->Lines() / 2 == 0) {
string msg = "Input cube [" + from->Filename() +
"must have an odd number of lines" ;
throw IsisErrorUser (msg,_FILEINFO_);
}
See the ISIS Developers Reference.