Writing an HTTP request

For CICS® as an HTTP client, you can use the WEB SEND command or the WEB CONVERSE command 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.

1. Specify the session token for this use of the connection, using the SESSTOKEN option.
2. Specify the HTTP method for the request (OPTIONS, GET, HEAD, PATCH, POST, PUT, DELETE, or TRACE), referring to HTTP method reference for CICS web support.
   The method tells the server what to do with your request. For more detailed guidance, consult the HTTP specification to which you are working, indicated in The HTTP protocol . CICS sends your request with HTTP/1.1.
3. Specify the path information for the required resource on the server.
   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 tells you when the use of a request body is appropriate.
   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. See Producing an entity body for an HTTP message.
6. Specify the media type for any entity body that you are providing, using the MEDIATYPE option.
   For requests with the PATCH, POST and PUT methods, which require a body, you need to specify the MEDIATYPE option. For requests with other methods, without body content, the MEDIATYPE option is not required.
7. Specify code page conversion as appropriate.
   For CICS as an HTTP client, the default setting is that the request body is converted, unless it has a nontext media type.
   • 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.
   • If code page conversion is required, ISO-8859-1 is the default and acceptable for most servers. If the default ISO-8859-1 character set is not suitable, specify a character set that is suitable for the server.
8. If you want to use the Expect header to test the acceptance by the server of the request, specify EXPECT for the ACTION option.
   This setting makes CICS send an Expect header 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.
   The Expect header is not supported by servers before HTTP/1.1. If CICS does not yet know the HTTP version of the server, CICS requests the version number before sending your request. If the Expect header is not suitable, CICS sends your request without it.
9. Optional: If this request is the last one that you want to make to this server, depending on whether or not you are using connection pooling, you might want to request the server to close the connection:
   1. If you are not using connection pooling for this connection, you may specify CLOSE for the CLOSESTATUS option. With this 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 means that the server can close its connection immediately after sending the final response. This behavior is not a requirement for web clients, but it is best practice if you definitely do not want to keep the connection available for reuse.
   2. If you are using connection pooling for this connection, do not specify the CLOSESTATUS option. If you specify CLOSESTATUS(CLOSE), the server closes the connection and it cannot be pooled.
   Connection pooling is enabled when you open a connection using a URIMAP resource with the SOCKETCLOSE attribute set.
10. If you want to use chunked transfer-coding to send the request body as a series of chunks, follow the additional instructions in Sending an HTTP request or response with chunked transfer-coding.
    Chunked transfer-coding is not supported in these circumstances:

    • Servers before HTTP/1.1
    • The WEB CONVERSE command
    • CICS documents (the DOCTOKEN option)