Connecting to a queue manager using the MQCONNX call

MQCONNX is not supported on Compaq NonStop Kernel or VSE/ESA.

The MQCONNX call is similar to the MQCONN call, but includes options to control the way that the call actually works.

As input to MQCONNX, you can supply a queue manager name, or a queue-sharing group name on z/OS shared queue systems. The output from MQCONNX is:

A connection handle (Hconn)
A completion code
A reason code

You use the connection handle on subsequent MQI calls.

A description of all of the parameters of MQCONNX is given in WebSphere MQ Application Programming Reference. The Options field allows you to set STANDARD_BINDING or FASTPATH_BINDING for Version 1 and Version 2 MQCNO. You can also make shared (thread independent) connections using a MQCONNX call. See Shared (thread independent) connections with MQCONNX for more information about these.

MQCNO_STANDARD_BINDING

By default, MQCONNX (like MQCONN) implies two logical threads where the WebSphere MQ application and the local queue manager agent run in separate processes. The WebSphere MQ application requests the WebSphere MQ operation and the local queue manager agent services the request. This is defined by the MQCNO_STANDARD_BINDING option on the MQCONNX call.

Note:: This default maintains the integrity of the queue manager (that is, it makes the queue manager immune to errant programs), but impairs the performance of the MQI calls.

MQCNO_FASTPATH_BINDING

Trusted applications imply that the WebSphere MQ application and the local queue manager agent become the same process. Since the agent process no longer needs to use an interface to access the queue manager, these applications become an extension of the queue manager. This is defined by the MQCNO_FASTPATH_BINDING option on the MQCONNX call.

You need to link trusted applications to the threaded WebSphere MQ libraries. For instructions on how to set up a WebSphere MQ application to run as trusted, see WebSphere MQ Application Programming Reference.

Note:: This option compromises the integrity of the queue manager as there is no protection from overwriting its storage. This also applies if the application contains errors which can be exposed to messages and other data in the queue manager too. These issues must be considered before using this option.

For z/OS these two options are tolerated, but only a standard bound connection is performed. MQCNO Version 3, for z/OS, allows four new options:

MQCNO_SERIALIZE_CONN_TAG_QSG: This allows an application to request that only one instance of an application may be running at any one time in a queue-sharing group. This is achieved by registering the use of a connection tag, whose value is specified or derived by the application. The tag is a 128 byte character string specified in the Version 3 MQCNO.
MQCNO_RESTRICT_CONN_TAG_QSG: This is used where an application consists of more than one process (or a TCB on z/OS), each of which can connect to a queue manager. Connection is permitted only if there is no current use of the tag, or the requesting application is within the same processing scope. For z/OS this is MVS address space within the same queue-sharing group as the tag owner.
MQCNO_SERIALIZE_CONN_TAG_Q_MGR: This is similar to MQCNO_SERIALIZE_CONN_TAG_QSG, but only the local queue manager is interrogated to see if the requested tag is already in use.
MQCNO_RESTRICT_CONN_TAG_Q_MGR: This is similar to MQCNO_RESTRICT_CONN_TAG_QSG, but only the local queue manager is interrogated to see if the requested tag is already in use.

Restrictions for trusted applications

The following restrictions apply to trusted applications:

You must explicitly disconnect trusted applications from the queue manager.
You must stop trusted applications before ending the queue manager with the endmqm command.
You must not use asynchronous signals and timer interrupts (such as sigkill) with MQCNO_FASTPATH_BINDING.
On WebSphere MQ on UNIX systems you must use mqm as the effective userID and groupID for all MQI calls. You may change these IDs before making a non-MQI call requiring authentication (for example, opening a file), but you must change it back to mqm before making the next MQI call.
On WebSphere MQ for iSeries:
1. trusted applications must be run under the QMQM user profile. It is not sufficient that the user profile be member of the QMQM group or that the program adopt QMQM authority. It may not be possible, or desirable, for the QMQM user profile to be used to sign on to interactive jobs, or be specified in the job description for jobs running trusted applications. In this case one approach is to use the OS/400 profile swapping API functions, QSYGETPH, QWTSETP and QSYRLSPH to temporarily change the current user of the job to QMQM while the MQ programs run. Details of these functions together with an example of their use is provided in the Security APIs section of iSeries System API Reference.
2. trusted applications must not be canceled through the use of System-Request Option 2, or by the jobs in which they are running being ended using ENDJOB.
On all platforms, a thread within a trusted application cannot connect to a queue manager while another thread in the same process is connected to a different queue manager.
On WebSphere MQ for AIX:
1. trusted applications cannot be compiled using the PL/I programming language.
2. trusted applications must have the environment variable EXTSHM set to ON in their environment before the application starts, otherwise the connection will be downgraded to a standard connection.

Shared (thread independent) connections with MQCONNX

Not supported in WebSphere MQ for z/OS.

On WebSphere MQ platforms other than WebSphere MQ for z/OS, a connection made with MQCONN is only available 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.

Use one of the following options to make a thread independent or shared connection:

MQCNO_HANDLE_SHARE_BLOCK	Creates a shared connection on which, if the connection is currently in use by another thread, an MQI call will wait until the current MQI call has completed
MQCNO_HANDLE_SHARE_NO_BLOCK	Creates a shared connection on which, if the connection is currently in use by another thread, an MQI call will fail immediately with a reason of MQRC_CALL_IN_PROGRESS
MQCNO_HANDLE_SHARE_NONE	Creates a standard non-shared connection

In the normal MQI environment the default value is MQCNO_HANDLE_SHARE_NONE. In the MTS environment the default value is MQCNO_HANDLE_SHARE_BLOCK.

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

For example, the following sequence of activity is possible with a shared Hconn:

Thread 1 issues MQCONNX and gets a shared Hconn h1
Thread 1 opens a queue and issues a get request using h1
Thread 2 issues a put request using h1
Thread 3 issues a put request using h1
Thread 2 issues MQDISC using h1

While the Hconn 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 this can cause difficulties. Suppose that in step 2 above, the thread issued a get request that waits for messages that may not have yet arrived (a get with wait). In this case, threads 2 and 3 will also be left waiting (blocked) for as long as the get request takes. If you prefer that your application is notified of calls that are already running on the Hconn, use MQCONNX with the option MQCNO_HANDLE_SHARE_NO_BLOCK.

Shared connection usage notes

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.
Any thread can call MQDISC to disconnect a shared Hconn, not just the thread that called the corresponding MQCONNX. The MQDISC will terminate the Hconn making it unavailable to all threads.
A single thread can use multiple shared Hconns serially, for example MQPUT one message under one shared Hconn then MQPUT another message using another shared Hconn, with each operation being under a different local unit of work.
Shared Hconns cannot be used within a global unit of work.

MQCONNX environment variable

On WebSphere MQ for iSeries, MQSeries for OS/2 Warp, WebSphere MQ for Windows, and WebSphere MQ on UNIX systems, the environment variable, MQ_CONNECT_TYPE, can be used in combination with the type of binding specified in the Options field. This environment variable allows you to execute the application with the STANDARD_BINDING if any problems occur with the FASTPATH_BINDING. If the environment variable is specified, it should have the value FASTPATH or STANDARD to select the type of binding required. However, the FASTPATH binding is used only if the connect option is appropriately specified as shown in Table 2:

Table 2. The MQ_CONNECT_TYPE environment variable

MQCONNX call option	MQ_CONNECT_TYPE environment variable	Result
STANDARD	UNDEFINED	STANDARD
FASTPATH	UNDEFINED	FASTPATH
STANDARD	STANDARD	STANDARD
FASTPATH	STANDARD	STANDARD
STANDARD	FASTPATH	STANDARD
FASTPATH	FASTPATH	FASTPATH

So, to run a trusted application, either:

Specify the MQCNO_FASTPATH_BINDING option on the MQCONNX call and the FASTPATH environment variable,

or
Specify the MQCNO_FASTPATH_BINDING option on the MQCONNX call and leave the environment variable undefined.

If neither MQCNO_STANDARD_BINDING nor MQCNO_FASTPATH_BINDING is specified, you can use MQCNO_NONE, which defaults to MQCNO_STANDARD_BINDING.