ISIS Documentation

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:

• Program name
• Class of error
• Error code
• Specific message
• Source code file
• Line number in the source code file

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

**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

**I/O Error** Unable to open cube [moon.cub] in IsisCube.cpp at 203

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

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.

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];
  }
}

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_);
}