CCDT

The client channel definition table—CCDT—is how IBM MQ operations teams ship connection instructions to hundreds of applications without recompiling code. Every CLNTCONN row is a recipe: which channel name to request on the server, which host and port to dial, which queue manager name to assert, and optionally which TLS cipher policy applies. When the data center moves a listener behind a new load balancer or fail over DNS to the DR site, you update the CCDT once and redeploy—provided every JVM, container, and batch server actually reads the new file. Beginners confuse CCDT with server-side channel tables, paste AMQCLCHL.TAB into git without understanding binary versus JSON formats, or leave MQCHLLIB unset so applications silently use ancient paths. This tutorial explains what CCDT contains, how it relates to MQCHLLIB and MQCHLTAB, how MQ Explorer and runmqsc generate tables, JSON CCDT for cloud, deployment patterns, security hygiene, and troubleshooting when MQCONNX cannot find the channel in the table.

What Lives Inside a CCDT

Each entry is logically a CLNTCONN channel definition. Fields include CHLTYPE(CLNTCONN), channel name, TRPTYPE(TCP), CONNAME in host(port) form, QMNAME for the target queue manager, and optional SSL attributes matching server SVRCONN policy. The client library matches the channel name your application passes—if the program calls MQCONNX with channel PAYMENTS.APP, a row with that name must exist. Missing rows produce errors referencing unknown channel before TCP even starts. Multiple rows allow one file to serve payments, inventory, and admin tools connecting to different queue managers or ports.

Binary CCDT: AMQCLCHL.TAB

Historically operators run runmqsc against a client definition repository or export from MQ Explorer to produce a binary AMQCLCHL.TAB file. Applications locate it through environment variables MQCHLLIB (directory path) and MQCHLTAB (filename, default AMQCLCHL.TAB). The binary format is not hand-editable—use MQSC or supported tools to regenerate after changes. Copy the file to every application server with consistent permissions; configuration management tools often package the table into RPM, Ansible artifacts, or container layers. Version-stamp the artifact in change tickets so support knows which CONNAME production used during an incident.

Creating and Updating CCDT

1
2
3
4
5
6
7
8
DEFINE CHANNEL('PAYMENTS.APP') CHLTYPE(CLNTCONN) TRPTYPE(TCP) +
  CONNAME('mq-prod.corp.example(1414)') QMNAME('QM_PROD')
DEFINE CHANNEL('PAYMENTS.DR') CHLTYPE(CLNTCONN) TRPTYPE(TCP) +
  CONNAME('mq-dr.corp.example(1414)') QMNAME('QM_PROD')
* Export to CCDT per platform tooling (Explorer, setmqenv, etc.)
* Deploy AMQCLCHL.TAB to /opt/mqm/ccdt on app servers
* export MQCHLLIB=/opt/mqm/ccdt
* export MQCHLTAB=AMQCLCHL.TAB

After DEFINE, use your platform documented export path to materialize the table file. Test from a jump host with the same environment variables as production before wide rollout. For DR, some sites maintain separate channel names PAYMENTS.APP and PAYMENTS.DR; others swap CONNAME in place during failover—pick one strategy and document which applications must restart versus reconnect automatically.

JSON CCDT and Modern Deployments

Container and Kubernetes deployments often mount a JSON client channel definition file referenced in IBM MQ client configuration. The same logical fields appear—channelName, connectionNameList, queueManager—with structure suited to ConfigMaps and secrets managers. TLS certificates mount as separate volumes. The operations principle remains: separate connection metadata from application business logic. GitOps pipelines should lint JSON and run connectivity tests in staging before promoting to production namespaces.

How Applications Select a Row

MQCONNX (or language equivalent) supplies a connection descriptor including channel name and queue manager name. The client loads the CCDT, finds the matching CLNTCONN, and uses its CONNAME for TCP. If both MQSERVER and CCDT are set, precedence rules depend on client version and connect options—avoid conflicting configuration without lab verification. Some frameworks hide channel name inside connection factories—grep configuration repos for SVRCONN names when migrations fail.

Security and Compliance

• Do not store passwords inside CCDT—use CONNAUTH and secret stores.
• Restrict file permissions on AMQCLCHL.TAB to application runtime users only.
• TLS trust stores remain separate from CCDT—update both on cert rotation.
• Audit changes to CCDT with the same rigor as firewall rules.

Troubleshooting CCDT Issues

1. Verify MQCHLLIB directory exists on the application host.
2. Confirm MQCHLTAB filename matches deployed file.
3. Check channel name spelling against table contents.
4. Ensure container image rebuilt after CCDT change—not only ConfigMap updated.
5. DISPLAY CHSTATUS on server—if no TCP arrive, client never left with right CONNAME.
6. Compare file timestamp on server versus expected deployment pipeline ID.

Explainer: Bus Schedule on the Wall

CCDT is the bus schedule posted at the station: everyone reads the same departure times and destinations. When the route changes, you replace the poster—not every passenger's memory individually.

Explain Like I'm Five: CCDT

CCDT is a shared phone book that tells all your apps which number to call to reach the MQ computer.

Practice Exercises

Exercise 1

Design a CCDT with two CLNTCONN rows for prod and DR with the same channel name strategy—justify your choice.

Exercise 2

Write the environment variables an Linux app server needs to pick up /var/mqm/ccdt/AMQCLCHL.TAB.

Exercise 3

List failure symptoms when MQCHLLIB points to an empty directory.

Frequently Asked Questions

Test Your Knowledge