Error Codes

next up previous contents
Next: Interaction with Executing Up: Error Handling Previous: Error Handlers

Error Codes

error codes

Most MPI functions return an error code indicating successful execution (MPI_SUCCESS), or providing information on the type MPI_SUCCESS of MPI exception that occurred. In certain circumstances, when the MPI function may complete several distinct operations, and therefore may generate several independent errors, the MPI function may return multiple error codes. This may occur with some of the calls described in Section gif that complete multiple nonblocking communications. As described in that section, the call may return the code MPI_ERR_IN_STATUS, in which case a detailed error code is returned MPI_ERR_IN_STATUS with the status of each communication.

The error codes returned by MPI are left entirely to the implementation (with the exception of MPI_SUCCESS, MPI_ERR_IN_STATUS and MPI_ERR_PENDING). MPI_SUCCESS MPI_ERR_IN_STATUS MPI_ERR_PENDING This is done to allow an implementation to provide as much information as possible in the error code. Error codes can be translated into meaningful messages using the function below.

MPI_ERROR_STRING(errorcode, string, resultlen)

  IN     errorcode      Error code returned by an MPI
  OUT    string         Text that corresponds to the errorcode
  OUT    resultlen      Length (in printable character) of the
                        result returned in string.

MPI_Error_string(int errorcode, char *string, int *resultlen)


Returns the error string associated with an error code or class. The argument string must represent storage that is at least MPI_MAX_ERROR_STRING characters long. MPI_MAX_ERROR_STRING

The number of characters actually written is returned in the output argument, resultlen.

The use of implementation-dependent error codes allows implementers to provide more information, but prevents one from writing portable error-handling code. To solve this problem, MPI provides a standard set of specified error values, called error classes, and a function that maps each error code into a suitable error class. error classes

Valid error classes are

MPI_SUCCESS         No error   
MPI_ERR_BUFFER      Invalid buffer pointer
MPI_ERR_COUNT       Invalid count argument
MPI_ERR_TYPE        Invalid datatype argument
MPI_ERR_TAG         Invalid tag argument
MPI_ERR_COMM        Invalid communicator
MPI_ERR_RANK        Invalid rank 
MPI_ERR_REQUEST     Invalid request 
MPI_ERR_ROOT        Invalid root 
MPI_ERR_GROUP       Invalid group 
MPI_ERR_OP          Invalid operation 
MPI_ERR_TOPOLOGY    Invalid topology 
MPI_ERR_DIMS        Invalid dimensions argument 
MPI_ERR_ARG         Invalid argument of some other kind 
MPI_ERR_UNKNOWN     Unknown error 
MPI_ERR_TRUNCATE    Message truncated on receive
MPI_ERR_OTHER       Known error not in this list   
MPI_ERR_INTERN      Internal MPI error   
MPI_ERR_IN_STATUS   Error code is in status	 
MPI_ERR_PENDING     Pending request	
MPI_ERR_LASTCODE    Last error code
Most of these classes are self explanatory. The use of MPI_ERR_IN_STATUS and MPI_ERR_PENDING is explained in Section gif. The list of standard classes may be extended in the future.

The function MPI_ERROR_STRING can be used to compute the error string associated with an error class.

The error codes satisfy,

MPI_Error_class(int errorcode, int *errorclass)


The function MPI_ERROR_CLASS maps each error code into a standard error code (error class). It maps each standard error code onto itself.

next up previous contents
Next: Interaction with Executing Up: Error Handling Previous: Error Handlers

Jack Dongarra
Fri Sep 1 06:16:55 EDT 1995