Writing an HTTP request

For CICS® as an HTTP client, the WEB SEND command or the WEB CONVERSE command can be used to make a request. The WEB CONVERSE command combines the options available on the WEB SEND command and the WEB RECEIVE command, so that you can use a single command to issue a request and receive the response.

You need to specify an HTTP method when making a request. The method tells the server what to do with your request. HTTP method reference for CICS Web support provides basic guidance on the different methods that you can use with CICS Web support. For more detailed guidance, including any requirements that apply to your use of methods, you should consult the HTTP specification to which you are working. See The HTTP protocol for more information about the HTTP specifications. CICS sends your request with HTTP/1.1 given as the HTTP version.

Write any additional HTTP headers for the request using the WEB WRITE HTTPHEADER command before making the request, as described in Writing HTTP headers for a request.

If wanted, the request can be sent in chunks (chunked transfer-coding), or you can send a pipelined sequence of requests.

The CICS Application Programming Reference has full reference information and descriptions of the options available on the WEB SEND and WEB CONVERSE commands. When you issue your chosen command:

  1. Specify the session token for this connection, using the SESSTOKEN option.
  2. Specify the HTTP method for the request (OPTIONS, GET, HEAD, POST, PUT, DELETE, or TRACE). HTTP method reference for CICS Web support has guidance for the correct use of each of these methods.
  3. Specify the path information for the resource on the server that the application needs to access. The default is the path given in any URIMAP definition that you referenced on the WEB OPEN command for this connection. You can specify an alternative path by using the URIMAP option to name another URIMAP definition from which the path can be taken. (The new URIMAP definition must specify the correct host name for the current connection.) Alternatively, you can use the PATH and PATHLENGTH options to provide the path information.
  4. Specify any query string for your request, using the QUERYSTRING and QUERYSTRLEN options.
  5. Specify any entity body for the HTTP request, and its length. HTTP method reference for CICS Web support has information about where the use of a request body is and is not appropriate.
    • For the GET, HEAD, DELETE, and TRACE methods, a request body is inappropriate.
    • For the OPTIONS method, a request body is permitted, but the HTTP/1.1 specification does not define any purpose for this body at present.
    • For the POST and PUT methods, a request body must be used.
    If a request body is required, the body content can be formed from a CICS document (using the CICS DOCUMENT interface and specifying the DOCTOKEN option to identify the document), or from the contents of a buffer (specifying the FROM option). Producing an entity body for an HTTP message explains how to produce this, and has information about size limits for the length of the body.
  6. Specify the media type for any entity body you are providing, using the MEDIATYPE option. For requests with the POST and PUT methods, which require a body, you need to specify the MEDIATYPE option. For requests with other methods, where no body content is provided, the MEDIATYPE option is not required.
  7. If code page conversion is not required for the request body, specify the appropriate conversion option (depending on whether you are using the WEB SEND command or the WEB CONVERSE command) so that CICS does not convert the request body. For CICS as an HTTP client, the default setting is that the request body is converted, unless it has a non-text media type.
  8. If code page conversion is required, and the default ISO-8859-1 character set is not suitable, specify a character set that is suitable for the server. ISO-8859-1 should be acceptable for most servers, unless you know from earlier connections that the server prefers an alternative.
  9. If you want to use the Expect header to test the server's acceptance of the request, specify EXPECT for the ACTION option. This setting makes CICS send an Expect header along with the request line and headers for the request, and await a 100-Continue response before sending the message body to the server. If a response other than 100-Continue is received, CICS informs the application program and cancels the send. If no response is received after a period of waiting, CICS sends the message body anyway.
  10. If this is the last request that you want to make to this server, specify CLOSE for the CLOSESTATUS option. CICS writes a Connection: close header on the request, or, for a server at HTTP/1.0 level, omits the Connection: Keep-Alive header. Specifying this option when you make your final request is good behavior, because the information in the headers means that the server can close its connection with you immediately after sending the final response, rather than waiting to see if you send further requests before timing out. The response from the server is still received and made available to your application. However, you will not be able to send any further requests to the server using this connection.
  11. If you want to use chunked transfer-coding to send the request body as a series of chunks, follow the additional instructions in Using chunked transfer-coding to send an HTTP request or response.
    Note: Chunked transfer-coding is not supported with:
    • Servers below HTTP/1.1.
    • The WEB CONVERSE command.
    • CICS documents (the DOCTOKEN option).
  12. If you want to send a pipelined sequence of requests, follow the instructions in Sending a pipelined sequence of requests.
CICS assembles the request line, HTTP headers and request body, and sends the request to the server.