HTTP request and response processing for CICS as an HTTP server

HTTP requests for CICS® as an HTTP server are initiated by a web client that makes a request to CICS. CICS provides the web client with responses to the requests it makes. The responses can be created from a static document identified by a URIMAP resource definition, or they can be created dynamically by a user application program.

Figure 1 shows the processing that is carried out by CICS web support to receive a request from a web client and provide a response.
Figure 1. Processing for CICS as an HTTP server
Server HTTP processing. The text following the figure explains the architecture elements shown and how they work together to process a request.
Processing for CICS as an HTTP server takes place as follows:
  1. CICS receives a TCP/IP connection request. The CICS Sockets domain uses the TCPIPSERVICE resource definition for the port to determine that the request should be processed by CICS web support. The TCPIPSERVICE definition specifies security attributes to be applied to the request, specifies the timeout setting for receiving the request message, and limits the maximum amount of data that can be received for a single request.
  2. CICS matches the URL for the request to a URIMAP definition, if available. CICS tries to match the URL specified in the HTTP request to any URIMAP resource definitions that are related to the TCPIPSERVICE definition and apply to CICS as an HTTP server. If a successful match is made, the URIMAP definition tells CICS how to process the request. If no match is found, CICS continues with the default process, which begins at processing stage 7 with the analyzer program.
  3. If the URIMAP definition specifies redirection, CICS redirects the web client to the specified URL. CICS composes the redirection message and transmits it to the web client. This completes the processing for that HTTP request.
  4. If the URIMAP definition relates to an Atom document, CICS locates the specified ATOMSERVICE resource to handle the request. Processing for Atom documents is described in How Atom feeds work in CICS.
  5. If the URIMAP definition relates to a web service, CICS locates the specified PIPELINE resource to handle the request. Processing for web services is described in How CICS supports web services .
  6. If the URIMAP definition specifies a static response, CICS forms and supplies the response. CICS uses a document template or a z/OS® UNIX System Services file, together with appropriate HTTP headers, to form an HTTP response. The response undergoes appropriate code page conversion, and CICS then transmits the response to the web client. This completes the processing for that HTTP request.
  7. An analyzer program may be run, if the URIMAP definition specifies its use, or if no matching URIMAP definition is found. The analyzer program can interpret the request dynamically, or it can be used for monitoring or audit purposes.

    The analyzer program for the TCPIPSERVICE definition must be used in the request processing path if no URIMAP definition has been set up for the request. It might also be needed if you are using a non-web-aware application program that has special requirements, for code page conversion or for pre-CICS TS Version 3 compatibility processing. (Analyzer programs explains these situations.) Otherwise, the use of an analyzer program is optional, but note that the analyzer program is called to process the request if the URIMAP definition is not found.

    If an analyzer program is being used, the HTTP request and the HTTP headers are passed to the analyzer program. The analyzer program can interpret the request to determine:
    • Which CICS resources are to be used to service the request.
    • Which user ID is to be associated with the request.
    • Which of the remaining processing stages are required.
  8. A converter program may be used to decode the request and construct input to the application program. Web-aware application programs should accept an HTTP request without any decoding. However, if you want to service an HTTP request using a non-web aware application program that requires COMMAREA input, you can use a converter program to decode the request and construct input that fits the requirements of your application program. A converter program can be specified using a URIMAP definition, or it can be selected by an analyzer program.
  9. An application program is executed to service the request. You can specify the application program using a URIMAP definition, or using an analyzer program. A web-aware application program, using the EXEC CICS WEB and EXEC CICS DOCUMENT application programming interfaces, can be used to handle the request and construct a response. A non-web-aware application program can be enabled for the web using either a converter program (which translates the web client's request into acceptable input, and composes an HTTP response based on the program's output), or a web-aware application program that calls the non-web aware program and uses its output.

    The application program runs under an alias transaction.

    The application program can perform the following tasks:
    • If the application program is web-aware, it can examine the HTTP headers on the request, extract information (such as a query string) from the request line, receive the body of the request into a buffer for processing, select a status code and text for the status line of the response, and write HTTP headers for the response. EXEC CICS WEB API commands such as WEB SEND and WEB WRITE HTTPHEADER are used to construct the response.
    • Whether or not the application is web-aware, it can produce output that forms the body of the response. Web-aware application programs can produce an entity body formed from a CICS document template or from a buffer of data. Application programs that are not web-aware can produce output that can be converted by a web-aware application program or a converter program into an entity body.
  10. A converter program may be used to encode the output from the application program and construct an HTTP response. If the application program is not web-aware and its output is not in the correct form to send to a web client, you can use a converter program to produce an appropriate HTTP response including a status line and HTTP headers. The converter program can also perform other types of processing on the output.

    The converter program can specify that processing stages 6 (decoding or other processing using converter program), 7 (application program) and 8 (encoding or other processing using converter program) should be repeated. Because the converter program can change the name of the application program, you can use this facility to allow more than one application program to work on the same request in sequence, and provide a single response.

  11. If a request error or an abend occurs in the CICS web support process, an error response is sent to the web client, which can be customized using the user-replaceable web error programs. DFHWBEP or DFHWBERX receives information about the error situation, and the default HTTP response (including status code and status text) that CICS plans to send to the web client. The user-replaceable programs can customize the response or build a new one, and return it to CICS for sending.

    The web error programs are not used in all error situations. They are used when problems occur in initial processing of requests, and for abends or failures in subsequent processing. They are not used for situations where processing (such as processing by a user-written application program) completes correctly and an error or redirection response is the designed outcome.

  12. CICS generates some required HTTP headers and adds them to the message. Appropriate headers are generated depending on the HTTP version for the response. If the response is HTTP/1.1, CICS adds headers that are required for HTTP/1.1 messages. If the response is HTTP/1.0, CICS adds the Connection: Keep-Alive header if the client has requested a persistent connection, and a small number of other headers. The values for some of these headers are generated directly by CICS (such as the Date header), and the values of others are based on information provided by a web-aware application program (using the WEB SEND command) or by a URIMAP definition. The headers can be added both to output from a web-aware application, and to output from a converter program.
  13. CICS transmits the complete HTTP response to the web client. If the web client supports persistent connections, CICS keeps the connection open for further possible HTTP requests, until the user application or web client requests closure or the timeout period is reached.

During this process, code page conversion is usually needed when messages enter and leave the CICS environment, so that CICS web support processing and user-written applications (which typically use an EBCDIC encoding) can communicate with web clients (which typically use an ASCII encoding). Code page conversion for CICS Web support explains when and how this takes place. The type of code page conversion that is required can be specified using options on the WEB SEND or WEB RECEIVE commands.

To improve performance, HTTP requests can bypass the web attach task. For further information, see Processing HTTP requests by using directly attached user transactions.