Connecting IBM MQ MQI client applications to queue managers

An application running in an IBM MQ MQI client environment can connect to a queue manager in various ways. We can use environment variables, the MQCNO structure, or a client definition table.

When an application running in an IBM MQ client environment issues an MQCONN or MQCONNX call, the client identifies how it is to make the connection. When an MQCONNX call is issued by an application on an IBM MQ client, the MQI client library searches for the client channel information in the following order:
  1. Use the contents of the ClientConnOffset or ClientConnPtr fields of the MQCNO structure (if supplied). These fields identify the channel definition structure (MQCD) to be used as the definition of the client connection channel. Connection details can be overridden by using a pre-connect exit. For more information, see Referencing connection definitions using a pre-connect exit from a repository.
  2. If the MQSERVER environment variable is set, the channel that it defines is used.
  3. If an mqclient.ini file is defined and contains a ServerConnectionParms, the channel that it defines is used. For more information, see Configure a client using a configuration file and CHANNELS stanza of the client configuration file.
  4. If the MQCHLLIB and MQCHLTAB environment variables are set, the client channel definition table that they point to is used. Alternatively, from IBM MQ Version 9.0, the MQCCDTURL environment variable provides the equivalent capability to setting a combination of the MQCHLLIB and MQCHLTAB environment variables. If MQCCDTURL is set, the client channel definition table that it points to is used. For more information, see Web addressable access to the client channel definition table.
  5. If an mqclient.ini file is defined and contains ChannelDefinitionDirectory and ChannelDefinitionFile attributes, these attributes are used to locate the client channel definition table. For more information, see Configure a client using a configuration file and CHANNELS stanza of the client configuration file.
  6. Finally, if the environment variables are not set, the client searches for a client channel definition table with a path and name that are established from the DefaultPrefix in the mqs.ini file. If the search for a client channel definition table fails, the client uses the following paths:

    • On UNIX and Linux : /var/mqm/AMQCLCHL.TAB
    • On Windows: C:\Program Files\IBM\MQ\amqclchl.tab
    • On IBM i: /QIBM/UserData/mqm/@ipcc
    • On IBM MQ Appliance: QMname_AMQCLCHL.TAB. They appear under the mqbackup:// URI.

The first of the options described in the previous list (using the ClientConnOffset or ClientConnPtr fields of MQCNO) is supported only by the MQCONNX call. If the application is using MQCONN rather than MQCONNX, the channel information is searched for in the remaining five ways in the order shown in the list. If the client fails to find the channel information, the MQCONN or MQCONNX call fails.

The channel name (for the client connection) must match the server-connection channel name defined on the server for the MQCONN or MQCONNX call to succeed.