Rules for selecting the IBM MQ messaging provider mode

The IBM® MQ messaging provider has three modes of operation: normal mode, normal mode with restrictions, and migration mode. You can select which of these modes of operation a JMS application uses to publish and subscribe by setting the PROVIDERVERSION property for the connection factory to the appropriate value. In some cases, the PROVIDERVERSION property is set as unspecified, in which case an algorithm is used to determine which mode of operation to use.

If you cannot change the connection factory that you are using, you can use the com.ibm.msg.client.wmq.overrideProviderVersion property to override any setting on the connection factory. This override applies to all connection factories in the JVM but the actual connection factory objects are not modified.

You can set the PROVIDERVERSION property to any of the values 8 (normal mode), 7 (normal mode with restrictions), 6 (migration mode), or unspecified (the default value). The value that you specify for the PROVIDERVERSION property must be a string. If you are specifying an option of 8, 7 or 6, you can do this in any of the following formats:
  • V.R.M.F
  • V.R.M
  • V.R
  • V
where V, R, M and F are integer values greater than or equal to zero. The extra R, M and F values are optional and are available for you to use in case fine grained control is needed. For example, if you wanted to use a PROVIDERVERSION level of 7, you could set PROVIDERVERSION=7, 7.0, 7.0.0 or 7.0.0.0.
8 - Normal mode
The JMS application uses the IBM MQ messaging provider normal mode. Normal mode uses all the features of a IBM MQ queue manager to implement JMS. This mode is optimized to use the JMS 2.0 API and functionality.

If you are connecting to a queue manager with a command level of 800, then all of the JMS 2.0 API and features, such as asynchronous send, delayed delivery, or shared subscription, can be used.

If the queue manager specified in the connection factory settings is not a Version 8.0.0 queue manager, the createConnection method fails with an exception JMSFMQ0003.

The IBM MQ messaging provider normal mode uses the sharing conversations feature and the number of conversations that can be shared is controlled by the SHARECNV() property on the server connection channel. If this property is set to 0, you cannot use IBM MQ messaging provider normal mode and the createConnection method fails with an exception JMSCC5007.

7 - Normal mode with restrictions
The JMS application uses the IBM MQ messaging provider normal mode with restrictions. This mode uses the JMS 2.0 API, but not the new features such as shared subscriptions, delayed delivery, or asynchronous send.

If you set PROVIDERVERSION to 7 only the IBM MQ messaging provider normal with restrictions mode of operation is available. If the queue manager specified in the connection factory settings is not a Version 7.0.1, or later, queue manager, the createConnection method fails with exception JMSFCC5008.

If you are connecting using normal mode with restrictions, to a queue manager with a command level between 700 and 800 then you can use the JMS 2.0 API, but not the asynchronous send, delayed delivery, or shared subscription features.

The IBM MQ messaging provider normal mode with restrictions uses the sharing conversations feature and the number of conversations that can be shared is controlled by the SHARECNV() property on the server connection channel. If this property is set to 0, you cannot use IBM MQ messaging provider normal mode with restrictions and the createConnection method fails with an exception JMSCC5007.

6 - Migration mode
The JMS application uses the IBM MQ messaging provider migration mode.

The IBM MQ classes for JMS use the features and algorithms supplied with IBM WebSphere® MQ 6.0. If you want to connect to WebSphere Message Broker Version 6.0 or 6.1 using IBM WebSphere MQ Enterprise Transport Version 6.0, you must use this mode. You can connect to a IBM MQ 8.0 queue manager using this mode, but none of the new features of a IBM MQ classes for JMS queue manager are used, for example, read ahead or streaming.

If you have a IBM MQ 8.0 client connecting to a IBM MQ 8.0 queue manager, then the message selection is done by the queue manager rather than on the client system.

If IBM MQ messaging provider migration mode is specified and you attempt to use any of the JMS 2.0 API, the API method call fails with the exception JMSCC5007.

unspecified (default)
The PROVIDERVERSION property is set to unspecified by default.

A connection factory that was created with a previous version of IBM MQ classes for JMS in JNDI takes this value when the connection factory is used with the new version of IBM MQ classes for JMS. The following algorithm is used to determine which mode of operation is used. This algorithm is used when the createConnection method is called and uses other aspects of the connection factory to determine if IBM MQ messaging provider normal mode, normal mode with restrictions, or IBM MQ messaging provider migration mode is required.

  1. First, an attempt to use IBM MQ messaging provider normal mode is made.
  2. If the queue manager connected is not IBM MQ 8.0, or later, an attempt to use IBM MQ messaging provider normal mode with restrictions is made.
  3. If the queue manager connected is not IBM WebSphere MQ 7.0.1, or later, the connection is closed and IBM MQ messaging provider migration mode is used instead.
  4. If the SHARECNV property on the server connection channel is set to 0, the connection is closed and IBM MQ messaging provider migration mode is used instead.
  5. If BROKERVER is set to V1 or the default unspecified value, IBM MQ messaging provider normal mode continues to be used, and therefore any publish/subscribe operations use the new IBM WebSphere MQ 7.0.1, or later, features.

    See ALTER QMGR for information about the PSMODE parameter of the ALTER QMGR command for further information on compatibility.

  6. If BROKERVER is set to V2 the action taken depends on the value of BROKERQMGR :
    • If the BROKERQMGR is blank:
      • If the queue specified by the BROKERCONQ property can be opened for output (that is, MQOPEN for output succeeds) and PSMODE on the queue manager is set to COMPAT or DISABLED, then IBM MQ messaging provider migration mode is used.
    • If the queue specified by the BROKERCONQ property cannot be opened for output, or the PSMODE attribute is set to ENABLED:
      • IBM MQ messaging provider normal mode is used.
    • If BROKERQMGR is non-blank :
      • IBM MQ messaging provider migration mode is used.