Parameters common to all the calls
There are two types of parameter common to all the calls: handles and return codes.
Using connection and object handles
For a program to communicate with a queue manager, the program must have a unique identifier by which it knows that queue manager. This identifier is called a connection handle, sometimes referred to as an Hconn. For CICS programs, the connection handle is always zero. For all other platforms or styles of programs, the connection handle is returned by the MQCONN or MQCONNX call when the program connects to the queue manager. Programs pass the connection handle as an input parameter when they use the other calls.
For a program to work with a WebSphere MQ object, the program must have a unique identifier by which it knows that object. This identifier is called an object handle, sometimes referred to as an Hobj. The handle is returned by the MQOPEN call when the program opens the object to work with it. Programs pass the object handle as an input parameter when they use subsequent MQPUT, MQGET, MQINQ, MQSET, or MQCLOSE calls.
Understanding return codes
A completion code and a reason code are returned as output parameters by each call. These are known collectively as return codes.
To show whether or not a call is successful, each call returns a completion code when the call is complete. The completion code is usually either MQCC_OK or MQCC_FAILED, showing success and failure, respectively. Some calls can return an intermediate state, MQCC_WARNING, indicating partial success.
Each call also returns a reason code that shows the reason for the failure, or partial success, of the call. There are many reason codes, covering such circumstances as a queue being full, get operations not being allowed for a queue, and a particular queue not being defined for the queue manager. Programs can use the reason code to decide how to proceed. For example, they could prompt the user of the program to make changes to his input data, then make the call again, or they could return an error message to the user.
When the completion code is MQCC_OK, the reason code is always MQRC_NONE.
The completion and reason codes for each call are listed with the description of that call in WebSphere MQ Application Programming Reference. This also contains further information (including some ideas for corrective action) for each completion and reason code.
WebSphere is a trademark of the IBM Corporation in the United States, other countries, or both.
IBM is a trademark of the IBM Corporation in the United States, other countries, or both.