Defining a TCP connection

The channel definition at the sending end specifies the address of the target. A listener program must be run at the receiving end.

Sending end

Specify the host name, or the TCP address of the target machine, in the Connection name field of the channel definition. The port to connect to will default to 1414. Port number 1414 is assigned by the Internet Assigned Numbers Authority to WebSphere MQ.

To use a port number other than the default, change the connection name field thus:

Connection Name OS2ROG3(1822)

where 1822 is the port required. (This must be the port that the listener at the receiving end is listening on.)

You can change the default port number by specifying it in the queue manager configuration file (qm.ini) for MQSeries for OS/2 Warp and the registry for WebSphere MQ for Windows:

TCP:
  Port=1822

Note:

To select which TCP/IP port number to use, WebSphere MQ uses the first port number it finds in the following sequence:

1. The port number explicitly specified in the channel definition or command line. This number allows the default port number to be overriden for a channel.
2. The port attribute specified in the TCP stanza in the qm.ini file. This number allows the default port number to be overriden for a queue manager.
3. The value specified for 'MQSeries' in the '/etc/services' file. This number allows the default port number to be overriden for a machine.
4. The default value of 1414. This is the number assigned to WebSphere MQ by the Internet Assigned Numbers Authority.

For more information about the values you set using qm.ini, see Appendix C, Configuration file stanzas for distributed queuing.

Receiving on TCP

Receiving channel programs are started in response to a startup request from the sending channel. To do this, a listener program has to be started to detect incoming network requests and start the associated channel.

You should use either the TCP/IP listener (INETD) (not for Windows) or the WebSphere MQ listener.

Using the TCP/IP listener

To use INETD to start channels on OS/2, two files must be configured:

1. Add a line in the TCPIP\ETC\SERVICES file:

   MQSeries      1414/tcp
   

   where 1414 is the port number required for WebSphere MQ. You can change this but it must match the port number specified at the sending end.

2. Add a line to the TCPIP\ETC\INETD.LST file:

   MQSeries      tcp C:\MQM\BIN\AMQCRSTA [-m QMName]
   

   The last part in square brackets is optional and is not required for the default queue manager. If your MQSeries for OS/2 Warp is installed on a different drive, replace the C: above with the correct drive letter.

It is possible to have more than one queue manager on the machine. You must add a line to each of the two files, as above, for each of the queue managers. For example:

MQSeries2     1822/tcp

Now stop, and then start the inetd program, before continuing.

Using the TCP listener backlog option

When receiving on TCP, a maximum number of outstanding connection requests is set. This can be considered a backlog of requests waiting on the TCP port for the listener to accept the request. The default listener backlog values are shown in Table 12.

Table 12. Default outstanding connection requests on OS/2 and Windows

If the backlog reaches the values shown in Table 12, the TCP/IP connection is rejected and the channel will not be able to start.

For MCA channels, this results in the channel going into a RETRY state and retrying the connection at a later time.

For client connections, the client receives an MQRC_Q_MGR_NOT_AVAILABLE reason code from MQCONN and should retry the connection at a later time.

However, to avoid this error, you can add an entry in the qm.ini file or in the registry for Windows:

TCP:
ListenerBacklog = n

This overrides the default maximum number of outstanding requests (see Table 12) for the TCP/IP listener.

Note:

Some operating systems support a larger value than the default. If necessary, this can be used to avoid reaching the connection limit.

To run the listener with the backlog option switched on, use the RUNMQLSR -b command. For information about the RUNMQLSR command, see the WebSphere MQ System Administration Guide book.

Using the WebSphere MQ listener

To run the Listener supplied with WebSphere MQ, that starts new channels as threads, use the RUNMQLSR command. For example:

RUNMQLSR -t tcp [-m QMNAME] [-p 1822]

The square brackets indicate optional parameters; QMNAME is not required for the default queue manager, and the port number is not required if you are using the default (1414).

For the best performance, run the WebSphere MQ listener as a trusted application as described in Running channels and listeners as trusted applications. See the WebSphere MQ Application Programming Guide for information about trusted applications.

You can stop all WebSphere MQ listeners running on a queue manager that is inactive, using the command:

ENDMQLSR [-m QMNAME]

If you do not specify a queue manager name, the default queue manager is assumed.

Using the TCP/IP SO_KEEPALIVE option

If you want to use the SO_KEEPALIVE option (as discussed in Checking that the other end of the channel is still available) you need to add the following entry to your queue manager configuration file (qm.ini):

TCP:
   KeepAlive=yes

If you are using OS/2, you must then issue the following command:

  inetcfg  keepalive=value

where value is the time interval in minutes.

On Windows, the TCP configuration registry value for KeepAliveTime controls the interval that elapses before the connection will be checked. The default is two hours. For information about changing this value, see the Microsoft article TCP/IP and NBT Configuration Parameters for Windows NT 3.5 (PSS ID number Q120642).