Creating a client-connection channel on the IBM MQ MQI client using MQSERVER

You can define a client-connection channel on a client workstation by using the MQSERVER environment variable.

About this task

You can use the MQSERVER environment variable to specify a simple definition of a client-connection channel. It is simple in the sense that you can specify only a few attributes of the channel using this method.

If you use the MQSERVER environment variable to define the channel between your IBM® MQ MQI client machine and a server machine, this is the only channel available to your application, and no reference is made to the client channel definition table (CCDT).

If the MQCONN or MQCONNX request specifies a queue manager other than the one the listener is connected to, or if the MQSERVER parameter TransportType is not recognized, the MQCONN or MQCONNX request fails with return code MQRC_Q_MGR_NAME_ERROR.

On UNIX and Linux®, you might define MQSERVER as in one of the following examples:


export MQSERVER=CHANNEL1/TCP/'9.20.4.56(2002)'
export MQSERVER=CHANNEL1/LU62/BOX99

All MQCONN or MQCONNX requests then attempt to use the channel you have defined unless an MQCD structure has been referenced from the MQCNO structure supplied to MQCONNX, in which case the channel specified by the MQCD structure takes priority over any specified by the MQSERVER environment variable.

The MQSERVER environment variable takes priority over any client channel definition pointed to by the MQCHLLIB and MQCHLTAB environment variables.

Procedure

Depending on your platform, use one of the following commands to specify the channel definition with MQSERVER.
- On Windows, specify a simple channel definition as follows:
```
SET MQSERVER=ChannelName/TransportType/ConnectionName
```
  For example:
```
export  MQSERVER='SYSTEM.DEF.SVRCONN/TCP/AMACHINE.ACOMPANY.COM(1414)' 
```
- On UNIX and Linux, specify a simple channel definition as follows:
```
export MQSERVER=ChannelName/TransportType/ConnectionName
```
  For example:
```
SET  MQSERVER=SYSTEM.DEF.SVRCONN/TCP/AMACHINE.ACOMPANY.COM(1414) 
```
- On IBM i, specify a simple channel definition as follows:
```
ADDENVVAR ENVVAR(MQSERVER) VALUE('ChannelName/TransportType/ConnectionName')
```
  For example:
```
ADDENVVAR ENVVAR(MQSERVER) VALUE('SYSTEM.DEF.SVRCONN/TCP/AMACHINE.ACOMPANY.COM(1414)')
```
Notes:
- The ChannelName must be the same name as defined on the server. It cannot contain the forward slash (/) character because this character is used to separate the channel name, transport type, and connection name. When the MQSERVER environment variable is used to define a client channel, a maximum message length (MAXMSGL) of 100 MB is used. Therefore the maximum message size in effect for the channel is the value specified in the SVRCONN channel at the server.
- The TransportType can be one of LU62, TCP, NETBIOS, SPX, depending on your IBM MQ client platform.
- On UNIX and Linux, the TransportType is case-sensitive and must be uppercase. An MQCONN or MQCONNX call returns 2058 if the transport type is not recognized
- The ConnectionName is the name of the server as defined to the communications protocol (TransportType). It must be a fully-qualified network name, for example AMACHINE.ACOMPANY.COM(1414).
- The ConnectionName can be a comma-separated list of connection names. The connection names in the list are used in a similar way to multiple connections in a client connection table. The connection name list might be used as an alternative to queue manager groups to specify multiple connections for the client to try. If you are configuring a multi-instance queue manager, you might use a connection name list to specify different queue manager instances.
To cancel MQSERVER and return to the client channel definition table pointed to by MQCHLLIB and MQCHLTAB, enter the following command:
- On UNIX and Linux:
```
unset MQSERVER
```
- On Windows:
```
SET MQSERVER=
```

Example

MQI client connected to QM1 on server, using MQI channel CHAN1. Channel has client-connection at client end, server-connection at server. — Figure 1. Example of a simple channel definition

To create the simple channel definition shown in Figure 1, use the following commands:

On UNIX and Linux:


export MQSERVER=CHANNEL1/TCP/'MCID66499'

On Windows:
```
SET MQSERVER=CHANNEL1/TCP/MCID66499
```

Note: For information on how to change the TCP/IP port number, see TCP/IP default port.

Some more examples of simple channel definitions are as follows:

On Windows:


SET MQSERVER=CHANNEL1/TCP/9.20.4.56
SET MQSERVER=CHANNEL1/NETBIOS/BOX643

On UNIX and Linux:


export MQSERVER=CHANNEL1/TCP/'9.20.4.56'
export MQSERVER=CHANNEL1/LU62/BOX99

where BOX99 is the LU 6.2 ConnectionName.

On IBM i:


ADDENVVAR ENVVAR(MQSERVER) VALUE('CHANNEL1/TCP/9.20.4.56(1416)')

On the IBM MQ MQI client, all MQCONN or MQCONNX requests then attempt to use the channel you have defined, unless the channel is overridden in an MQCD structure referenced from the MQCNO structure supplied to MQCONNX.