Users may want to write a layered library on top of an existing MPI implementation, and this library may have its own set of error codes and classes. An example of such a library is an I/O library based on the I/O chapter in MPI-2. For this purpose, functions are needed to:
| MPI_ADD_ERROR_CLASS(errorclass) | |
| OUT errorclass | value for the new error class (integer) | 
 
  int MPI_Add_error_class(int *errorclass) 
  
 
  MPI_ADD_ERROR_CLASS(ERRORCLASS, IERROR)
 INTEGER ERRORCLASS, IERROR 
  
 
  
  int MPI::Add_error_class() 
  
  
Creates a new error class and returns the value for it.
 
 
 
 Rationale.  
 
To avoid conflicts with existing error codes and classes, the value is  
set by the implementation and not by the user.  
 ( End of rationale.) 
 
 
 
 Advice  
        to implementors.  
 
A high quality implementation will return the value for a new  
 errorclass in the same deterministic way on all processes.  
 ( End of advice to implementors.) 
 
 
 
 Advice to users.  
 
Since a call to  MPI_ADD_ERROR_CLASS is local, the same  
 errorclass may not be returned on all processes that make  
this call.  Thus, it is not safe to assume that registering a new  
error on a set of processes at the same time will yield the same  
 errorclass on all of the processes.  However,  if an  
implementation returns the new  errorclass in a deterministic  
way, and they are always generated in the same order  
on the same set of processes (for  
example, all processes), then the value will be the same.  However,  
even if a deterministic algorithm is used, the value can vary across  
processes.  This can happen, for example, if different but overlapping  
groups of processes make a series of calls.  As a result of these issues,  
getting the ``same'' error on multiple processes may not cause the  
same value of error code to be generated.  
 ( End of advice to users.) 
 
The value of  MPI_ERR_LASTCODE is not affected by new user-defined  
error codes and classes.  As in  MPI-1, it is a constant value.  
Instead, a predefined attribute key  MPI_LASTUSEDCODE is  
associated with  
 MPI_COMM_WORLD.  The attribute value corresponding to this key  
  
is the current maximum error class including the user-defined ones.  
  
This is a local value and may be different on different processes.    
  
The value returned by this key is always greater than or equal to  
 MPI_ERR_LASTCODE.  
  
 
 
 
 Advice to users.  
 
The value returned by the key  
 MPI_LASTUSEDCODE will not change unless the user calls a  
function to explicitly add an error class/code.  In a multi-threaded  
environment, the user must take extra care in assuming this value has  
not changed.  
  
Note that error codes and error classes are not necessarily dense.  A user may not assume that each error class below  MPI_LASTUSEDCODE is valid.  
  
 ( End of advice to users.) 
 
| MPI_ADD_ERROR_CODE(errorclass, errorcode) | |
| IN errorclass | error class (integer) | 
| OUT errorcode | new error code to associated with errorclass (integer) | 
 
  int MPI_Add_error_code(int errorclass, int *errorcode) 
  
 
  MPI_ADD_ERROR_CODE(ERRORCLASS, ERRORCODE, IERROR)
 INTEGER ERRORCLASS, ERRORCODE, IERROR 
  
 
  int MPI::Add_error_code(int errorclass) 
  
Creates new error code associated with errorclass and returns its value in errorcode.
 
 
 
 Rationale.  
 
To avoid conflicts with existing error codes and classes, the value  
of the new error code is set by the implementation and not by the  
user.   
 ( End of rationale.) 
 
 
 
 Advice  
        to implementors.  
 
A high quality implementation will return the value for a new  
 errorcode in the same deterministic way on all processes.  
 ( End of advice to implementors.) 
 
| MPI_ADD_ERROR_STRING(errorcode, string) | |
| IN errorcode | error code or class (integer) | 
| IN string | text corresponding to errorcode (string) | 
 
  int MPI_Add_error_string(int errorcode, char *string) 
  
 
  MPI_ADD_ERROR_STRING(ERRORCODE, STRING, IERROR)
 INTEGER ERRORCODE, IERROR 
CHARACTER*(*) STRING 
  
 
  
  void MPI::Add_error_string(int errorcode, const char* string) 
  
  
Associates an error string with an error code or class. The string must be no more than MPI_MAX_ERROR_STRING characters long. The length of the string is as defined in the calling language. The length of the string does not include the null terminator in C or C++. Trailing blanks will be stripped in Fortran. Calling MPI_ADD_ERROR_STRING for an errorcode that already has a string will replace the old string with the new string. It is erroneous to call MPI_ADD_ERROR_STRING for an error code or class with a value leq constiMPI_ERR_LASTCODE.
If MPI_ERROR_STRING is called when no string has been set, it will return a empty string (all spaces in Fortran, "" in C and C++).
Section Error Handlers describes the methods for creating and associating error handlers with communicators, files, and windows.
| MPI_COMM_CALL_ERRHANDLER (comm, errorcode) | |
| IN comm | communicator with error handler (handle) | 
| IN errorcode | error code (integer) | 
 
  int MPI_Comm_call_errhandler(MPI_Comm comm, int errorcode) 
  
 
  MPI_COMM_CALL_ERRHANDLER(COMM, ERRORCODE, IERROR)
 INTEGER COMM, ERRORCODE, IERROR 
  
 
  void MPI::Comm::Call_errhandler(int errorcode) const 
  
  
This function invokes the error handler assigned to the communicator with the error code supplied. This function returns MPI_SUCCESS in C and C++ and the same value in IERROR if the error handler was successfully called (assuming the process is not aborted and the error handler returns).
 
 
 
 Advice to users.  
 
Users should note that the default error handler is  
 MPI_ERRORS_ARE_FATAL.  Thus, calling  
 MPI_COMM_CALL_ERRHANDLER will abort the  comm  
processes if the default error handler has not been changed for this  
communicator or on the parent before the communicator was created.  
 ( End of advice to users.) 
 
| MPI_WIN_CALL_ERRHANDLER (win, errorcode) | |
| IN win | window with error handler (handle) | 
| IN errorcode | error code (integer) | 
 
  
  int MPI_Win_call_errhandler(MPI_Win win, int errorcode) 
  
 
  MPI_WIN_CALL_ERRHANDLER(WIN, ERRORCODE, IERROR)
 INTEGER WIN, ERRORCODE, IERROR 
  
 
  void MPI::Win::Call_errhandler(int errorcode) const 
  
This function invokes the error handler assigned to the window with the error code supplied. This function returns MPI_SUCCESS in C and C++ and the same value in IERROR if the error handler was successfully called (assuming the process is not aborted and the error handler returns).
 
 
 
 Advice to users.  
 
As with communicators, the default error handler for windows is  
 MPI_ERRORS_ARE_FATAL.  
 ( End of advice to users.) 
 
  
| MPI_FILE_CALL_ERRHANDLER (fh, errorcode) | |
| IN fh | file with error handler (handle) | 
| IN errorcode | error code (integer) | 
 
  int MPI_File_call_errhandler(MPI_File fh, int errorcode) 
  
 
  MPI_FILE_CALL_ERRHANDLER(FH, ERRORCODE, IERROR)
 INTEGER FH, ERRORCODE, IERROR 
  
 
  void MPI::File::Call_errhandler(int errorcode) const 
  
  
This function invokes the error handler assigned to the file with the error code supplied. This function returns MPI_SUCCESS in C and C++ and the same value in IERROR if the error handler was successfully called (assuming the process is not aborted and the error handler returns).
 
 
 
 Advice to users.  
 
  
Unlike errors on communicators and windows, the default behavior for files is to  
  
have  MPI_ERRORS_RETURN  
 ( End of advice to users.) 
 
  
 
 
 
 Advice to users.  
Users are warned that handlers should not be called recursively with MPI_COMM_CALL_ERRHANDLER, MPI_FILE_CALL_ERRHANDLER, or MPI_WIN_CALL_ERRHANDLER. Doing this can create a situation where an infinite recursion is created. This can occur if MPI_COMM_CALL_ERRHANDLER, MPI_FILE_CALL_ERRHANDLER, or MPI_WIN_CALL_ERRHANDLER is called inside an error handler.
 
Error codes and classes are associated with a process.  As a result,  
they may be used in any error handler.  Error handlers should be  
prepared to deal with any error code it is given.  Furthermore, it is  
good practice to only call an error handler with the appropriate  
error codes.  For example, file errors would normally be sent to the  
file error handler.  
 ( End of advice to users.)