Connect 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:- 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.
- If the MQSERVER environment variable is set, the channel that it defines is used.
- 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.
- 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.
- 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.
- 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.
- Connect client applications to queue managers using environment variables
Client channel information can be supplied to an application running in a client environment by environment variables. - Connect client applications to queue managers using the MQCNO structure
We can specify the definition of the channel in a channel definition structure (MQCD), which is supplied using the MQCNO structure of the MQCONNX call. - Connect client applications to queue managers using a client channel definition table
If we use the MQSC DEFINE CHANNEL command, the details you provide are placed in the client channel definition table (ccdt). The contents of the QMgrName parameter of the MQCONN or MQCONNX call determines which queue manager the client connects to. - Use automatic client reconnection
We can make client applications reconnect automatically, without writing any additional code, by configuring a number of components. - Role of the client channel definition table
The client channel definition table (CCDT) contains definitions of client connection channels. It is particularly useful if your client applications might need to connect to a number of alternative queue managers. - Examples of channel weighting and affinity
These examples illustrate how client-connection channels are selected when non-zero ClientChannelWeights are used. - Examples of MQCONN calls
Examples of using MQCONN to connect to a specific queue manager, or to one of a group of queue managers.
Parent topic: Running applications in the IBM MQ MQI client environment
Related information
- Client channel definition table
- Web addressable access to the client channel definition table
- MQSERVER
- MQCHLLIB
- MQCHLTAB
- MQCCDTURL
- Configure connections between the server and client
- MQCNO - Connect options