Connecting a WebSphere MQ MQI client to a queue manager, using the MQSERVER environment variable

When an IBM® WebSphere® MQ application is run on the IBM WebSphere MQ MQI client, it requires the name of the MQI channel, the communication type, and the address of the server to be used. Provide these parameters by defining the MQSERVER environment variable.

Before you begin

Before you start this task, you must complete the task, Setting up the server using the command line, and save the following information:
  • The hostname or IP address of the server and port number that you specified when creating the listener.
  • The channel name of the server-connection channel.

About this task

This task describes how to connect a IBM WebSphere MQ MQI client, by defining the MQSERVER environment variable on the client.

If you are using Windows, HP Integrity NonStop Server, UNIX or Linux systems, you can give the client access to the generated client channel definition table, instead; see Accessing client-connection channel definitions .

Alternatively, on Windows, if Active Directory support is enabled, the client discovers the client-connection information dynamically from the Active Directory.


  1. Check the TCP/IP connection. From the client, enter one of the following commands:
    • ping server-hostname
    • ping n.n.n.n

      n.n.n.n represents the network address. You can set the network address in IPv4 dotted decimal form, for example, Alternatively, set the address in IPv6 hexadecimal form, for example 2001:0DB8:0204:acff:fe97:2c34:fde0:3485.

    If the ping command fails, correct your TCP/IP configuration.
  2. Set the MQSERVER environment variable. From the client, enter one of the following commands:
    1. On Windows:
      SET MQSERVER=channelName/TCP/server-address(port)
    2. On UNIX and Linux, and IBM WebSphere MQ client for HP Integrity NonStop Server OSS systems:
      export MQSERVER=channelName/TCP/'server-address(port)'
    3. On IBM WebSphere MQ client for HP Integrity NonStop Server Guardian systems:
      param MQSERVER CHANNEL1/TCP/server-address(port)
    4. On IBM i:
      ADDENVVAR ENVVAR(MQSERVER) VALUE('channelName/TCP/server-address(port)')
    • channelName is the server-connection channel name.
    • server-address is the TCP/IP host name of the server.
    • port is the TCP/IP port number the server is listening on.
    If you do not give a port number, IBM WebSphere MQ uses the one specified in the qm.ini file, or the client configuration file. If no value is specified in these files, IBM WebSphere MQ uses the port number identified in the TCP/IP services file for the service name MQSeries. If an MQSeries entry in the services file does not exist, a default value of 1414 is used. It is important that the port number used by the client and the port number used by the server listener program are the same.

What to do next

Use the sample programs to test communication between the client and server; see Testing communication between a client and a server.

Task Task


Timestamp icon Last updated: Thursday, 28 February 2019 cs11790_