FAQ: How and when are EXCI pipes de-allocated by the CICS Transaction Gateway?

Resolving The Problem

In the customer scenario, the Gateway daemon listening on port 2007 is reserved for an application which should connect to two CICS applications, AP04CC17 and AP40CC43. AP04CC17 has 40 EXCI sessions defined, AP40CC43 has 20 EXCI-sessions defined. From time to time all the possible 100 pipes are allocated and the application fails and the Gateway daemon has to be restarted. This problem occurred at least once a day.

This raises several questions:

Q1. How/where can I have an overview what pipes are in use or what pipes are free?

A. CICS Transaction Gateway v7 allows monitoring of this information, on a per server basis, using the statistics API. CICS Transaction Gateway v6 logs messages when 90% and 100% of pipes are in use, and what the defined EXCI pipe limit is.

Q2. When are the pipes de-allocated?

A. Pipes are de-allocated in 3 scenarios:

a) At Gateway daemon termination.

b) When the CICS TG is using the 'one pipe per thread' allocation model and a Gateway worker thread tries to allocate a new pipe to a different CICS region.

c)When a pipe has been closed due to an unexpected condition occurring, for example, a CICS region terminating.

Q3. What happens with the CICS TG EXCI pipes if one of the CICS regions is stopped?

A. If a CICS region is stopped, the session on the pipes will be broken, and on next usage by the CICS TG they will be closed.

Q4. How does CICS TG pipe allocation work?

A. CICS TG v6 and above has two pipe allocation model, 'reuse all' and 'reuse one per thread'. CICS TG prior to v6 only used the 'reuse all' model, and this is the default.

The 'reuse all' model allows a single worker thread to have a pipe allocated to every CICS region it sends a request to. This means if a single worker makes requests to 3 CICS region, it will have 3 pipes allocated to it. The practical effect of this is that unless you tune the number of worker threads correctly for the number of CICS regions the CICS TG will talk to, you may see ECI_ERR_RESOURCE_SHORTAGE (-16) error codes. This is best explained by an example:

If for instance their are 30 potential CICS regions and 20 worker threads in each Gateway, then each worker thread can potentially connect to 30 CICS regions, taking up 30 pipes. So, multiply this by the number of worker threads, 20, and this means that the Gateway can potentially try to allocate 20x30=600 pipes, which is much higher than the default 100 pipe limit in CICS TS v1.3. There are 3 ways around this situation:

a. Reduce the number of CICS TG worker threads such that (worker threads)x(max CICS regions) <= EXCI pipe limit. The default limit being 100

b. Reduce the number of CICS regions that a single Gateway daemon can connect to such that (worker threads)x(max CICS regions) <= EXCI pipe limit

c. Increase the EXCI pipe limit if you are using CICS TS v2.2 or higher, by applying APAR PQ92943, which allows the limit to be increased to 250.

d. Use the new pipe allocation model of one pipe per thread. See below.

The 'reuse one per thread' model simplifies the calculation by allowing a worker thread to de-allocate an existing pipe and allocating a new one to a new CICS region dynamically as required, meaning that you do not have to tune the number of worker threads based on the number of CICS regions. This buys the ability to have more concurrent requests in CICS, at the cost of a slight impact to performance.