PetscCall — PETSc 3.21.4 documentation

Skip to main content
`Ctrl`+`K`

# PetscCall

Calls a PETSc function and then checks the resulting error code, if it is non-zero it calls the error handler and returns from the current function with the error code.

## Synopsis

    #include <petscerror.h>
    void PetscCall(PetscFunction(args))

Not Collective

## Input Parameter

- PetscFunction - any PETSc function that returns an error code

## Notes

Once the error handler is called the calling function is then returned from with the given error code. Experienced users can set the error handler with `PetscPushErrorHandler()`.

`PetscCall()` cannot be used in functions returning a datatype not convertible to `PetscErrorCode`. For example, `PetscCall()` may not be used in functions returning `void`, use `PetscCallAbort()` or `PetscCallVoid()` in this case.

## Example Usage

      PetscCall(PetscInitiailize(...)); // OK to call even when PETSc is not yet initialized!

      struct my_struct
      {
        void *data;
      } my_complex_type;

      struct my_struct bar(void)
      {
        PetscCall(foo(15)); // ERROR PetscErrorCode not convertible to struct my_struct!
      }

      PetscCall(bar()) // ERROR input not convertible to PetscErrorCode

It is also possible to call this directly on a `PetscErrorCode` variable

      PetscCall(ierr);  // check if ierr is nonzero

Should not be used to call callback functions provided by users, `PetscCallBack()` should be used in that situation.

`PetscUseTypeMethod()` or `PetscTryTypeMethod()` should be used when calling functions pointers contained in a PETSc object’s `ops` array

## Fortran Notes

The Fortran function in which this is used must declare a `PetscErrorCode` variable necessarily named `ierr`, and `ierr` must be the final argument to the PETSc function being called.

In the main program and in Fortran subroutines that do not have `ierr` as the final return parameter, one should use `PetscCallA()`

## Example Fortran Usage

      PetscErrorCode ierr
      Vec v

      ...
      PetscCall(VecShift(v, 1.0, ierr))
      PetscCallA(VecShift(v, 1.0, ierr))

## See Also

`SETERRQ()`, `PetscCheck()`, `PetscAssert()`, `PetscTraceBackErrorHandler()`, `PetscCallMPI()`, `PetscPushErrorHandler()`, `PetscError()`, `CHKMEMQ`, `CHKERRA()`, `CHKERRMPI()`, `PetscCallBack()`, `PetscCallAbort()`, `PetscCallVoid()`

## Level

beginner

## Location

include/petscerror.h

Index of all Sys routines
Table of Contents for all manual pages
Index of all manual pages