HTTP request and response processing for CICS as an HTTP client

For CICS® as an HTTP client, CICS is the web client, and it communicates with an HTTP server. A user-written application program sends requests through CICS to the HTTP server, and receives the responses from it. CICS maintains a persistent connection with the server. A session token is used on the commands issued by the application program to identify the connection.

An application program that makes an HTTP request and receives a response must use the EXEC CICS WEB API commands to explicitly direct the interaction with the server. A web-aware application program could be used to make an HTTP request, and then process the results to provide information to an application that is not web-aware.

The application program that initiates the HTTP request should be designed to process whatever CICS receives from the server in response to that request, which might include error responses, redirection to another URL, embedded hypertext links, HTML forms, image source, or other items that request an action from the application program. CICS can perform code page conversion for requests and responses, if required.

Figure 1 shows the process described in this topic.
Figure 1. Processing for CICS as an HTTP client
Client HTTP processing. The elements used and the way in which they interact are described in the text following the figure.
Processing for CICS as an HTTP client takes place as follows:
  1. The application program initiates a connection to the HTTP server through CICS. The application program does this by issuing the EXEC CICS WEB OPEN command. A URIMAP resource that you have created can be referenced to specify the scheme and host name for the connection, or the application program can provide this information. (See URIMAP resource definitions for more information about URIMAP resources.) An application can have more than one connection open at a time.
  2. CICS establishes the connection with the server, or checks for a suitable pooled connection. Using the information provided by the application program, CICS opens a TCP/IP connection on a socket and contacts the server. During this process, the XWBOPEN user exit can be used (if it has been activated using the ENABLE PROGRAM command) to redirect the application program's requests through a proxy server, if required, and to apply a security policy to connections to the host. Alternatively, if the application program used a URIMAP resource that specifies connection pooling (the SOCKETCLOSE attribute), CICS checks whether a dormant connection is available in the pool for reuse. When the TCP/IP connection is established, or the existing connection is supplied to the application for reuse, CICS returns a session token to the application program to uniquely identify the connection during its use. This session token is used on all the remaining commands issued by the application program concerning that connection. See Session tokens for more information about the session token.
  3. The application program can write HTTP headers for its request. User-written HTTP headers can be built using the WEB WRITE HTTPHEADER command and stored ready for sending.
  4. The application program specifies components of the request line. The request method, path information, and query string are specified using the WEB SEND or WEB CONVERSE command. The HTTP version for the request is supplied by CICS.
  5. The application program can produce an entity body for its request. The content of the request is specified on the WEB SEND or WEB CONVERSE command. It can be formed from a CICS document (using the DOCUMENT interface), or from the contents of a buffer. If the server is at HTTP/1.1, chunked transfer-encoding may be used for a request body formed from the contents of a buffer (but not for a CICS document).
  6. The application program initiates transmission of the request. When the application program issues the WEB SEND or WEB CONVERSE command, the request is passed to CICS for sending across the connection specified by the session token.
  7. CICS generates some required HTTP headers and adds them to the request, then sends the request to the server. The values for some of the headers are generated directly by CICS (such as the Date header), and the values of others are based on information provided by the application program (using the WEB SEND or WEB CONVERSE command) or by a URIMAP resource. During sending of the request, two user exits can be invoked, if required. XWBSNDO is called to apply a security policy for the individual request, and XWBAUTH specifies the username and password details required for Basic Authentication.
  8. The server receives and processes the request, and provides a response. CICS passes the response to the application program.
  9. The application program examines the response. The WEB READ HTTPHEADER command, or the HTTP header browsing commands, can be used to examine the headers of the response. The WEB RECEIVE or WEB CONVERSE command receives the body of the response (if there is one), which can be processed by the application program, and the response's status code and status text.
  10. The application program can initiate further requests and responses. If the server supports persistent connections, the connection identified by the session token remains open for further requests. If the server does not support persistent connections, the server instructs CICS to close the connection.
  11. The application program finishes its use of the connection. When all the requests and responses are completed, the application program issues a WEB CLOSE command to end its use of the connection. If the connection was opened using a URIMAP resource that specified connection pooling, and neither the server nor the application program have made a request to close the connection, CICS does not close the connection. Instead, CICS checks that the connection is in a good state and then places it in a pool of dormant connections. Pooled connections can be reused by another application program or by another instance of the same application program to connect to the same server. When a connection is not suitable for connection pooling, because it has been closed, or it was not opened using a URIMAP resource, or it is not in a good state, CICS closes the connection.

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 HTTP servers (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, WEB RECEIVE, or WEB CONVERSE commands. For CICS as an HTTP client, the default is that code page conversion does take place when messages are sent and received.