The C codebase indicates errors using Return and Reason codes. The C code does not have any exception handling mechanism, as in C++. WebSphere MQ Everyplace does not use the operating system error handling functions. An MQeExceptBlock handles errors and returns values from the functions. An application is free to install any operating system exception handlers that it requires.
The specific nature of an error condition is returned using two values, MQERETURN and MQEREASON. MQERETURN determines the general area in which the application failed, and distinguishes between warnings and errors. You can ignore warnings, but you must not ignore errors. With errors, your application needs to solve the problem in order to continue safely.
MQERETURN and MQEREASON are both returned in the MQeExceptBlock. The MQERETURN value is also the return value from the function.
The MQe_nativeReturnCodes.h header file lists all of the return and reason codes. They are divided into funtion area and then by error or warning. For example, MQERETURN_QUEUE_MANAGER_ERROR and MQERETURN_QUEUE_MANAGER_WARNING. Warnings indicate that a situation may be ignored.
The MQeExceptBlock structure is used to pass the return code and reason code, generated by a function call, back to the user. If a function call does not return MQERETURN_OK, use the ERC macro to get the reason code.
WebSphere MQ Everyplace ships two macros:
The convention within WebSphere MQ Everyplace is that a pointer to an exception block is passed first on a new function. A pointer to the object handle is passed second, followed by any additional parameters. On subsequent calls, the object handle is the first parameter passed, and the pointer to the exception block is second, followed by any additional parameters.
The structure of the exception block, as shown in the following example, is MQeExceptBlock_st.
struct MQeExceptBlock_st { MQERETURN ec; /* return code*/ MQEREASON erc; /* reason code*/ MQEVOID* reserved; /* reserved for internal use only*/ }
We recommend that you allocate the Exception Block on the stack, rather than the heap. This simplifies possible memory allocations, although there are no restrictions on allocating space on the heap. The following code demonstates how to do this:
MQERETURN rc MQeExceptBlock exceptBlock; /*.....initialisation*/ rc = mqeFunction_anyFunction(&exceptBlock, /*parameters go here*/); if (MQERETURN_OK ! = rc) { printf("An error has occured, return code = %d, reason code =%d \n", exceptBlock.ec exceptBlock.erc); }else { }
All API calls need to take exception blocks. The C Bindings codebase permits NULL to be passed to an API call. However, this feature is deprecated in the C codebase and, therefore, not recommended.
You should use a different exception block for each thread in the application.
A number of macros help to access the exception block:
MQeExceptBlock exceptBlock; SET_EXCEPT_BLOCK(&exceptBlock, MQERETURN_OK, MQEREASON_NA);
MQeExceptBlock exceptBlock; SET_EXCEPT_BLOCK_TO_DEFAULT(&exceptBlock);
MQeExceptBlock exceptBlk; /*WebSphere MQ Everyplace API call */ MQERETURN returncode; returnCode = EC(&exceptBlock);
MQeExceptBlock exceptBlk; /*WebSphere MQ Everyplace API call*/ MQEREASON reasoncode; MQEREASON reasonCode = ERC(&exceptBlock);