Listeners

LISTENER objects are how you tell IBM MQ which network door to open. Channels reference host and port in CONNAME; clients use the same in CCDT—but something must bind to that port on the server. That is the listener definition and its running process. This page focuses on the administrative object: attributes, starting and stopping, multiple listeners per queue manager, pairing with SVRCONN and RCVR channels, and operations checks. For the runtime process lifecycle, see the listener processes tutorial; together they complete the picture for beginners wiring first remote connections.

DEFINE LISTENER Basics

DEFINE LISTENER(LISTENER.TCP) TRPTYPE(TCP) PORT(1414) creates the object. Optional IPADDR limits binding to one network interface—useful on multi-homed servers. DESCR documents ownership. REPLACE allows idempotent automation scripts. Without START LISTENER, the definition exists but no process listens—remote partners get connection refused or timeout.

Explainer: Pairing with Channels and Clients

On QM2 you DEFINE LISTENER on port 1414 and START it. On QM1 the SDR channel CONNAME('qm2.host(1414)') targets that listener. On QM2 the matching RCVR channel accepts the session. Java clients instead open SVRCONN; the same listener port often serves both message channels and clients unless you segregate ports for security zones. Load balancers in front of multiple queue manager instances must preserve affinity if required by your HA design.

Starting, Stopping, and Status

1. START LISTENER(name)—activates process for definition.
2. STOP LISTENER(name)—graceful stop; check for active channels first.
3. DISPLAY LISTENER(*) ALL—static definition attributes.
4. DISPLAY LSSTATUS(*) ALL—runtime state per listener.

During maintenance, stop listeners before firewall changes to avoid half-open channels, or quiesce channels first per runbook.

Multiple Listeners and Ports

Segregate traffic: LISTENER.CLIENT on 1414 for applications, LISTENER.ADMIN on 1415 for operations tools from a jump host only. Each requires firewall rules and documentation in the connection table. Document which SVRCONN and RCVR channels expect which port to prevent “connection works in TEST but not PROD” when ports differ by environment.

LU62 and Other Transports

TRPTYPE(LU62) and other values appear in SNA or specialty integrations. Most readers use TCP; when you encounter LU62, consult platform-specific IBM MQ networking guides. Conceptually the listener still accepts inbound transport attach requests before channels run.

Tutorial: Listener and Client Channel

1
2
3
4
5
6
7
8
9
10
DEFINE LISTENER('LISTENER.TCP') TRPTYPE(TCP) PORT(1414) +
  CONTROL(QMGR) REPLACE
START LISTENER('LISTENER.TCP')
DISPLAY LSSTATUS('LISTENER.TCP') ALL
 
DEFINE CHANNEL('JAVA.CLIENT') CHLTYPE(SVRCONN) REPLACE
* Client CCDT or MQSERVER points to host:1414 channel JAVA.CLIENT
 
ALTER AUTHREC PROFILE('JAVA.CLIENT') OBJTYPE(CHANNEL) +
  PRINCIPAL('appuser') AUTHADD(CONNECT,INQ,GET,PUT)

Explain Like I'm Five: Listeners

The LISTENER is the sign on the post office door that says “open here on port 1414.” The channel is the rule for what happens after you walk in. No sign (listener stopped), no visitors (connections fail).

Practice Exercises

Exercise 1

CONNAME uses port 1415 but LISTENER uses 1414. What error family appears?

Exercise 2

Design two listeners for PROD DMZ and internal admin—ports and firewall rules.

Exercise 3

Difference between DISPLAY LISTENER and DISPLAY LSSTATUS?

Frequently Asked Questions

Test Your Knowledge