Rejecting HTTP requests

If an application or resource in your CICS® system is temporarily unavailable and you cannot provide cover through redirection, or if an application or resource has been permanently removed, you can reject HTTP requests at several different levels. You can also implement connection throttling if a CICS region is at risk of becoming overloaded with long-lived persistent connections from web clients.

About this task

You can reject HTTP requests at these levels:

At the level of the specific request URL. To achieve this level of granularity, the request URL is covered by a URIMAP definition. If you do not have URIMAP definitions, you can modify the handling of HTTP requests through changes to the analyzer program that handles the requests, but this technique is less convenient.
At the level of a virtual host (which covers all requests for a particular host name). For a request to be incorporated into a virtual host, it must be covered by a URIMAP definition.
At the level of a port. A port maps to a TCPIPSERVICE definition. For example, disabling the TCPIPSERVICE definition for the default HTTP port 80 prevents CICS from receiving any HTTP requests, except requests that use SSL or nonstandard ports.
Completely, at the level of all ports. In the CEMT transaction or in CICSPlex® SM, you can shut down CICS internal TCP/IP sockets support, and so shut down CICS web support completely.

Generally, if you reject the HTTP request at a more granular level, CICS can give a more useful error response to the web client. For example, if you reject an HTTP request by disabling a URIMAP definition or a virtual host, CICS returns an HTTP 503 response (Service Unavailable) to the web client through a web error program. You can tailor the web error program to modify this response. However, if you reject HTTP requests by disabling a TCPIPSERVICE definition, the web client receives only a general error response that indicates a server error.

If you have a CICS region that has experienced performance problems because too many web clients set up a long-lived persistent connections, you can implement connection throttling to control these requests. Connection throttling automatically limits the number of persistent HTTP connections that a single CICS region accepts for a particular port, so you do not have to intervene manually. Web clients can obtain a persistent connection by reconnecting to another CICS region that shares the port and provides the same service.

When you implement connection throttling, web clients over the limit that you set are required to close their connection after each response. An HTTP/1.1 server should normally allow persistent connections, so only set the connection throttling if you need to provide automatic intervention for a CICS region that has experienced performance problems. How CICS web support handles persistent connections explains the impact of connection throttling.

You can reject or throttle HTTP requests in these ways:

Procedure

To reject requests to a particular request URL:
1. If you have a URIMAP definition for the URL, disable the URIMAP definition.
  Check that the request URL is not matched by a less specific URIMAP definition that has a wildcard character in the path.
  CICS returns an HTTP 503 response (Service Unavailable) to the web client through a web error program. You can tailor this response by changing the web error program.
2. If you do not have a URIMAP definition for the URL, you can reject requests by changing the analyzer program associated with the TCPIPSERVICE definition for the port on which the request is made.
  You might want to code the analyzer program to provide an individual rejection message for each URL, or you might prefer to provide a single message that covers any URL that is unavailable.
  
  Analyzer programs tells you which actions are appropriate for handling rejected requests.
To reject requests to a virtual host (that is, all requests to a certain host name), disable the virtual host using the SET HOST command, as described in Administering virtual hosting.
CICS returns an HTTP 503 response (Service Unavailable) to the web client through a web error program. You can tailor this response by changing the web error program.
To limit the number of persistent connections to the CICS region on a particular port, specify a value for the MAXPERSIST attribute when you set up the TCPIPSERVICE definition.
If your limit is reached, connection throttling is implemented. CICS sends the Connection: close header on responses to further web clients that connect on the port, and they must close the connection after receiving the response. Be aware that the performance of these new web clients can be affected by connection throttling, especially if they reconnect to the same CICS region. When these web clients connect to another CICS region that shares the port and has not reached its limit, they can maintain a persistent connection there instead. The web clients that already had persistent connections to the CICS region can maintain their persistent connections.
When the web clients that have persistent connections close their connections, the CICS region begins to accept new persistent connections again.
To reject all requests on a particular port, disable the TCPIPSERVICE definition using the SET TCPIPSERVICE command in CEMT, or CICSPlex SM.
You can choose to stop listening on the port normally, with active tasks being allowed to complete, or immediately, with active tasks being ended abnormally.
To reject all inbound and outbound requests and stop CICS web support completely, use the SET TCPIP command in CEMT, or CPSM, to close TCP/IP.
You can choose to close normally, with active tasks being allowed to complete, or immediately, with active tasks being ended abnormally.