[next] [prev] [prev-tail] [tail] [up]

### 8 Error handling

The PSBLAS library error handling policy has been defined at the time version 2.0 was written. The idea behind the design of error handling strategy is to keep error messages on a stack allowing the user to trace back up to the point where the first error message has been generated. Every routine in the PSBLAS library has, as last non-optional argument, an integer info variable; whenever, inside the routine, an error is detected, this variable is set to a value corresponding to a specific error code. Then this error code is also pushed on the error stack and then either control is returned to the caller routine or the execution is aborted, depending on the users choice. At the time when the execution is aborted, an error message is printed on standard output with a level of verbosity than can be chosen by the user. If the execution is not aborted, then, the caller routine checks the value returned in the info variable and, if not zero, an error condition is raised. This process continues on all the levels of nested calls until the level where the user decides to abort the program execution.

Figure 5 shows the layout of a generic psb_foo routine with respect to the PSBLAS error handling policy. It is possible to see how, whenever an error condition is detected, the info variable is set to the corresponding error code which is, then, pushed on top of the stack by means of the psb_errpush. An error condition may be directly detected inside a routine or indirectly checking the error code returned returned by a called routine. Whenever an error is encountered, after it has been pushed on stack, the program execution skips to a point where the error condition is handled; the error condition is handled either by returning control to the caller routine or by calling the psb\_error routine which prints the content of the error stack and aborts the program execution, according to the choice made by the user with psb_set_erraction. The default is to print the error and terminate the program, but the user may choose to handle the error explicitly.

    subroutine psb_foo(some args, info)
       ...
       if(error detected) then
         info=errcode1
         call psb_errpush(’psb_foo’, errcode1)
         goto 9999
       end if
       ...
       call psb_bar(some args, info)
       if(info .ne. zero) then
         info=errcode2
         call psb_errpush(’psb_foo’, errcode2)
         goto 9999
       end if
       ...
    9999 continue
       if (err_act .eq. act_abort) then
        call psb_error(icontxt)
        return
       else
        return
       end if

    end subroutine psb_foo

Listing 5: The layout of a generic psb_foo routine with respect to PSBLAS-2.0 error handling policy.

Figure 6 reports a sample error message generated by the PSBLAS library. This error has been generated by the fact that the user has chosen the invalid “FOO” storage format to represent the sparse matrix. From this error message it is possible to see that the error has been detected inside the psb_cest subroutine called by psb_spasb ... by process 0 (i.e. the root process).

    ==========================================================
    Process: 0.  PSBLAS Error (4010) in subroutine: df_sample
    Error from call to subroutine mat dist
    ==========================================================
    Process: 0.  PSBLAS Error (4010) in subroutine: mat_distv
    Error from call to subroutine psb_spasb
    ==========================================================
    Process: 0.  PSBLAS Error (4010) in subroutine: psb_spasb
    Error from call to subroutine psb_cest
    ==========================================================
    Process: 0.  PSBLAS Error (136) in subroutine: psb_cest
    Format FOO is unknown
    ==========================================================
    Aborting...

Listing 6: A sample PSBLAS error message. Process 0 detected an error condition inside the psb_cest subroutine

#### 8.1 psb_errpush — Pushes an error code onto the error stack

    call psb_errpush(err_c, r_name, i_err, a_err)

Type:

  Asynchronous.

On Entry

err_c

  the error code
  Scope: local
  Type: required
  Intent: in.
  Specified as: an integer.

r_name

  the soutine where the error has been caught.
  Scope: local
  Type: required
  Intent: in.
  Specified as: a string.

i_err

  addional info for error code
  Scope: local
  Type: optional
  Specified as: an integer array

a_err

  addional info for error code
  Scope: local
  Type: optional
  Specified as: a string.

#### 8.2 psb_error — Prints the error stack content and aborts execution

    call psb_error(icontxt)

Type:

  Asynchronous.

On Entry

icontxt

  the communication context.
  Scope: global
  Type: optional
  Intent: in.
  Specified as: an integer.

#### 8.3 psb_set_errverbosity — Sets the verbosity of error messages

    call psb_set_errverbosity(v)

Type:

  Asynchronous.

On Entry

v

  the verbosity level
  Scope: global
  Type: required
  Intent: in.
  Specified as: an integer.

#### 8.4 psb_set_erraction — Set the type of action to be taken upon error condition

    call psb_set_erraction(err_act)

Type:

  Asynchronous.

On Entry

err_act

  the type of action.
  Scope: global
  Type: required
  Intent: in.
  Specified as: an integer. Possible values: psb_act_ret, psb_act_abort.

[next] [prev] [prev-tail] [front] [up]