Main Page   Modules   Data Structures   File List   Data Fields   Globals   Related Pages  

Error Handling

When using C code, there are no exception handling mechanisms such as in C++ (note that Websphere MQ Everyplace for Native Platforms does not interact with or use the operating system exception handling functionality). All error handling is done via an "Exception Block" and return values from the functions. An application is free to install any operating system exception handlers it requires.

The specific nature of an error condition is returned using two values, MQERETURN and MQEREASON. MQERETURN determines the broad area of failure, and will distinguish between warnings and errors. Warnings may be ignored, whereas errors may not. When errors are returned, your application will need to take action in order to continue safely.

The MQERETURN and MQEREASON values are both returned in the ExceptionBlock. In addition the MQERETURN value will also constitute the return value from the function.

The structure of the exception block is MQeExceptBlock_st

         struct MQeExceptBlock_st
         {
            MQERETURN           ec;           /* return code */
            MQEREASON           erc;          /* reason code */
            MQEVOID *           reserved;     /* reserved for internal use only */
         };
   

A full list of the possible return and reason codes is provided in MQe_Native_ReturnCodes.h. This file lists a constant for each value. It is possible to convert a numeric value to a textual value using the following code. Note that this code will increase the size of your code by about 20Kb. It is important to add the following code after including MQe_API.h - for instance, insert it at the end of your application.

#define BUILDING_FORMATTER
#undef MQE_RETURN_CODES_H_INCLUDED 
#include <published/MQe_Native_ReturnCodes.h>

char* mapReturnCodeName(unsigned int rc) {

    unsigned int i = 0;

    for ( i =0; MQERETURN_Array[i].entry != rc && MQERETURN_Array[i].entry !=-1; i++ ) {
        NULL; /* empty block */
    };

    return MQERETURN_Array[i].name;

}

char* mapReasonCodeName(unsigned int rc) {

    unsigned int i = 0;

    for ( i =0; MQEREASON_Array[i].entry != rc && MQEREASON_Array[i].entry !=-1; i++ ) {
        NULL; /* empty block */
    };

    return MQEREASON_Array[i].name;

}


Obtaining an Exception Block

It is recommended that the exception block is allocated on the stack, rather than the heap. This is to simplify possible memory allocations, although there is no programmatic restriction against allocating space on the heap. At its simplest, your code would look like this:

    MQERETURN rc
    MQeExceptBlock exceptBlock;
    /* .... initialization */
    rc = mqeFunction_anyFunction(&exceptBlock,   /* parameters go here */ );
    if (MQERETURN_OK != rc ) {
        printf("An error has occurred , return code = %d,  reason code = %d \n", exceptBlock.ec exceptBlock.erc);
    } else {
    
    }

If you are not interested in the status of a call, then NULL can be passed as the exception block. Note that if an error does occur and corrective action is not taken, subsequent API calls could put the system in an unpredictable state.

Useful Macros

There are several macros that help with accessing the Exception Block


Generated Thu Aug 11 23:27:18 2005 for Websphere MQ Everyplace for Multiplatforms C Programming Reference