Shared (thread independent) connections with MQCONNX

Use this information to learn about Shared connections with MQCONNX, and some usage notes to consider.

Note: Not supported on IBM MQ for z/OS . On IBM MQ platforms other than IBM MQ for z/OS, a connection made with MQCONN is available only to the thread that made the connection. Options on the MQCONNX call allow you to create a connection that can be shared by all the threads in a process. If the application is running in a transactional environment that requires MQI calls to be issued on the same thread, we must use the following default option:

    MQCNO_HANDLE_SHARE_NONE
    Creates a non-shared connection.

In most other environments, we can use one of the following thread independent, shared connection options:

    MQCNO_HANDLE_SHARE_BLOCK
    Creates a shared connection. On a MQCNO_HANDLE_SHARE_BLOCK connection, if the connection is currently in use by an MQI call on another thread, the MQI call waits until the current MQI call has completed.

    MQCNO_HANDLE_SHARE_NO_BLOCK
    Creates a shared connection. On a MQCNO_HANDLE_SHARE_NO_BLOCK connection, if the connection is currently in use by an MQI call on another thread, the MQI call fails immediately with a reason of MQRC_CALL_IN_PROGRESS.

Except for the MTS ( Microsoft Transaction Server) environment, the default value is MQCNO_HANDLE_SHARE_NONE. In the MTS environment, the default value is MQCNO_HANDLE_SHARE_BLOCK.

A connection handle is returned from the MQCONNX call. The handle can be used by subsequent MQI calls from any thread in the process, associating those calls with the handle returned from the MQCONNX. MQI calls using a single shared handle are serialized across threads.

For example, the following sequence of activity is possible with a shared handle:
  1. Thread 1 issues MQCONNX and gets a shared handle h1
  2. Thread 1 opens a queue and issues a get request using h1
  3. Thread 2 issues a put request using h1
  4. Thread 3 issues a put request using h1
  5. Thread 2 issues MQDISC using h1

While the handle is in use by any thread, access to the connection is unavailable to other threads. In circumstances where it is acceptable that a thread waits for any previous call from another thread to complete, use MQCONNX with the option MQCNO_HANDLE_SHARE_BLOCK.

However blocking can cause difficulties. Suppose that in step 2, thread 1 issues a get request that waits for messages that might not have yet arrived (a get with wait). In this case, threads 2 and 3 are also left waiting (blocked) for as long as the get request on thread 1 takes. If you prefer that an MQI call returns with an error if another MQI call is already running on the handle, use MQCONNX with the option MQCNO_HANDLE_SHARE_NO_BLOCK.


Shared connection usage notes

  1. Any object handles (Hobj) created by opening an object are associated with an Hconn; so for a shared Hconn, the Hobjs are also shared and usable by any thread using the Hconn. Similarly, any unit of work started under an Hconn is associated with that Hconn; so this too is shared across threads with the shared Hconn.
  2. Any thread can call MQDISC to disconnect a shared Hconn, not just the thread that called the corresponding MQCONNX. The MQDISC terminates the Hconn making it unavailable to all threads.
  3. A single thread can use multiple shared Hconns serially, for example use MQPUT to put one message under one shared Hconn then put another message using another shared Hconn, with each operation being under a different local unit of work.
  4. Shared Hconns cannot be used within a global unit of work.

Parent topic: Connect to a queue manager using the MQCONNX call