TITLE: Error String v5

* Version 5 passed a formal 6/0/0 vote at the September 2000 meeting 
with minor corrections to the bindings and the addition of the final 
paragraph.

* Version 4 corrects the descriptive text for the function which I
neglected to update for version v3.

* Attendees at the June 2000 meeting preferred that a simple pointer to
a null-terminated string (allocated by the library) be returned.  With
that modification, version v3 was supported by a straw vote of 8/1/0.

* The only change for version 2 is to add the C++ binding.

* Version 1 was born as I was updating the Error Proposal.  After 
realizing that I needed this in the MPI/RT Test Suite, I solicited 
comments on the MPI/RT 1.1 email reflector.  The replies were mixed so
I made this a full proposal suitable for voting.

SUMMARY

Provide in the Standard a way for user code to get a string
representation of each error value.

BACKGROUND

In order for user code to report an error in a user-friendly fashion, it
is preferable to print "ERR_INV_KEYVAL" rather than "37".  Tracing down
the actual meaning of a numerical error code can often be difficult as
it typically appears in a library header file somewhere.

A user or third-party library writer could write a routine to convert
the numeric value to a string.  But if this functionality isn't included
as part of the implementation, it is difficult to do correctly.  For
instance, you don't know how many error codes there are or their
numerical values, so you can't just make an array of strings, you have
to make a big case statement or create a more complicated dynamically
allocated structure.

Even then, the above solutions are a maintenance problem because when
new error codes are added, this function must be revised.  And if you
add the newest error codes, the program is not portable to earlier
implementation versions that don't have the new error codes.  Also, if a
vendor decides to diagnose some additional error conditions, those error
codes won't be portable and may not be known to the user.

ISSUES

Even if we agree that the function is useful, an issue is whether it
belongs as part of the standard.

Some vendors may have a unified mechanism for reporting errors for all
their products and do not want to be restricted from incorporating
MPI/RT into their error reporting scheme.  This proposal does not
preclude any vendor-specific additional reporting capabilities.

Currently, there is no other actual functionality defined in Chapter 1,
but there doesn't seem to be a good alternative location.

PROPOSAL

Add a new section 1.4.4 titled "String Representation of Error Codes":

To allow for portable error handling by user code, the following
function provides a standard way for user code to get a string
representation of each error value.

MPIRT_ERROR_STRING(err_code, err_string)

  IN    err_code        error code (integer)

  OUT   err_string      string describing error (ref. to string)

int MPIRT_Error_string(int err_code, char** err_string)

int MPIRT::Error_String(int err_code, char*& err_string)

Given an MPI/RT error code, the library will return a pointer to a 
null-terminated string representation of that error code.  For instance, 
given the integer error code MPIRT_ERR_INV_QOS, the function would 
return a pointer to the string "MPIRT_ERR_INV_QOS".

If the given error code is undefined, the function returns a pointer to
the string representation of the signed decimal error number, e.g., "547"
or "-22".

A Production Library is allowed to return a pointer to any valid
null-terminated string including an empty string.

The result is a constant string; the user must not modify or free it.