The most obvious place to check which TCP ports your WebSphere MQ channel listeners are configured to use is:

DISPLAY LISTENER(*) PORT in runmqsc.

But that’s not the only place to check. It’s easy to miss one of the places, so in this post, I’ll quickly outline the different factors that affect the TCP port that a channel listener will use.

  • PORT attribute of the channel listener
    The most obvious place, but the easiest one to start with. An explicit PORT attribute in a channel listener definition overrides anything else. This is the port that the listener will use.

    If this is set to 0, then the next place to check is:

  • Port setting in the qm.ini file or Windows Registry
    On Windows, this can be found in system Registry at:
    HKEY_LOCAL_MACHINE\SOFTWARE\IBM\MQSeries\CurrentVersion\
    Configuration\QueueManager\QMGRNAME\TCP\Port

    On UNIX, it will be found in the TCP stanza of the queue manager’s qm.ini file /var/mqm/qmgrs/QMGRNAME/qm.ini:

    TCP: 
  Port = 9999

    TCP page in the Queue Manager properties pageIf you are using WebSphere MQ Explorer, the value can be found in the Queue Manager Properties dialog on the TCP page.

    Just right-click on the queue manager and click on ‘Properties’, then click on TCP.

    This is the default port number for the queue manager, and the value here will be used for any channel listeners with a PORT value of 0.

    If this value is not set (in Windows, if the registry key is not present or in UNIX if the Port attribute is not included in the qm.ini file), then the value that will be used is:

  • mqseries entry in etc/services
    On Windows, this can be found at: 

    C:\\WINDOWS\\system32\\drivers\\etc\\services

    On UNIX, this can be found at:

    /etc/services

    If an mqseries entry is contained in this file:

    mqseries 12345/tcp # mqseries default port number

    then this port number is used for channel listeners with a PORT attribute of 0 on queue managers without a default port number in the Registry (or qm.ini).

    If an mqseries entry is not included in the etc/services file, then the value that is used is:

  • 1414
    The default for WebSphere MQ channel listeners. In the absence of the above settings, we use port 1414.

.

That’s not quite the whole story, though. There are a few quirks that it’s also worth being aware of:

WebSphere MQ Explorer users

The first time you look at the Queue Manager’s default Port value with WMQ Explorer, it shows ‘1414’. But as implied above, new queue managers do not actually have a TCP port setting. This is just showing you the effective port value because of the WebSphere MQ default. (This can be verified in regedit by looking in the Registry – this key won’t exist until the first time you alter the queue manager’s TCP Port setting in WMQ Explorer.) Once altered in WebSphere MQ Explorer, the value is considered to be explicitly set – even if you set it back to 1414 after changing it, you will notice that the registry key remains.

So, “1414” in the WMQ Explorer can either mean 1414 has been set, or that there is nothing set and WebSphere MQ is defaulting to 1414.

SYSTEM.DEFAULT.LISTENER.TCP

A channel listener “SYSTEM.DEFAULT.LISTENER.TCP” is created when a queue manager is created. This is created by WMQ (whether the queue manager is created by WMQ Explorer, or at the command line). It does not specify a port number, and so would use the queue manager’s default port number setting if started.

However, it is not a listener which I would expect to see people using – it is created for use by the queue manager. Most importantly, it serves as a template for the creation of new listener objects. Notice, for example, that if you delete this object, you are therefore unable to create new channel listener objects as there is nothing to use as a template. As an important system object, this is best left alone and essentially ignored for WMQ’s own internal use.

Creating queue managers with WebSphere MQ Explorer

Create Queue Manager wizard of the WebSphere MQ ExplorerA channel listener may be created by the WMQ Explorer ‘Create Queue Manager’ wizard. Step 4 (‘Enter listener options’) of the ‘Create Queue Manager’ wizard specifies the creation of a channel listener with an explicit port number specified. The listener which it will create is named LISTENER.TCP.

By default, the option to do this is enabled. (Note that this is an optional feature of the WMQ Explorer wizard and is not done if creating queue managers at the command line.)

This is not setting the default port number for the queue manager. It is just specifying the port number to use for a single channel listener. As this is a channel listener with it’s own port number explicitly provided, it is not affected by the queue manager’s default port number setting.

Only one listener on a port at a time

Finally, only one listener can use a port number on a single machine at any one time. Although multiple listeners can be defined to use the same port number, only one can be running at any one time. Any attempts to start a second listener on a port number already in use (whether by an automatically or manually defined listener) will fail – and that second listener’s status will remain ‘Stopped’.
.

.
Update: I should have pointed out that a discussion about channel listener objects is only relevant for WebSphere MQ version 6 and above.

However, where I talk about channel listener object definitions, the same is true for channel listener processes started manually using runmqlsr:

  • runmqlsr commands started with an explicit port number (using -p) are equivalent to setting the PORT attribute of a channel listener object
  • runmqlsr commands started without an explicit port number (omitting -p) are equivalent to channel listener objects with a PORT attribute of 0

Update 2: Inserted bullet-point section about etc/services as suggested by Russell below.