What is MPI_Add_error_string?

MPI_Add_error_string

Some users may want to create additional libraries on top of an existing MPI implementation, and these libraries may have their own sets of error codes and classes. MPI offers the MPI_Add_error_string function to associate an error string with an error code or class. The string must not exceed MPI_MAX_ERR_STRING characters.

Syntax

int MPI_Add_error_string( int errorcode, const char* string)

Parameters

errorcode is the error code or class with which the string will be associated.
string is the text corresponding to the error code.

Return value

If unsuccessful, the function returns an error. The error aborts the MPI job by default.

In case of success, MPI_Add_error_string returns MPI_SUCCESS, the value returned upon successful termination of any MPI routine.

Example

The example below shows how we can use the MPI_Add_error_string function to associate text with a custom-made error class:

#include "mpi.h"
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
/* Create NCLASSES new classes, each with 4 codes (120 total) */
#define NCLASSES 30
#define NCODES 4
int main( int argc, char *argv[] )
{
  int newclass[NCLASSES], newcode[NCLASSES][NCODES];
  char string[MPI_MAX_ERROR_STRING];
  int i, j;
  MPI_Init( &argc, &argv );
  /* Initialize the new codes */
  for (i=0; i<NCLASSES; i++) {
      MPI_Add_error_class( &newclass[i] );
      for (j=0; j<NCODES; j++) {
          MPI_Add_error_code( newclass[i], &newcode[i][j] );
          sprintf( string, "code for class %d errorcode %d\n", i, j );
          MPI_Add_error_string( newcode[i][j], string );
      }
  }
}

We define the macros NCLASSES and NCODES to define the number of classes and the error codes within each class (lines 7-8).
We then initialize the newcode and newclass arrays to represent the error classes and their codes (line 12).
In the for loop, we use the MPI_Add_error_class method to create a new error class, and within the loop, we also assign each class with its error codes using the MPI_Add_error_code method (line 19, 21).
Finally, we associate a string with the error codes in each class using the MPI_Add_error_string method (line 23).

Free Resources