Start of change

Making HTTP requests through CICS as an HTTP client

HTTP client requests made from CICS® to a server on the Internet are initiated by a user-written application program. This topic tells you how to write an application program that makes an HTTP client request.

Before writing an application program that makes an HTTP client request, read about the processing stages for these requests, because most of the stages are initiated by the application program itself. HTTP request and response processing for CICS as an HTTP client explains what the application program needs to do, and what actions CICS takes during the process.

For CICS as an HTTP client, the application program makes requests to a server, and waits for the responses. An application program can control more than one connection, using a session token to differentiate between them.

To make HTTP requests and receive responses, write your application program to follow this process:

  1. Initiate a connection to the server, using the WEB OPEN command. Opening a connection to an HTTP server tells you how to do this. This step ensures that the server is available, and generates the session token that can be used to manage the connection.
  2. Write HTTP headers for the request, using the WEB WRITE HTTPHEADER command. Writing HTTP headers for a request tells you how to do this. CICS automatically provides the headers that are required for HTTP/1.1 messages. You can provide additional headers for other purposes.
  3. If required, produce an entity body, or message body, which is the content of the HTTP request. The process is the same as when CICS is an HTTP server, as described in Producing an entity body for an HTTP message. For many request methods, an entity body is not used, but for the POST and PUT methods (which are used to supply data to the server) it is required. The entity body is formed from a CICS document (which is created using the EXEC CICS DOCUMENT application programming interface) or from a buffer of data supplied by the application program.
  4. Send the request to the Web client using the WEB SEND or WEB CONVERSE command. Writing an HTTP request tells you how to do this. You need to select a suitable method, and specify the entity body. CICS assembles the request using these items and the HTTP headers. If you want to use chunked transfer-coding, you also need to follow the special instructions in Using chunked transfer-coding to send an HTTP request or response.
  5. If you want to send further requests as a pipelined sequence, use the guidance in Sending a pipelined sequence of requests to do this.
  6. Wait for and receive the request, following the process in Receiving an HTTP response:
    1. Receive the message body of the response using the WEB RECEIVE command (or the WEB CONVERSE command that you issued earlier).
    2. Read the headers for the response using the WEB READ HTTPHEADER command, or the HTTP header browsing commands.
    3. Process the server's response, depending on the status code, and execute the application's business logic.
    4. If you sent a pipelined sequence of requests, receive the rest of the responses from the server using further WEB RECEIVE commands.
  7. If further requests and responses are wanted, repeat the process. If the server supports persistent connections, and does not close the connection, there is no need to open a new connection. You can continue using the same session token. If the server closes the connection, you need to issue the WEB OPEN command again if you want to make further requests.
  8. When you have finished working with the server, close the connection. Closing the connection to an HTTP server explains how to do this.
End of change