# 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
`PetscCallVoid()` in this case.


## Example Usage
```none
  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
```none
  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 from which this is used must declare a variable PetscErrorCode 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
```none
  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()`

## Level
beginner

## Location
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/include/petscerror.h.html#PetscCall">include/petscerror.h</A>

## Examples
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/sys/classes/viewer/tutorials/ex1.c.html">src/sys/classes/viewer/tutorials/ex1.c.html</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/sys/classes/viewer/tutorials/ex2.c.html">src/sys/classes/viewer/tutorials/ex2.c.html</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/sys/classes/random/tutorials/ex1.c.html">src/sys/classes/random/tutorials/ex1.c.html</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/sys/classes/random/tutorials/ex2.c.html">src/sys/classes/random/tutorials/ex2.c.html</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/sys/tutorials/ex1.c.html">src/sys/tutorials/ex1.c.html</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/sys/tutorials/ex16.c.html">src/sys/tutorials/ex16.c.html</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/sys/tutorials/ex17.c.html">src/sys/tutorials/ex17.c.html</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/sys/tutorials/ex19.c.html">src/sys/tutorials/ex19.c.html</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/sys/tutorials/ex2.c.html">src/sys/tutorials/ex2.c.html</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/sys/tutorials/ex20.c.html">src/sys/tutorials/ex20.c.html</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/sys/tutorials/ex3.c.html">src/sys/tutorials/ex3.c.html</A><BR>


---
[Edit on GitLab](https://gitlab.com/petsc/petsc/-/edit/release/include/petscerror.h)


[Index of all Sys routines](index.md)  
[Table of Contents for all manual pages](/docs/manualpages/index.md)  
[Index of all manual pages](/docs/manualpages/singleindex.md)  
