Error management

Errors can be handled by checking the return value of every function:

c     Example error handling
      ierr = idba_presentati(dbhandle, "dsn", "user", "password")
      if (ierr.ne.0) then
c       handle the error...
      end if

Or they can be handled by installing a callback function that is automatically called in case of error:

c     How to set a callback
c       * the first parameter is the error code that triggers the callback (0
c         means 'trigger on all errors')
c       * the second parameter is the routine to call when the error happens        
c         (remember to declare the function as 'external'
c       * the third parameter is a convenience arbitrary integer that will be
c         passed to the function
c       * the fourth parameter is used to return a handle that can be used to
c         remove the callback
      call idba_error_set_callback(0, error_handler, 42, cb_handle)

The previous code will setup DB-ALLe to call error_handler after any error, passing it the integer value 42. The callback can be removed at any time by calling idba_error_remove_callback:

c     How to remove a callback
      call idba_error_remove_callback(cb_handle)

This is a useful error handling function:

c     The error handler needs to be declared 'external'
      external error_handler

c     Compute the length of a string
c     (this is an utility function that is used by the error handler
c      to print nicer error messages)
      integer function istrlen(string)
      character string*(*)
        istrlen = len(string)
        do while ((string(istrlen:istrlen).eq." " .or.
     $       string(istrlen:istrlen).eq."").and.
     $       istrlen.gt.0)
           istrlen = istrlen - 1
        enddo
        return
      end

c     Generic error handler: print all available information
c     about the error, then exit
      subroutine error_handler(val)
      integer val
      character buf*1000
        print *,ier," testcb in ",val
        call idba_error_message(buf)
        print *,buf(:istrlen(buf))
        call idba_error_context(buf)
        print *,buf(:istrlen(buf))
        call idba_error_details(buf)
        print *,buf(:istrlen(buf))
        call exit (1)
        return
      end

This code introduces three new functions:

idba_error_message

returns a string describing what type of error has happened.

idba_error_context

returns a string describing what DB-ALLe was trying to do when the error happened.

idba_error_details

returns a detailed description of the error, when available. If no detailed description is available, it returns an empty string.

A similar error handling behaviour can be obtained by using the predefined convenience function idba_default_error_handler:

c     Declare the external function (not necessary if you include dballef.h)
      external idba_default_error_handler

c     Use it as the error handling callback
      call idba_error_set_callback(0, idba_default_error_handler, 1, cb_handle)

An alternative error handler called idba_error_handler_tolerating_overflows is available: it exists on all errors instead of value overflows, in what case it prints a warning to standard error and allows the program to continue. The overflow error can then be catched, if needed, by inspecting the error code returned by the DB-ALLe function that causes the error.

This is how to use it:

c     Declare the external function (not necessary if you include dballef.h)
      external idba_error_handler_tolerating_overflows

c     Use it as the error handling callback
      call idba_error_set_callback(0, idba_error_handler_tolerating_overflows, 1, cb_handle)