proposals for enumeration of interface-specific error codes

[Jason Kraftcheck]

The need for interface-specific error codes was discussed during the 
boot camp.  The following items were agreed upon:

o New error codes should be set to the list for review.
o All error codes should be included in the iBase_ErrorType enumeration
   (defined in iBase.h)
o Interface-specific error codes should be prefixed with the name of the
   interface that they are specific to in place of the iBase prefix.  For
   example: iMeshP_NO_PARTITION rather than iBase_NO_PARTITION.
o The error codes should be enumerated such that adding a new error code
   does not break implementations of different interfaces that use an
   array of strings to implement i*_getDescription.  For example, adding
   a new iMeshP_* error code should not break iRel_* implementations.

Below I will propose three alternate schemes for addressing the last 
point (only).

All of these schemes have the additional beneficial property that things 
will not break if interface-specific error codes are added to the list 
for an interface for which there were no specific error codes, 
effectively changing the ordering of the blocks of interface-specific codes.

--------------------------------- 1 ----------------------------------

My first, and most controversial suggestion, is to ignore the issue. 
Getting an error string from an error code should not be a 
performance-sensitive issue.  There is no reason not to use a switch 
statement to obtain the string for an error code rather than indexing 
into an array, and such a solution does not break in difficult to catch 
ways when the list of error codes changes.

--------------------------------- 2 ----------------------------------

The second solution is to do the array based indexing using relative 
values.  Similar to my first proposed solution, this solution requires 
nothing special be done in the iBase_ErrorType definition.

The index into the array of interface-specific error codes can be 
determined by subtracting the first interface-specific error code from 
the passed error code.  For example:

Given:

   enum iBase_ErrorType {
     iBase_SUCCESS,
     iBase_MESH_ALREADY_LOADED,
     iBase_NO_MESH_DATA,
     ...
     iBase_FAILURE,

     iRel_NO_RELATION,
     ...
     iRel_NO_SETS,

     iMeshP_NO_PARTITION,
     iMeshP_NO_PART,
   };

Do something like:

const iBase_ErrorType first_irel_error = iRel_NO_RELATION;
if (error_code >= first_irel_error)
   return iRel_error_strings[error_code - first_irel_error];


---------------------------------- 3 ---------------------------------

The final suggestion is to use explicit fixed offsets.  This is probably 
most like what the those in the group who expressed a need for this 
requirement expected.  However, it also results in a fairly sparse 
array.  That makes the use of a single common function to for all 
implementations that indexes into a single array more difficult.

Move this enumeration from the iRel.h header to iBase.h (this should 
probably be done anyway):

   enum IfaceType
   {iRel_IBASE_IFACE = 0,
    iRel_IGEOM_IFACE,
    iRel_IMESH_IFACE,
    iRel_IFIELD_IFACE,
    iRel_IREL_IFACE};

and change it to be the following:
   enum iBase_IfaceType
   {
     iBase_IBASE_IFACE = 0,
     iBase_IGEOM_IFACE,
     iBase_IMESH_IFACE,
     iBase_IMESHP_IFACE,
     iBase_IFIELD_IFACE,
     iBase_IREL_IFACE
   };

Now explicitly define the first interface-specific error code for each 
interface to be 100 times the corresponding value in the IfaceType 
enumeration.

For example:


   enum iBase_ErrorType {
     iBase_SUCCESS = 100*iBase_IBASE_IFACE,
     iBase_MESH_ALREADY_LOADED,
     iBase_NO_MESH_DATA,
     ...
     iBase_FAILURE,

     iRel_NO_RELATION = 100*iBase_IREL_IFACE,
     ...
     iRel_NO_SETS,

     iMeshP_NO_PARTITION = 100*iBase_IMESHP_IFACE,
     iMeshP_NO_PART,
   };