Syncpoint considerations in IBM MQ applications

Use this information to learn about using syncpoints in IBM® MQ applications.

Two-phase commit is supported by the following environments:
  • [AIX]IBM MQ for AIX®
  • [IBM i]IBM MQ for IBM i
  • [HP-UX]IBM MQ for HP-UX
  • [Linux]IBM MQ for Linux®
  • [Solaris]IBM MQ for Solaris
  • [Windows]IBM MQ for Windows
  • [z/OS]CICS® Transaction Server for z/OS®
  • [z/OS]TXSeries®
  • [z/OS]IMS/ESA®
  • [z/OS]z/OS batch with RRS
  • Other external coordinators using the X/Open XA interface
Single-phase commit is supported by the following environments:
  • [IBM i]IBM MQ for IBM i
  • [UNIX]IBM MQ on UNIX
  • [Windows]IBM MQ for Windows
  • [z/OS] z/OS batch

For further information about external interfaces, see Interfaces to external syncpoint managers on Multiplatforms, and the XA documentation CAE Specification Distributed Transaction Processing: The XA Specification, published by The Open Group. Transaction managers (such as CICS, IMS, Encina, and Tuxedo) can participate in two-phase commit, coordinated with other recoverable resources. This means that the queuing functions provided by IBM MQ can be brought within the scope of a unit of work, managed by the transaction manager.

Samples shipped with IBM MQ show IBM MQ coordinating XA-compliant databases. For further information about these samples, see Using the IBM MQ sample procedural programs.

In your IBM MQ application, you can specify on every put and get call whether you want the call to be under syncpoint control. To make a put operation operate under syncpoint control, use the MQPMO_SYNCPOINT value in the Options field of the MQPMO structure when you call MQPUT. For a get operation, use the MQGMO_SYNCPOINT value in the Options field of the MQGMO structure. If you do not explicitly choose an option, the default action depends on the platform:
  • [UNIX, Linux, Windows, IBM i]The syncpoint control default is NO.
  • [z/OS]The syncpoint control default is YES.

When an MQPUT1 call is issued with MQPMO_SYNCPOINT, the default behavior changes, so that the put operation is completed asynchronously. This might cause a change in the behavior of some applications that rely on certain fields in the MQOD and MQMD structures being returned, but which now contain undefined values. An application can specify MQPMO_SYNC_RESPONSE to ensure that the put operation is performed synchronously and that all of the appropriate field values are completed.

When your application receives an MQRC_BACKED_OUT reason code in response to an MQPUT or MQGET under syncpoint, the application should normally back out the current transaction using MQBACK and then, if appropriate, try the entire transaction again. If the application receives MQRC_BACKED_OUT in response to an MQCMIT or MQDISC call, it does not need to call MQBACK.

Every time an MQGET call is backed out, the BackoutCount field of the MQMD structure of the affected message is incremented. A high BackoutCount indicates a message that has been repeatedly backed out. This might indicate a problem with this message, which you should investigate. See BackoutCount for details of BackoutCount.

Except on z/OS batch with RRS, if a program issues the MQDISC call while there are uncommitted requests, an implicit syncpoint occurs. If the program ends abnormally, an implicit backout occurs.

[z/OS]On z/OS, an implicit syncpoint also occurs if the program ends normally without first calling MQDISC. The program is deemed to have ended normally if the TCB connected to MQ ends normally. When running under z/OS UNIX System Services and Language Environment (LE), default condition handling is invoked for abends or signals. The LE condition handlers process the error condition and the TCB ends normally. Under these conditions MQ commits the unit of work. For more information, see Introduction to Language Environment Condition Handling.

[z/OS]For IBM MQ for z/OS programs, you can use the MQGMO_MARK_SKIP_BACKOUT option to specify that a message must not be backed out if backout occurs (in order to avoid an MQGET-error-backout loop). For information about using this option, see Skipping backout.

Changes to queue attributes (either by the MQSET call or by commands) are not affected by the committing or backing out of units of work.