Connect to a queue manager using the MQCONN call

Use this information to learn how to connect to a queue manager using the MQCONN call.

In general, we can connect either to a specific queue manager, or to the default queue manager:

Alternatively, in the z/OS MVS batch, TSO, and RRS environments we can connect to any one queue manager within a queue sharing group. The MQCONN or MQCONNX request selects any one of the active members of the group.

When you connect to a queue manager it must be local to the task. It must belong to the same system as the IBM MQ application.

In the IMS environment, the queue manager must be connected to the IMS control region and to the dependent region that the program uses. The default queue manager is specified in the CSQQDEFV module when IBM MQ for z/OS is installed.

With the TXSeries CICS environment, and TXSeries for Windows and AIX, the queue manager must be defined as an XA resource to CICS.

To connect to the default queue manager, call MQCONN, specifying a name consisting entirely of blanks or starting with a null (X'00') character.

An application must be authorized for it to successfully connect to a queue manager. For more information, see Securing.

The output from MQCONN is:

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

Use the connection handle on subsequent MQI calls.

If the reason code indicates that the application is already connected to that queue manager, the connection handle that is returned is the same as the one that was returned when the application first connected. The application must not issue the MQDISC call in this situation because the calling application expects to remain connected.

The scope of the connection handle is the same as the scope of the object handle (see Opening objects using the MQOPEN call ).

Descriptions of the parameters are given in the description of the MQCONN call in MQCONN.

The MQCONN call fails if the queue manager is in a quiescing state when we issue the call, or if the queue manager is shutting down.


Scope of MQCONN or MQCONNX

The scope of an MQCONN or MQCONNX call is typically the thread that issued it. That is, the connection handle returned from the call is valid only within the thread that issued the call. Only one call can be made at any one time using the handle. If it is used from a different thread, it is rejected as invalid. If we have multiple threads in the application and each wants to use IBM MQ calls, each one must issue MQCONN or MQCONNX.

It is not necessary for each call to be made to the same queue manager when a process makes multiple MQCONN calls. However, only one IBM MQ connection can be made from a thread at a time. Alternatively, consider Shared (thread independent) connections with MQCONNX to allow multiple IBM MQ connections from a single thread and an IBM MQ connection to be used from any thread. 1

If the application is running as a client, it can connect to more than one queue manager within a thread.

Parent topic: Connect to and disconnecting from a queue manager 1 When using multithreaded applications with IBM MQ on UNIX and Linux systems we need to ensure that the applications have a sufficient stack size for the threads. Consider using a stack size of 256 KB, or larger, when multithreaded applications are making MQI calls, either by themselves or, with other signal handlers (for example, CICS ).