Error functions — CALCEPH - Fortran 2003 language 3.4.1 documentation

# Error functions

The following group of functions defines the behavior of the library when errors occur during the execution.

## Usage

The following examples, that can be found in the directory examples of the library sources, show the typical usage of this group of functions.

The example in Fortran 2003 language is `f2003error.f`.

The following example shows how to stop the execution on the error.

    program f2003error
        USE, INTRINSIC :: ISO_C_BINDING
        use calceph
        implicit none
        integer res
        real(8) jd0
        real(8) dt
        real(8) PV(6)

     ! set the  error handler to stop on error
         call calceph_seterrorhandler(2, C_NULL_FUNPTR)

     ! open the ephemeris file
        res = calceph_sopen("example1.dat"//C_NULL_CHAR)
        ...

    stop
    end

The following example shows how to define a custom error handler function.

    !/*-----------------------------------------------------------------*/
    !/* custom error handler */
    !/*-----------------------------------------------------------------*/
         subroutine myhandler(msg, msglen) BIND(C)
            USE, INTRINSIC :: ISO_C_BINDING
            implicit none
            character(kind=C_CHAR), dimension(msglen), intent(in) :: msg
            integer(C_INT), VALUE, intent(in) :: msglen
            write (*,*) "The calceph calls the function myhandler"
            write (*,*) "The message contains ",msglen," characters"
            write(*,*) "The error message is :"
            write(*,*) "----------------------"
            write(*,*) msg
            write(*,*) "----------------------"
            write(*,*) "The error handler returns"
         end

    !/*-----------------------------------------------------------------*/
    !/* main program */
    !/*-----------------------------------------------------------------*/
         program f2003error
             USE, INTRINSIC :: ISO_C_BINDING
             use calceph
             implicit none
             integer res
             real(8) jd0
             real(8) dt
             real(8) PV(6)

             interface
              subroutine myhandler(msg, msglen) BIND(C)
                  USE, INTRINSIC :: ISO_C_BINDING
                  implicit none
                  character(kind=C_CHAR), dimension(msglen), intent(in) &
        &          :: msg
                  integer(C_INT), VALUE, intent(in) :: msglen
              end subroutine
             end interface

    ! set the  error handler to use my own callback
             call calceph_seterrorhandler(3, c_funloc(myhandler))

    ! open the ephemeris file
            res = calceph_sopen("example1.dat"//C_NULL_CHAR)

       ! ...

         stop
         end

## calceph_seterrorhandler

subroutine `calceph_seterrorhandler`(typehandler, userfunc ) BIND(C)

  Parameters: | typehandler [TYPE(C_INT), VALUE, intent(in)] :: type of handler userfunc [TYPE(C_FUNPTR), VALUE, intent(in)] :: user function

This function defines the behavior of the library when an error occurs during the execution of the library's functions. This function should be (not mandatory) called before any other functions of the library. The behavior depends on the value of typehandler.

The possible values for typehandler are :

value | meaning
--- | ---
1 | The library displays a message and continues the execution. The functions return an error code. The python and Octave/Matlab interfaces raise an exception. This is the default behavior of the library.
2 | The library displays a message and terminates the execution with a system call to thefunction exit.
3 | The library calls the user function userfunc with the message.

If the function is called with 1 or 2 for typehandler, the parameter userfunc must be set to C_NULL_FUNPTR.

The function userfunc must be defined as

    subroutine userfunc (msg, msglen)  BIND(C)
    USE, INTRINSIC :: ISO_C_BINDING
    implicit none
    CHARACTER(kind=C_CHAR), dimension(msglen), intent(in) :: msg
    INTEGER(C_INT), VALUE, intent(in) :: msglen

This function must have an explicit interface.