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-//. For this purpose, functions are needed to:
MPI_ADD_ERROR_CLASS(errorclass)
int MPI_Add_error_class(int *errorclass)
MPI_ADD_ERROR_CLASS(ERRORCLASS, IERROR)INTEGER ERRORCLASS, IERROR
int MPI::Add_error_class()
int
Creates a new error class and returns the value for it.
The value of MPI_ERR_LASTCODE is not affected by new user-defined error codes and classes. As in MPI-/, 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.
MPI_ADD_ERROR_CODE(errorclass, errorcode)
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)
int
Creates new error code associated with errorclass and returns its value in errorcode.
MPI_ADD_ERROR_STRING(errorcode, string)
int MPI_Add_error_string(int errorcode, char *string)
MPI_ADD_ERROR_STRING(ERRORCODE, STRING, IERROR)INTEGER ERRORCODE, IERROR
CHARACTER*(*) STRING
int MPI::Add_error_string(int errorcode, const char* string)
void
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
.
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++).
truein
Section 4.13 on
page describes the methods for creating
and associating error handlers with communicators, files, and windows.
MPI_COMM_CALL_ERRHANDLER (comm, errorcode)
int MPI_Comm_call_errhandler(MPI_Comm comm, int errorcode)
MPI_COMM_CALL_ERRHANDLER(COMM, ERRORCODE, IERROR)INTEGER COMM, ERRORCODE, IERROR
int MPI::Comm::Call_errhandler(int errorcode) const
void
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).
MPI_WIN_CALL_ERRHANDLER (win, errorcode)
int MPI_Win_call_errhandler(MPI_Win win, int errorcode)
MPI_WIN_CALL_ERRHANDLER(WIN, ERRORCODE, IERROR)INTEGER WIN, ERRORCODE, IERROR
int MPI::Win::Call_errhandler(int errorcode) const
void
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).
MPI_FILE_CALL_ERRHANDLER (fh, errorcode)
int MPI_File_call_errhandler(MPI_File fh, int errorcode)
MPI_FILE_CALL_ERRHANDLER(FH, ERRORCODE, IERROR)INTEGER FH, ERRORCODE, IERROR
int MPI::File::Call_errhandler(int errorcode) const
void
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).
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.)
MPI-Standard for MARMOT