MQCHLTAB

MQCHLTAB names the file—not the folder—that IBM MQ clients open when they need CLNTCONN definitions from a binary client channel definition table. Operations folklore treats AMQCLCHL.TAB as immovable, but MQCHLTAB exists precisely so you can version, swap, and test tables without relocating the entire directory mount. A canary deployment might mount /var/mqm/ccdt unchanged while only MQCHLTAB shifts from AMQCLCHL.TAB to AMQCLCHL.CANARY.TAB for selected pods. Disaster recovery runbooks copy AMQCLCHL.DR.TAB into place and flip MQCHLTAB during the cutover window. Beginners set MQCHLLIB correctly yet leave MQCHLTAB unset assuming a default that differs on Windows versus Linux, or deploy a new file name without updating the variable so production still reads yesterday's table inode. This tutorial explains MQCHLTAB behavior, pairing with MQCHLLIB, multi-table strategies, change management, and troubleshooting filename mismatches.

Default and Custom Filenames

When MQCHLTAB is unset, IBM MQ client libraries fall back to platform-documented defaults—commonly AMQCLCHL.TAB. Explicitly setting MQCHLTAB in all environments removes ambiguity in support calls. Custom names must match the actual file deployed: case sensitivity matters on Linux; Windows may be more forgiving but stay consistent. Do not point MQCHLTAB at a path with slashes—it is filename only; paths belong in MQCHLLIB.

Blue-Green and Canary

1
2
3
4
5
6
7
8
# Same directory, different table files
export MQCHLLIB=/var/mqm/ccdt
# Blue (current prod)
export MQCHLTAB=AMQCLCHL.BLUE.TAB
# Green (new CONNAME target) — switch env in deployment
# export MQCHLTAB=AMQCLCHL.GREEN.TAB
ls -l /var/mqm/ccdt/AMQCLCHL.*.TAB
# Rolling restart apps after MQCHLTAB change

Keep both files in the directory during migration; switch MQCHLTAB per deployment wave. Validate CLNTCONN contents with MQ tools before cutover. Roll back by reverting MQCHLTAB without regenerating MQSC if the blue file was preserved. Document which Kubernetes Deployment sets which MQCHLTAB value in Helm values.yaml comments.

Generating Multiple Tables

Export separate CCDT files from different CLNTCONN sets in runmqsc or Explorer—prod table versus DR table. Name outputs distinctly before copy to MQCHLLIB. Automation should never overwrite AMQCLCHL.TAB in place without backup; versioned filenames plus MQCHLTAB pointer make rollback one environment variable change. Store artifacts in artifact repository with semantic version tags matching application releases.

Relationship to JSON Client Config

Container-native IBM MQ clients may ignore MQCHLTAB when using JSON connection configuration mounted elsewhere. Hybrid estates might use binary TAB on VMs and JSON in Kubernetes—maintain a matrix in operations wiki showing which technology uses which mechanism. Audits fail when teams assume one global standard.

Verification Steps

1. ls $MQCHLLIB/$MQCHLTAB as application user.
2. Compare file checksum after deployment pipeline.
3. Test MQCONNX from jump host with same env.
4. Enable short client trace; confirm table load path in trace.
5. Wrong file symptom: connects to old IP after DNS change—check TAB contents not just DNS.

Common Mistakes

• MQCHLTAB set but file not deployed to MQCHLLIB directory.
• Typo AMQCLCHL.TAB versus AMQCLCHL.tab on case-sensitive FS.
• CI publishes new TAB but runtime still references AMQCLCHL.TAB literal in Helm chart.
• Multiple apps share directory but need different tables—use per-app MQCHLTAB in service unit.

Explainer: Which Book in the Drawer

MQCHLLIB is the drawer. MQCHLTAB is whether you pull the 2024 phone book or the 2026 DR edition from that drawer.

Explain Like I'm Five: MQCHLTAB

MQCHLTAB is the exact name of the paper in the folder so your app opens the right one when there are two papers.

Practice Exercises

Exercise 1

Design blue-green filenames and MQCHLTAB values for a CONNAME change with rollback in one env var.

Exercise 2

Write a checklist verifying MQCHLLIB and MQCHLTAB together before go-live.

Exercise 3

Explain symptom when MQCHLTAB points to UAT file in production pod spec.

Frequently Asked Questions

Test Your Knowledge