MQCONN

MQCONN is the front door of the Message Queue Interface: before your application can MQOPEN a queue, MQPUT a payment, or MQGET a work item, it must obtain a connection handle (Hconn) to a queue manager. Think of Hconn as your session ticket—the queue manager uses it to identify which application instance is calling, apply security checks, and associate subsequent opens and puts with your process. MQCONN takes a queue manager name string; MQCONNX extends the same idea with an MQCD structure describing TCP host, port, channel name, SSL parameters, and optional user identification for client connections over SVRCONN. Beginners see connect failures more than any other MQI error because networking, channel names, and authority must align before a single message flows. This tutorial walks through bindings versus client connect, connection options, common reason codes, multi-threading patterns, pairing with MQDISC, and how language bindings like JMS ConnectionFactory or pymqi QueueManager.connect map to these C calls underneath.

Bindings Mode: MQCONN on the Same Host

When the application runs on the same operating system image as the queue manager and uses server bindings, MQCONN with name QM1 attaches through shared memory without traversing a TCP listener. This is the fastest path and common for batch on Linux or user programs colocated with the broker VM. The queue manager name must match the active instance (dspmq -m QM1). Wrong name yields 2059. The user ID of the process is checked against OAM or RACF for connect permission—2035 means the OS user cannot use this queue manager at all.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
#include 
 
MQLONG compCode, reason;
MQHCONN Hconn;
 
MQCONN("QM1",                 /* queue manager name */
       &Hconn,                /* connection handle returned */
       &compCode,
       &reason);
 
if (compCode != MQCC_OK) {
  /* reason 2035 = not authorized, 2059 = QM not available */
  printf("MQCONN failed reason %ld\n", reason);
  return 1;
}
/* use Hconn on MQOPEN, MQPUT, MQGET ... */

Client Mode: MQCONNX with MQCD

Distributed and cloud applications connect remotely. MQCONNX accepts ConnOpts pointing to MQCD filled with ChannelName, ConnectionName (host(port)), and optional SSL fields. The client library reads CCDT from MQCHLLIB if you omit details in code. The channel name must exist as SVRCONN on the server with compatible TRPTYPE and TLS settings. MCAUSER on the channel may adopt the message authority for the session. Heartbeat and reconnect behavior are client properties configured outside this single call but depend on a successful initial MQCONNX.

1
2
3
4
5
6
7
MQCD cd = {MQCD_CLIENT_CONN_DEFAULT};
MQCNO cno = {MQCNO_DEFAULT};
strncpy(cd.ChannelName, "PAYMENTS.APP", MQ_CHANNEL_NAME_LENGTH);
strncpy(cd.ConnectionName, "mq-prod.corp(1414)", MQ_CONN_NAME_LENGTH);
cno.ClientConnPtr = &cd;
 
MQCONNX("QM_PROD", &cno, &Hconn, &compCode, &reason);

Connection Options (MQCNO)

ConnOpts (MQCNO) control client behavior. Options include sharing conversations, blocking login, and specifying an MQSCO security structure for certificate labels. Compare MQCNO_HANDLE_SHARE_BLOCK versus default for whether multiple threads may share one Hconn—IBM documents thread safety rules per language binding. Setting UserIdentifier and Password in MQCD supports basic authentication where CONNAUTH allows it; prefer TLS client certificates in modern estates. ApplicationName in MQCD helps operators correlate DISPLAY CONN on the queue manager with a specific microservice pod name.

Explainer: Signing In at the Building Lobby

MQCONN is signing in at the IBM MQ building lobby. You show ID (OS user or certificate). Security checks the guest list (authority). If approved, you receive a badge (Hconn) that every elevator (MQOPEN) and mailroom (MQPUT) will scan until you return the badge at MQDISC.

What Happens Inside the Queue Manager

On connect, the queue manager creates an internal connection object tracking your process or remote channel instance. DISPLAY CONN(*) TYPE(*) ALL shows active connections. Quiesce shutdown (endmqm -w) stops new MQCONN while existing ones drain. Long-running apps that never MQDISC block maintenance windows—batch jobs should disconnect in finally blocks. Client reconnect after network blip may re-establish TCP transparently in some client configurations, but application code should still handle MQRC_CONNECTION_BROKEN on subsequent MQI calls.

z/OS and CICS Considerations

On z/OS, the connecting user is the TSO region or CICS task user unless overridden. RACF profiles in MQCONN class govern connect. CICS MQCONN calls may use the adapter; still the same logical Hconn concept for application design. Distinguish connect authority from put authority on individual queues—passing MQCONN does not mean MQPUT to PAYMENTS.IN is allowed.

Language Bindings

• C — MQCONN / MQCONNX as shown.
• Java JMS — ConnectionFactory.createConnection maps to client connect.
• COBOL — CALL MQCONN using linkage section Hconn.
• pymqi — QueueManager.connect wraps MQCONNX parameters.
• .NET — MQQueueManager constructor with properties bag.

Higher-level APIs still require correct queue manager name and channel metadata somewhere in configuration—environment variables MQSERVER, MQCHLLIB, or Kubernetes secrets.

Threading and Performance

Opening one Hconn per process and sharing across worker threads reduces handshake overhead but demands correct locking per IBM thread guidance for your language. Alternatively each thread MQCONNects—simpler code, more server resources. Load tests measure which fits your container replica count. Connection pooling in Java app servers amortizes MQCONNX cost across many short JMS sessions.

Troubleshooting Connect Failures

1. Verify queue manager Running with dspmq.
2. Client: ping host, telnet port, DISPLAY LSSTATUS on server.
3. Channel name matches SVRCONN definition exactly.
4. CHLAUTH and CONNAUTH logs on failed attempt.
5. Bindings: app user in mqm group or granted connect via setmqaut.
6. Certificate expiry on TLS channels.

Explain Like I'm Five: MQCONN

MQCONN is telling the mail building who you are so they give you a visitor badge before you can send or pick up letters.

Practice Exercises

Exercise 1

Trace a 2059 from a Java client: list five checks in order.

Exercise 2

Explain when you choose MQCONN over MQCONNX in a new microservice on the same VM as the QM.

Exercise 3

Find DISPLAY CONN output after a test connect and identify your application name field.

Frequently Asked Questions

Test Your Knowledge