gsw_mod_error_functions - prototype error handling system

[hylandg]

This simple system constructs an error code of the form 9.nabcxyz000000d15 (based on the idea from v3.03 of returning a large number - 9d15 in Fortran or NaN in Matlab - if an error occurs within a function). Note that because all the Fortran functions are elemental then the error handling system cannot do any i/o or alter global data - hence the need for error information to be encapsulated into a single return value.

n = current error level (1-4) - automatically updated by successive calls to gsw_error_code
     abc = error code for level #1
     xyz = error code for level #2 etc.
and level error codes comprise ...
     a  = error number for level #1 (0-9) - defined within individual functions
     bc = function number for level #1 (0-99) - as listed in module gsw_mod_error_functions

Functions that call gsw_error_code have to be pre-listed in gsw_mod_error_functions - we could gather this info during an initialisation routine but probably overkill at this stage.

Typical usage is as follows ...

use gsw_mod_error_functions, only : gsw_error_code, gsw_error_limit
...
value1 = gsw_some_other_routine(sa, p)
if (value1 .gt. gsw_error_limit) then
    this_routines_return_value = gsw_error_code(2, "this_routines_name", value1)
    return
end if

[hylandg]

Here is a simple example of what this means in terms of the extra information available to users. Firstly the Matlab call to gsw_melting_ice_into_seawater with a set of parameters that should give an invalid result ...

>> [a,b,c] = gsw_melting_ice_into_seawater(6.,10.,0.,0.91,-1.0)

a =
   NaN

b =
   NaN

c =
   NaN

The result is a set of NaNs that is not particularly informative. Secondly, the Fortran equivalent ...

program example

use gsw_mod_kinds
use gsw_mod_toolbox
use gsw_mod_check_data

use gsw_mod_error_functions, only : gsw_error_code, gsw_error_limit
use gsw_mod_error_functions, only : gsw_error_handler, gsw_error_addname

implicit none

real (r8) :: sa_final, ct_final, w_ih_final

character (*), parameter :: func_name = "gsw_error_example"

call gsw_error_addname(func_name)

call gsw_melting_ice_into_seawater(6.0_r8,10.0_r8,0.0_r8,0.91_r8,-1.0_r8, &
                                   sa_final,ct_final,w_ih_final)
if (sa_final .gt. gsw_error_limit) then
    sa_final = gsw_error_code(1,func_name,sa_final)
    call gsw_error_handler(sa_final)
else
    print *, sa_final, ct_final, w_ih_final
end if

return
end

that gives an informative traceback indicating where the error occurred ...

>> ./example

Trace for error code:  9.3507316142000E+15

  Code: 1 in function: gsw_error_example                       
  Code: 3 in function: gsw_melting_ice_into_seawater           
  Code: 5 in function: gsw_frazil_properties

In this case, a quick scan through the gsw_frazil_properties source to see where error code #5 is generated indicates an overflow of w_ih (ie. w_ih > 0.9).