Why do I keep getting CCL9126E when my applications try to connect to CICS Transaction Gateway?

When application processes are started and attempts to connect to CICS TG an IPC message queue is created to allow communication with CICS TG's Client daemon process which then sends the requests to CICS. The key used to create the message queue is created based on the application process ID (PID) and a fixed value unique to CICS TG.

When we see CCL9126E it tells us there is a conflict with an existing message queue which prevents the customer application from communicating with our client daemon. Very often it was a previous instance of an application that left this message queue. Unfortunately, CICS TG can not be sure of this so can not use this queue as it is possible another process owns the queue and may update or remove the queue, which would create havoc for CICS TG.

Whatever the cause, when this occurs, the application is unable to connect to CICS TG and ends.

The cause of this problem is due to applications that are not shut down cleanly, either through an application that dies unexpectedly or is killed using something like a kill -9 command. When this occurs CICS TG is unable to run through its cleanup processes, which leaves message queues stranded on the system. Any future CICS TG application that is assigned the same PID -- something we see more frequently than might be expected -- will then encounter the message queue.

Unfortunately, this problem can not be resolved by simply restarting CICS TG or its CICS client daemon. The queue will remain even after CICS TG is restarted and will continue to block communication whenever the message queue key ID is assigned.
For that reason we recommend that care be taken when closing client applications and/or the CICS client daemon. A kill -9 should only be used as a last resort. Instead, a kill -2 should be attempted against the PID, which allows for message queue clean up.

CTGCLEAN

To address this issue we created a tool, ctgclean, that attempts to locate and remove stranded message queues. CICS TG maintains an internal list of processes that have sent it requests. The ctgclean utility cross-references that list to determine which queues it can safely remove. Ctgclean will then attempt to destroy those queues. Therefore, if ctgclean is run while CICS TG is still running -- while that list still exists -- it will be more effective.

However, the tool may not be able to tie queues to our processes, such as in cases where our client daemon itself has either ended or been recycled. When this happens the list of processes may not be available to connect to CICS TG, reducing the number of queues that it can remove.

There are cases where a queue becomes locked and won't respond to a request for its removal. In that case there is a destructive mode to ctgclean that can be enabled to use more forceful means for queue removal. If run while the CICS client daemon is running, however, the command will result in the end of the client daemon, so should only be used as a last resort. The readme file that accompanies CR01 explains how to enable destructive mode.

Ctgclean can be run in non-destructive mode at any time and should have no effect on our client daemon. Some customers have been known to set up a cron job to run the utility at regular intervals to prevent possible queue conflicts.

Ctgclean is is part of SupportPac CR01.