Locally determined errors

Information about locally determined errors, which include failure on an MQI call, system interruptions, and messages that contain incorrect data.

The three most common causes of errors that the queue manager can report immediately are:

Failure of an MQI call; for example, because a queue is full
An interruption to the running of some part of the system on which your application depends; for example, the queue manager
Messages containing data that cannot be processed successfully

If you are using the asynchronous put facility, errors are not reported immediately. Use the MQSTAT call to retrieve status information about previous asynchronous put operations.

Failure of an MQI call

The queue manager can immediately report any errors in the coding of an MQI call. It does this using a set of predefined return codes. These are divided into completion codes and reason codes.

To show whether a call is successful, the queue manager returns a completion code when the call completes. There are three completion codes, indicating success, partial completion, and failure of the call. The queue manager also returns a reason code that indicates the reason for the partial completion or the failure of the call.

The completion and reason codes for each call are listed with the description of that call in Return codes. For more detailed information, including ideas for corrective action, see Messages and reason codes.

Design your programs to handle all the return codes that can arise from each call.

System interruptions

Your application might be unaware of any interruption if the queue manager to which it is connected has to recover from a system failure. However, you must design your application to ensure that your data is not lost if such an interruption occurs.

The methods that you can use to make sure that your data remains consistent depends on the platform on which your queue manager is running:

AIX®, Linux®, and Windows systems

In these environments, you can make your MQPUT and MQGET calls in the usual way, but you must declare sync points by using the MQCMIT and MQBACK calls (see Committing and backing out units of work ). In the CICS® environment, MQCMIT and MQBACK commands are disabled, because you can make your MQPUT and MQGET calls within units of work that are managed by CICS.

IBM® i

You can make your MQPUT and MQGET calls within global units of work that are managed by IBM i commitment control. You can declare sync points by using the native IBM i COMMIT and ROLLBACK commands or the language-specific commands. Local units of work are managed by IBM MQ using the MQCMIT and MQBACK calls.

z/OS®

In the CICS and IMS environments, you can make MQPUT and MQGET calls within units of work that are managed by CICS or IMS. In the batch environment, you can make MQPUT and MQGET calls in the same way, but you must declare sync points using:

The IBM MQ for z/OS MQCMIT and MQBACK calls (see Committing and backing out units of work ), or
The z/OS Transaction Management and Recoverable Resource Manager Services (RRS) to provide two-phase sync point support. RRS allows you to update both IBM MQ and other RRS-enabled product resources, such as Db2® stored procedure resources, within a single logical unit of work. For information about RRS sync point support see Transaction management and recoverable resource manager services.

Use persistent messages for carrying all data that you cannot afford to lose. Persistent messages are reinstated on queues if the queue manager has to recover from a failure.

With IBM MQ on AIX, Linux, and Windows, an MQGET or MQPUT call within your application will fail at the point of filling all the log files, with the message MQRC_RESOURCE_PROBLEM. For more information about log files on AIX, Linux, and Windows, see Logging: Making sure that messages are not lost.
For z/OS see Planning your logging environment on z/OS.

If the queue manager is stopped by an operator while an application is running, the quiesce option is usually used. The queue manager enters a quiescing state in which applications can continue to do work, but they must terminate as soon as convenient. Small, quick applications can probably ignore the quiescing state and continue until they terminate as normal. Longer running applications, or ones that wait for messages to arrive, should use the fail if quiescing option when they use the MQOPEN, MQPUT, MQPUT1, and MQGET calls. These options mean that the calls fail when the queue manager quiesces, but the application might still have time to terminate cleanly by issuing calls that ignore the quiescing state. Such applications could also commit, or back out, changes that they have made, and then terminate.

If the queue manager is forced to stop (that is, stop without quiescing), applications will receive the MQRC_CONNECTION_BROKEN reason code when they make MQI calls. Exit the application or, alternatively, on IBM MQ for IBM i, AIX, Linux, and Windows systems, issue an MQDISC call.

Messages containing incorrect data

When you use units of work in your application, if a program cannot successfully process a message that it retrieves from a queue, the MQGET call is backed out.

The queue manager maintains a count (in the BackoutCount field of the message descriptor) of the number of times that happens. It maintains this count in the descriptor of each message that is affected. This count can provide valuable information about the efficiency of an application. Messages with backout counts that are increasing over time are being repeatedly rejected; design your application so that it analyzes the reasons for this and handles such messages accordingly.

[z/OS] On IBM MQ for z/OS, to make the backout count survive restarts of the queue manager, set the HardenGetBackout attribute to MQQA_BACKOUT_HARDENED; otherwise, if the queue manager has to restart, it does not maintain an accurate backout count for each message. Setting the attribute this way adds the penalty of extra processing.

On IBM MQ for [IBM i] IBM i, AIX, Linux, and Windows systems, the backout count always survives the queue manager restarts.

[z/OS] Also, on IBM MQ for z/OS, when you remove messages from a queue within a unit of work, you can mark one message so that it is not made available again if the unit of work is backed out by the application. The marked message is treated as if it has been retrieved under a new unit of work. You mark the message that is to skip backout using the MQGMO_MARK_SKIP_BACKOUT option (in the MQGMO structure) when you use the MQGET call. See Skipping backout for more information about this technique.