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. You can use environmental variables, the MQCNO structure, or a client definition table.
- Using the contents of the
ClientConnOffset
orClientConnPtr
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 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 Configuring 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 they point to is used.
- 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 Configuring 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 themqs.ini
file. If the search for a client definition table fails, the client uses the following paths:- UNIX and Linux® systems: /var/mqm/AMQCLCHL.TAB
- Windows: C:\Program Files\IBM\WebSphere MQ\amqclchl.tab
- IBM i: /QIBM/UserData/mqm/@ipcc
- 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.
If you receive an MQRC_Q_MGR_NOT_AVAILABLE return code from your application with an error message in the error log file of AMQ9517 - File damaged, see Migration and client channel definition tables (CCDT).