Syncpoint considerations in IBM WebSphere MQ applications

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

Two-phase commit is supported under:
  • WebSphere MQ for AIX®
  • WebSphere MQ for HP-UX
  • WebSphere MQ for Linux®
  • WebSphere MQ for Solaris
  • WebSphere MQ for Windows
  • CICS® for MVS/ESA 4.1
  • CICS Transaction Server for z/OS®
  • TXSeries®
  • IMS/ESA®
  • Other external coordinators using the X/Open XA interface
Single-phase commit is supported under:
  • WebSphere MQ on UNIX systems
  • WebSphere MQ for Windows
Note: For further details on external interfaces see Interfaces to external syncpoint managers, 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 WebSphere MQ can be brought within the scope of a unit of work, managed by the transaction manager.

Samples shipped with WebSphere MQ show WebSphere MQ coordinating XA-compliant databases. For further information about these samples, see Sample programs for distributed platforms.

In your WebSphere 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. The syncpoint control default is no.

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.

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.

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.