EimRC--EIM Return Code Parameter

All EIM APIs return an errno. If the EimRC parameter is not NULL, this EIM return code structure contains additional information about the error that was returned. It can be used to get a text description of the error.

The layout for EimRC follows:

typedef struct EimRC {
    unsigned int memoryProvidedByCaller; /* Input: Size of the entire RC
                                     structure. This is filled in by
                                     the caller. This is used to tell
                                     the API how much space was provided
                                     for substitution text            */
    unsigned int  memoryRequiredToReturnData;/* Output: Filled in by API
                                     to tell caller how much data could 
                                     have been returned. Caller can then
                                     determine if the caller provided
                                     enough space (that is, if the 
                                     entire substitution string was 
                                     able to be copied to this 
                                     structure.                       */
    int  returnCode;                /* Same as the errno returned as the
                                     rc for the API                   */
    int messageCatalogSetNbr;       /* Message catalog set number     */
    int messageCatalogMessageID;    /* Message catalog message id     */
    int ldapError;                  /* ldap error, if available       */
    int sslError;                   /* ssl error, if available        */
    char     reserved[16];          /* Reserved for future use        */
    unsigned int substitutionTextLength; /* Length of substitution text
                                     excluding a null-terminator which
                                     may or may not be present        */
    char substitutionText[1];       /* further info describing the
                                     error.                           */
} EimRC;

Field Descriptions

memoryProvidedByCaller

(Input) The number of bytes the calling application provides for the error code. The number of bytes provided must be 48, or more than 48.

memoryRequiredToReturnData

(Output) The length of the error information available to the API to return, in bytes. If this is 0, no error was detected and none of the fields that follow this field in the structure are changed.

returnCode

(Output) The errno returned for this API. This is the same as the return value for each API.

messageCatalogSetNbr

(Output) The message set number for the EIM catalog. This can be used with the messageCatalogID to get the error message text.

messageCatalogMessageID

(Output) The message ID number for the EIM catalog. This can be used with the messageCatalogSetNbr to get the error message text.

reserved

(Output) Reserved for future use.

substitutionTextLength

(Output) This field is set if any substitution text is returned. If there is no substitution text, this field is zero.

substitutionText

(Output) Message substitution text.

Example

See Code disclaimer information for information pertaining to code examples.

The following example shows how to retrieve the message text from the message catalog.

#include <nl_types.h>
#include <eim.h>

char  * getError(EimRC * eimrc)
{
    nl_catd catd;
    char * catmsg;
    char * msg = NULL;

    catd = catopen("/QIBM/PRODDATA/OS400/MRI2924/EIM/EIM.CAT", 0);
    if (NULL == catd)
       return NULL;

    catmsg = catgets(catd,
                     eimrc->messageCatalogSetNbr,
                     eimrc->messageCatalogMessageID,
                     strerror(eimrc->returnCode));

    if (catmsg)
    {
       msg = (char *)malloc(strlen(catmsg)+
                        eimrc->substitutionTextLength+1);

       if (0 == eimrc->substitutionTextLength)
          sprintf(msg,catmsg);
       else
          sprintf(msg, catmsg, eimrc->substitutionText);
       
    }
    catclose(catd);
    
    return msg;
}

Note: To use the message catalog support in nl_types.h, you must compile the parts with LOCALETYPE(*LOCALE) and SYSIFCOPT(*IFSIO).