Connecting to a queue manager using the MQCONNX call
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. 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.
- 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.
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.
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.
- 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 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:
- 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.
- 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:
- trusted applications cannot be compiled using the PL/I programming language.
- 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
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
You can use the environment variable, MQ_CONNECT_TYPE (MQCONNECTTYPE on MQSeries for Compaq NonStop Kernel) 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 1:
Table 1. 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.
WebSphere is a trademark of the IBM Corporation in the United States, other countries, or both.
IBM is a trademark of the IBM Corporation in the United States, other countries, or both.