Connect 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 works.

As input to MQCONNX, we 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 the parameters of MQCONNX is given in MQCONNX. The Options field allows you to set STANDARD_BINDING, FASTPATH_BINDING, SHARED_BINDING, or ISOLATED_BINDING for any version of MQCNO. We 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 IBM MQ application and the local queue manager agent run in separate processes. The IBM MQ application requests the IBM MQ operation and the local queue manager agent services the request. This is defined by the MQCNO_STANDARD_BINDING option on the MQCONNX call.

If you specify MQCNO_STANDARD_BINDING, the MQCONNX call uses either MQCNO_SHARED_BINDING or MQCNO_ISOLATED_BINDING, depending on the value of the DefaultBindType attribute of the queue manager, which is defined in qm.ini.

This is the default value.

If we are linking to the mqm library, then a standard server connection using the default bind type is attempted first. If the underlying server library failed to load, a client connection is attempted instead.

• If the MQ_CONNECT_TYPE environment variable is specified, one of the following options can be supplied to change the behavior of MQCONN or MQCONNX if MQCNO_STANDARD_BINDING is specified. (The exception to this is if MQCNO_FASTPATH_BINDING is specified with MQ_CONNECT_TYPE set to LOCAL or STANDARD to allow fastpath connections to be downgraded by the administrator without a related change to the application:

  Value	Meaning
  CLIENT	A client connection only is attempted.
  FASTPATH	This value was supported in previous releases, but is now ignored if specified.
  LOCAL	A server connection only is attempted. Fastpath connections are downgraded to a standard server connection.
  STANDARD	Supported for compatibility with previous releases. This value is now treated as LOCAL.

• If the MQ_CONNECT_TYPE environment variable is not set when MQCONN is called, a standard server connection using the default bind type is attempted. If the server library fails to load, a client connection is attempted.

MQCNO_FASTPATH_BINDING

Trusted applications imply that the IBM MQ application and the local queue manager agent become the same process. Because 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.

We need to link trusted applications to the threaded IBM MQ libraries. For instructions on how to set up an IBM MQ application to run as trusted, see MQCNO Options.

This option gives the highest performance.

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

MQCNO_SHARED_BINDING

Specify this option to make the application and the local queue manager agent run in separate processes. This maintains the integrity of the queue manager, that is, it protects the queue manager from errant programs. However, the application and the local queue manager agent share some resources.

This option is intermediate between MQCNO_FASTPATH_BINDING and MQCNO_ISOLATED_BINDING, both in terms of protecting the integrity of the queue manager, and in terms of the performance of MQI calls.

MQCNO_SHARED_BINDING is ignored if the queue manager does not support this type of binding. Processing continues as though the option had not been specified.

If an application has connected to the local queue manager using MQCNO_SHARED_BINDING, the queue manager can be stopped while the application is running. If you restart the queue manager while the application is still running, the attempt to start the queue manager fails with error AMQ7018 as the application is still holding on to resources needed by the queue manager.

In order to start the queue manager, we must stop the application.

MQCNO_ISOLATED_BINDING

Specify this option to make the application and the local queue manager agent run in separate processes, as for MQCNO_SHARED_BINDING. In this case, however, the application process and the local queue manager agent are isolated from each other in that they do not share resources.

This is the safest option for protecting the integrity of the queue manager, but it gives the slowest performance of MQI calls.

MQCNO_ISOLATED_BINDING is ignored if the queue manager does not support this type of binding. Processing continues as though the option had not been specified.

MQCNO_CLIENT_BINDING

Specify this option to make the application attempt a client connection only. This option has the following limitations:

• MQCNO_CLIENT_BINDING is ignored on z/OS.
• MQCNO_CLIENT_BINDING is rejected with MQRC_OPTIONS_ERROR if it is specified with any MQCNO binding option other than MQCNO_STANDARD_BINDING.
• MQCNO_CLIENT_BINDING is not available for Java as it has its own mechanisms for choosing the bind type.
• If the MQ_CONNECT_TYPE environment variable is not set when MQCONN is called, a standard server connection using the default bind type is attempted. If the server library fails to load, a client connection is attempted.

MQCNO_LOCAL_BINDING

Specify this option to make the application attempt a server connection. If either MQCNO_FASTPATH_BINDING, MQCNO_ISOLATED_BINDING, or MQCNO_SHARED_BINDING is also specified, then the connection is of that type instead, and is documented in this section. Otherwise a standard server connection is attempted using the default bind type. MQCNO_LOCAL_BINDING has the following limitations:

• MQCNO_LOCAL_BINDING is ignored on z/OS.
• MQCNO_LOCAL_BINDING is rejected with MQRC_OPTIONS_ERROR if it is specified with any MQCNO reconnect option other than MQCNO_RECONNECT_AS_DEF.
• MQCNO_LOCAL_BINDING is not available for Java as it has its own mechanisms for choosing the bind type.
• If the MQ_CONNECT_TYPE environment variable is not set when MQCONN is called, a standard server connection using the default bind type is attempted. If the server library fails to load, a client connection is attempted.

On z/OS these options are tolerated, but only a standard bound connection is performed.

MQCNO Version 3, for z/OS, allows four different options:

MQCNO_SERIALIZE_CONN_TAG_QSG

This allows an application to request that only one instance of an application runs at any one time in a queue sharing group. This is achieved by registering the use of a connection tag with a value that 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), 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. 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
  
• Shared (thread independent) connections with MQCONNX
  Use this information to learn about Shared connections with MQCONNX, and some usage notes to consider.
• MQCONNX environment variable
  Use this information to understand the different MQCONNX call options and how they are used with MQ_CONNECT_TYPE. Note that MQ_CONNECT_TYPE only has any effect for STANDARD bindings. For other bindings, MQ_CONNECT_TYPE is ignored.

Parent topic: Connect to and disconnecting from a queue manager