C Client

The IBM MQ C client is the foundation most other language bindings build on: direct Message Queue Interface calls that have looked the same to systems programmers since MQSeries days. If you maintain legacy C++ middleware, write Linux daemons beside mainframe flows, or read IBM samples like amqsputc and amqsgetc, you work with MQCONN, MQOPEN, MQPUT, MQGET, and MQCMIT in straight C. Every buffer length, structure version field, and reason code comes back to your code explicitly—no JMS wrapper to absorb details. That control helps performance tuning and hurts beginners who omit MQCNO version or forget to zero structures before use. This tutorial walks through client connection with MQCONNX, object and message descriptors, put and get loops, syncpoint, CCDT and MQSERVER environment usage, linking libmqm on Linux and Windows, and mapping reason codes to operations actions when integrating with enterprise queue managers.

Connect with MQCONNX

MQCONN is the simpler connect for basic scenarios; MQCONNX accepts MQCNO for reconnect and security extensions. Supply queue manager name, channel definition or client connection info, and connection options. Reason code 2035 appears on open or put when authority fails—not always on connect. Reason 2538 indicates host unavailable—check CONNAME path. After successful connect, Hconn handle identifies the connection in subsequent calls. MQDISC releases resources—long-running daemons must not leak connections during reload signals.

1
2
3
4
5
6
7
8
9
10
#include 
MQHCONN  Hcon;
MQCD     ClientConn = {MQCD_CLIENT_CONN_DEFAULT};
MQCNO    Cno = {MQCNO_DEFAULT};
strcpy(ClientConn.ChannelName, "ORDERS.API");
strcpy(ClientConn.ConnectionName, "mq-prod.corp(1414)");
Cno.ClientConnPtr = &ClientConn;
Cno.Version = MQCNO_VERSION_4;
MQCONNX("QM_PROD", &Cno, &Hcon, &CompCode, &Reason);
/* Check CompCode and Reason before MQOPEN */

Structures must use correct Version constants—MQCNO_VERSION_4 enables fields your headers define. ClientConnPtr points to MQCD with channel and connection name matching server SVRCONN. Alternatively set MQCHLLIB and MQCHLTAB and pass channel name only. Zero CompCode with MQCC_OK means success; otherwise log Reason and consult MQRC table in product documentation.

Open Put Get Close

MQOPEN with MQOD pointing at QLOCAL name returns Hobj. MQPUT supplies MQMD and MQPMO—set Persistence MQPER_PERSISTENT for durable messages. MQGET uses MQGMO with WaitInterval for blocking consumers. MQCLOSE releases the object. In syncpoint mode, MQCMIT commits puts and gets in the unit of work; MQBACK rolls back. Non-syncpoint puts commit individually per queue manager policy. Match server DEFPSIST and message persistence or messages may not survive restarts as expected.

Sample Put Flow

1
2
3
4
5
6
7
8
MQOD     od = {MQOD_DEFAULT};
MQMD     md = {MQMD_DEFAULT};
MQPMO    pmo = {MQPMO_DEFAULT};
memcpy(od.ObjectName, "PAY.IN", 6);
MQOPEN(Hcon, &od, MQOO_OUTPUT, &Hobj, &CompCode, &Reason);
md.Persistence = MQPER_PERSISTENT;
MQPUT(Hcon, Hobj, &md, &pmo, buflen, buffer, &CompCode, &Reason);
MQCLOSE(Hcon, &Hobj, MQCO_NONE, &CompCode, &Reason);

Building and Linking

• Include cmqc.h from client inc directory.
• Link -lmqm or platform equivalent client library.
• Ensure LD_LIBRARY_PATH or PATH includes native client lib.
• Match 64-bit app to 64-bit client libraries.
• Container: copy client from IBM install into image.

CCDT MQSERVER and Tracing

Operations set MQSERVER for quick tests; production uses CCDT via MQCHLLIB. Client trace STRMQTRC on some platforms helps support—enable only in controlled windows. Correlate client trace timestamps with server AMQERR when connects fail mysteriously.

COBOL and C on Mainframe

z/OS applications often call MQ from COBOL or Assembler with different copybooks but same queue manager when bindings. Distributed C clients talking to z/OS queue managers still use SVRCONN and TLS—firewall between LPAR and distributed network must allow it. Character set conversion may apply for EBCDIC payloads—plan for CCSID fields in MQMD.

Troubleshooting Reason Codes

1. Log CompCode and Reason on every failed call.
2. 2035 after connect—AUTHREC MCAUSER from CHSTATUS.
3. 2085 unknown object—queue name typo.
4. 2009 connection broken—network or QM restart.
5. Structure version mismatch—upgrade headers with client.

Explainer: Direct Dial to MQ

C MQI is dialing the queue manager directly without a receptionist—every digit (structure field) must be correct.

Explain Like I'm Five: C Client

The C client is talking to MQ using the exact words the queue manager understands, not through a translator app.

Practice Exercises

Exercise 1

Write MQCONNX with MQCD for channel PAY.API to paymq(1414).

Exercise 2

Explain MQMD fields needed for request-reply correlation.

Exercise 3

Map reason 2035 and 2538 to server-side checks.

Frequently Asked Questions

Test Your Knowledge