Start of change

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 with the HTTP server through CICS. The application program does this by issuing the EXEC CICS WEB OPEN command. A URIMAP resource definition 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. (The CICS Resource Definition Guide has more information about URIMAP definitions.) An application may have more than one connection open at a time.
  2. CICS establishes the connection with the server. 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 may 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. CICS queries the HTTP version of the server when the connection is opened, and uses this information for subsequent communications. CICS also returns the HTTP version information to the application program, to be checked if you plan to write HTTP headers or send chunked messages. When the TCP/IP connection is established, CICS returns a session token to the application program to uniquely identify the connection. This session token is used on all the remaining commands issued by the application program concerning that connection. Session tokens explains more about the session token.
  3. The application program may 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 may 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 command) or by a URIMAP definition. During sending of the request, the XWBSNDO user exit is called to apply a security policy for the individual request, if required.
  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 may initiate further requests and responses. If the server supports persistent connections, the connection identified by the session token remains open for further requests.
  11. The application program initiates closing of the connection to the server. When all the requests and responses are completed, the application program issues a WEB CLOSE command, and CICS closes its end of the TCP/IP connection. If the application program does not issue a WEB CLOSE command, the connection is closed at end of task.

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.

End of change