.. _exception-handling:

 .. f:currentmodule:: fmsg_m

******************
Exception Handling
******************

This chapter discusses how MSG handles exceptions. These can arise in a variety of circumstances:

* Attempts to load grids from files that are missing or corrupt.
* Attempts to interpolate at locations outside the bounds of a grid.
* Attempts to interpolate at locations where grid data are missing (so-called :ref:`grid voids <grid-voids>`).
* Attempts to interpolate with incomplete specification of photospheric parameters.
* Attempts to interpolate for invalid wavelength and/or angle parameters.

When an exception occurs, how it's signaled depends on the language interface being used.

Python
======
  
Using the Python interface, exceptions are signaled using the
language's built-in exception handling capabilities. The list of
exceptions that can be thrown by each function is provided in the
:ref:`python-interface` chapter.

Fortran
=======

Using the Fortran interface, exceptions are signaled through the
optional procedure argument :code:`stat`. If this argument is
present, then on return it is set to one of the status code values
defined in the :ref:`Fortran parameters <fortran-params>` section. The
value :f:var:`STAT_OK` indicates that no problem was encountered;
other values signal an exception. If :code:`stat` is not present when
an exception occurs, then execution halts with an error message
printed to standard output.

C
=

Using the C interface, exceptions are signaled through the pointer
function argument :code:`stat`. If this pointer is non-null, then on
return the pointer target :code:`*stat` is set to one of the status code values
defined in the :ref:`C enums <c-enums>` section. The value
:c:enumerator:`STAT_OK` indicates that no problem was encountered; other
values signal an exception. If :code:`stat` is null when an exception
occurs, then execution halts with an error message printed to standard
output.
