Defining a TCP connection

The channel definition at the sending end specifies the address of the target. The inetd daemon is configured for the connection 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 REMHOST(1822)

where REMHOST is the hostname of the remote machine and 1822 is the port number required. (This must be the port that the listener at the receiving end is listening on.)

Alternatively you can change the port number by specifying it in the queue manager configuration file (qm.ini):

TCP:
  Port=1822

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

Receiving on TCP

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

Using the TCP/IP listener

To start channels on UNIX, the /etc/services file and the inetd.conf file must be edited, following the instructions below:

1. Edit the /etc/services file:

   Note:

   To edit the /etc/services file, you must be logged in as a superuser or root. You can change this, but it must match the port number specified at the sending end.

   Add the following line to the file:

   MQSeries 1414/tcp
   

   where 1414 is the port number required by WebSphere MQ.

2. Add a line in the inetd.conf file to call the program amqcrsta:

   MQSeries stream tcp nowait mqm /mqmtop/bin/amqcrsta amqcrsta
   [-m Queue_Man_Name]
   

The updates are active after inetd has reread the configuration files. To do this, issue the following commands from the root user ID:

• On AIX:

  refresh -s inetd
  

• On other UNIX systems:

  kill -1 <process number>
  

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

MQSeries1     1414/tcp
MQSeries2     1822/tcp

MQSeries2 stream tcp nowait mqm /mqmtop/bin/amqcrsta amqcrsta -m QM2

This avoids error messages being generated if there is a limitation on the number of outstanding connection requests queued at a single TCP port. For information about the number of outstanding connection requests, see Using the TCP listener backlog option.

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 19.

Table 19. Default outstanding connection requests

If the backlog reaches the values shown in Table 19, 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:

TCP:
ListenerBacklog = n

This overrides the default maximum number of outstanding requests (see Table 19) 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, which 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 must the add the following entry to your queue manager configuration file (QM.INI) or the Windows NT registry:

TCP:
   KeepAlive=yes

On some UNIX systems, you can define how long TCP waits before checking that the connection is still available, and how frequently it retries the connection if the first check fails. This is either a kernel tunable parameter, or can be entered at the command line. See the documentation for your UNIX system for more information.

On MQSeries for SINIX and DC/OSx you can set the TCP keepalive parameters by using the idtune and idbuild commands to modify the TCP_KEEPCNT and TCP_KEEPINT values for the kernel configuration. The default configuration is to retry 7 times at 7200 second (2 hourly) intervals.