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; }
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.
There are several macros that help with accessing the Exception Block