MQCHLLIB

MQCHLLIB answers one question for every IBM MQ client process: which folder on this machine holds the client channel definition table? Without a correct directory, AMQCLCHL.TAB may as well not exist—the library never opens it, and MQCONNX hunts for channel metadata that is not in memory. Operations teams set MQCHLLIB in systemd units, Kubernetes env blocks, WebSphere Liberty server.env files, and mainframe USS export files; developers often forget it in IDE run configurations and spend hours debugging SVRCONN that was perfect on the server. This tutorial explains MQCHLLIB in relation to MQCHLTAB, default paths on distributed platforms, permissions and read-only mounts, containers and immutable images, how MQCHLLIB differs from MQSERVER and from queue manager directories, and troubleshooting when the file is present on disk but the application acts as if it is missing.

Directory Versus Filename

IBM MQ splits location into two variables by design. MQCHLLIB is only the directory path—no trailing filename. MQCHLTAB is only the filename—default AMQCLCHL.TAB. The client concatenates them according to platform path rules. This split lets you swap table filenames during blue-green tests while keeping the same directory mount, or point different applications at different files in one shared folder by varying only MQCHLTAB. Both variables must be visible to the process environment before the first MQ client call in that process.

Setting MQCHLLIB Correctly

1
2
3
4
5
6
7
8
9
mkdir -p /var/mqm/ccdt
cp AMQCLCHL.TAB /var/mqm/ccdt/
chmod 440 /var/mqm/ccdt/AMQCLCHL.TAB
chown appuser:mqclient /var/mqm/ccdt/AMQCLCHL.TAB
export MQCHLLIB=/var/mqm/ccdt
export MQCHLTAB=AMQCLCHL.TAB
# Verify from app user:
ls -l $MQCHLLIB/$MQCHLTAB
su - appuser -c 'echo MQCHLLIB=$MQCHLLIB'

The application runtime user must have read permission on the directory and file. World-writable CCDT directories are a security risk—attackers could redirect your applications to a hostile queue manager. Prefer read-only mounts in containers after the image is built. When multiple versions of the table exist, use versioned filenames and update MQCHLTAB rather than overwriting in place while processes hold old file handles—some platforms cache open files.

Containers and Orchestration

Mount a volume or ConfigMap into a fixed path and set MQCHLLIB to that mount point. Init containers can copy the latest CCDT from a secret store before the main container starts. Remember that changing a mounted ConfigMap does not always propagate to running pods without restart—plan rolling updates. Sidecar pattern alternatives push connection data through client.json instead of binary TAB files; MQCHLLIB may be unset in those designs—know which pattern your chart uses.

MQCHLLIB Versus Queue Manager Paths

Queue manager data lives under paths like /var/mqm/qmgrs/QM1 on Linux—that is server infrastructure. MQCHLLIB on an application pod points at client metadata only. Never point MQCHLLIB at the queue manager qmgrs directory hoping to read SVRCONN—the formats and tools differ. Server definitions are managed with runmqsc on the queue manager; client tables are exported CLNTCONN subsets.

Interaction With MQSERVER

When both are set, client precedence depends on connect options and release—do not assume MQSERVER wins. For isolation tests, unset MQCHLLIB temporarily and use MQSERVER only to prove server reachability, then restore CCDT testing. Document production standard: CCDT via MQCHLLIB for all JVMs, MQSERVER forbidden in prod to reduce drift.

Troubleshooting

1. From application user, test file readable: ls MQCHLLIB/MQCHLTAB.
2. Print env inside process—not only parent shell.
3. Check for trailing spaces in path strings in unit files.
4. Verify SELinux or AppArmor not blocking read.
5. Confirm deployment pipeline updated directory not only server MQSC.

Explainer: Folder for the Phone Book

MQCHLLIB is which drawer holds the phone book. MQCHLTAB is which book in the drawer. You need both to find the number.

Explain Like I'm Five: MQCHLLIB

MQCHLLIB tells your app which folder to look in to find the paper that says how to call MQ.

Practice Exercises

Exercise 1

Write systemd Environment lines for MQCHLLIB and MQCHLTAB with correct syntax.

Exercise 2

List permission bits for CCDT directory and file for user mqapp.

Exercise 3

Explain why pointing MQCHLLIB at a qmgrs subdirectory fails.

Frequently Asked Questions

Test Your Knowledge