Home

User Documentation

Getting Started
Learn More
Explore in Detail
Get Inspired

Contributor Documentation

Getting Started
Learn More
Explore in Detail
Get Inspired

Quick Links

Software Manual
AstroDiscuss
GitHub
API Reference

Documentation Versions


ISIS 2

Documentation
Tutorials
Technical Documents
USGS

ISIS Documentation


Error Handling Facility

Guide to the various aspects of the Error Handling Facility

Home

Introduction

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.

Standard Form

The standard form of an error message is

**CLASS** MESSAGE in FILE at LINE
Two 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

PVL Form

The standard form can be overridden by modifying the Preference file.

Group = ErrorFacility
  Format = Standard | PVL
EndGroup
This 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 203
would 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

Errors and the GUI

[GUI error screen shot]

Screen shot of illustrating a GUI error message.

600x500, 15KB

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.


Errors and the Command Line

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

Program Exit Status

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.

Errors and the Session Log

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.

Tips For Programmers

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.