Connection pooling for HTTP client performance

For CICS® as an HTTP client, connection pooling can provide performance benefits where multiple invocations of CICS web support applications, web services applications, or the HTTP EP adapter make connection requests for the same host and port, or where a web services application makes multiple requests and responses.

By default, CICS closes a client HTTP connection after the connection has been used:
  • For CICS web support applications that make HTTP client requests, CICS closes the connection when the application program issues a WEB CLOSE command to notify CICS that it has finished using the connection. If the application does not issue the WEB CLOSE command, CICS closes the connection when end of task is reached.
  • For CICS web services applications that are service requesters, CICS closes the connection after the application program has issued its service request using the INVOKE SERVICE command and received the response if appropriate.
  • For CICS event processing, CICS closes the connection after the HTTP EP adapter has emitted the business event.

When you set up connection pooling, instead of closing the client HTTP connection after use, CICS keeps the connection open and stores it in a pool in a dormant state. The dormant connection can be reused by the same application or by another application that connects to the same host and port. When an application issues a command to open a client HTTP connection, CICS checks whether a dormant connection is available in the pool for that host and port, and if so supplies it to the application rather than opening a new connection.

When a pooled connection is reused, CPU use is reduced compared to opening a new connection. An additional saving occurs where connections use the Secure Sockets Layer (SSL), because the security measures do not need to be repeated when the connection is reused. Applications reuse a pooled connection in exactly the same way as they use a new connection, and the connection can be pooled again after use.

Connection pooling is specified by the SOCKETCLOSE attribute in a URIMAP resource, which defines if, and for how long, CICS keeps a socket open after the CICS application has finished using its client HTTP connection. Applications must specify the URIMAP resource when they open the connection.

The HTTP EP adapter requires a URIMAP resource to open a connection. URIMAP resources are not a requirement for HTTP client requests from CICS web support and web services applications, but they have a number of advantages. In addition to enabling connection pooling, when you use URIMAP resources for client connections, system administrators can manage any changes to the endpoint of the connection, and you do not need to recompile applications if the URI of a service provider changes. For CICS web support applications, URIMAP resources can also be used to store and administer client certificates and cipher suite codes for SSL.

Connection pooling can provide performance benefits for CICS applications that use client HTTP connections in the following scenarios:
  • Multiple CICS web support applications, either invocations of the same application or different applications, make HTTP client requests to the same host and port.
  • Multiple CICS web services applications that are service requesters make requests to the same web service provider.
  • A CICS web services application that is a service requester makes multiple requests to a web service provider in a single task.
  • The HTTP EP adapter sends events frequently to the HTTP server specified in the event binding.
Connection pooling does not enhance the performance of a single invocation of a user-written CICS web support application, or a single web services request and response, or a single event emission.

How CICS manages connection pooling

Connection pooling is transparent to applications, and does not require any involvement from administrators after the SOCKETCLOSE attribute is specified in the URIMAP resource definition. CICS holds a pool of connections for each URIMAP resource that has a nonzero SOCKETCLOSE attribute.

Before placing an HTTP client connection in a pool of connections, CICS checks the state of the connection. Connections are not placed in the pool if they are found or suspected to be in a poor state. For example, the following situations would cause the connection to be in a poor state:
  • The last HTTP response from the server was not OK.
  • The number of requests and the number of responses on the connection are not equal.
  • The connection still has data present on it that the CICS application did not receive.
  • A CICS web support application that opened the connection did not issue a WEB CLOSE command to notify CICS that it had finished using the connection.

When an application issues a command to open an HTTP client connection and suitable connections are available in the pool, CICS selects the connection that was placed in the pool most recently. This practice enables older connections to expire in the situation where connection usage has reduced from a previous peak level. When a pooled connection reaches the time limit that you specified in the SOCKETCLOSE attribute without being reused, CICS closes the socket and removes the connection.

CICS also closes dormant connections in a pool in the following situations:
  • The web server closes a connection.
  • You discard the URIMAP resource associated with the pool of connections.
  • MAXSOCKETS is reached for the CICS region, and sockets are required for use by different connections.
The resource statistics for URIMAP definitions, in DFHWBRDS, include statistics for connection pooling as follows:
  • The SOCKETCLOSE setting for the URIMAP resource
  • The current and peak number of pooled connections in the pool for this URIMAP resource
  • The number of dormant connections that CICS reclaimed from the pool because the CICS region had reached the MAXSOCKETS limit
  • The number of dormant connections that were not reused and expired while they were in the pool
These statistics are reported in the DFHSTUP and DFH0STAT reports.

How to determine a SOCKETCLOSE value for Outbound Connection Pooling in CICS

Start by specifying a SOCKETCLOSE value of one minute 000100 (hhmmss) or a value of your choosing. Then, make use of your DFHSTUP statistics output or use the STAT transaction online to capture URIMAP Resource statistics. Specifically observing the following four statistics:
  • URIMAP Socket pool size
  • URIMAP Peak socket pool size
  • URIMAP Sockets reclaimed
  • URIMAP Sockets timed-out

You should not be too concerned about the "Socket pool size" or "Peak socket pool size" as they are purely influenced by the number of concurrent requests using the specific URIMAP. A high value is only a concern if the specific URIMAP is not expected to be being used very much.

The number of "Sockets reclaimed" is where CICS had no available sockets to service a new request so one of the idle sockets from the pool was closed and reused for the new request. If the number of reclaimed sockets is high then that could indicate the system is processing too much "sockets based work" compared to its MAXSOCKETS setting within the CICS system initialization parameters (DFHSIT). If this is your case you should consider increasing your MAXSOCKETS setting.

The most important value for tuning is the number of "Sockets timed out". If there is a huge number being timed out then this would indicate that one of the following is happening:
  • The sockets are not being used very much and are instead remaining idle in the pool until the SOCKETCLOSE value is reached
  • The SOCKETCLOSE value is too small and the sockets are getting closed before they have had a chance to get reused

In this case, the value for SOCKETCLOSE should be increased to allow the sockets to get reused. If the number of timeouts is 0 or a relatively small number then that indicates the pool is working well and the sockets are being actively reused.