Sending an HTTP request or response with chunked transfer-coding

You can set up chunked transfer-coding for an HTTP request by CICS® as an HTTP client or for an HTTP response from CICS as an HTTP server.

1. Before beginning a chunked message, verify that the web client or server is at HTTP/1.1 version.
   All HTTP/1.1 applications must handle chunked transfer-coding. A chunked message cannot be sent to an HTTP/1.0 recipient.
   1. For responses sent by CICS as an HTTP server, use the WEB EXTRACT command to check the HTTP version specified for the web client request.
   2. For requests sent by CICS as an HTTP client, the HTTP version of the server is returned on the WEB OPEN command for the connection if you specify the HTTPVNUM and HTTPRNUM options on the command. If you did not specify these options, use the WEB EXTRACT command to check the HTTP version of the server.
   3. Alternatively, you can omit this check and allow CICS to check the version of the web client or server when you issue the WEB SEND command to send the first chunk of the message.
      If the recipient is HTTP/1.0, you receive an error response.
2. Use the WRITE HTTPHEADER command as many times as necessary to write any HTTP headers that must be sent before the body of the message.
   Do not write the headers for chunked transfer-coding; CICS writes them itself, using the chunk length information supplied by the application program.
3. If you want to include trailing headers (headers sent out after the body of the message) with the chunked message, use the WRITE HTTPHEADER command to write a Trailer header. Specify the names of all the HTTP headers that you plan to send in the trailer, as the value of the Trailer header.
   You can send any headers as trailing headers, except the Transfer-Encoding, Trailer, and Content-Length headers.
   1. For responses sent by CICS as an HTTP server, ensure that the web client sent a TE: trailers header on its request.
      This header shows that the client handles trailing headers.
      CICS returns an INVREQ response with a RESP2 value of 6 to the WRITE HTTPHEADER command if you attempt to write the Trailer header when the client did not send TE: trailers. Alternatively, you can use the READ HTTPHEADER command to check for the presence of the TE: trailers header.
   2. For requests sent by CICS as an HTTP client, trailing headers can be included without reference to the TE header.
   The trailing headers themselves are written during the chunked sending process.
4. Use the WEB SEND command to send the first chunk of the message.
   1. Specify CHUNKING(CHUNKYES) to tell CICS that it is a chunk of a message.
   2. Use the FROM option to specify the first chunk of data from the body of the message.
   3. Use the FROMLENGTH option to specify the length of the chunk.
   4. For requests by CICS as an HTTP client, specify an appropriate method on the METHOD option. Chunked transfer-coding is not relevant for requests with no message body, so it is not relevant for the GET, HEAD, DELETE, OPTIONS, and TRACE methods, but you can use it for the POST and PUT methods.
   5. Specify any other options that apply to both chunked and non-chunked messages, as given in your main set of instructions.
5. Use the WEB SEND command as many times as necessary to send each of the remaining chunks of the message. On each WEB SEND command, specify the following items:
   1. CHUNKING(CHUNKYES)
   2. FROM, giving the chunk of data
   3. FROMLENGTH, giving the length of the chunk
   Do not specify any other options for the command. CICS sends each chunk as you issue the command.
6. Optional: At any time after issuing the WEB SEND command for the first chunk, but before issuing the WEB SEND command for the final empty chunk (see the next step), use the WRITE HTTPHEADER command to create further HTTP headers that are sent as trailing headers.
   If a Trailer header was written on the first chunk of the message, the HTTP headers written during the chunked sending process are treated by CICS as trailing headers, and they are sent out with the final empty chunk. (If the Trailer header was not written, CICS does not allow any trailing headers to be written.)
   Note that CICS does not check whether your trailer headers match the names that you specified in the initial Trailer header on the first chunk of the message.
7. When you have sent the last chunk of the data, specify a further WEB SEND command with CHUNKING(CHUNKEND) and no FROM or FROMLENGTH option.
   CICS then generates and sends an empty chunk to the recipient to end the chunked message. The empty chunk is sent with the trailer containing any trailing headers that you wrote.
8. For CICS as an HTTP server, errors are handled as follows:
   1. If one of the WEB SEND commands fails during the sequence, an error response is returned, and subsequent sends also fail. The application must handle this situation appropriately.
   2. If all the chunks are sent successfully, but the application does not issue the final WEB SEND command with CHUNKING(CHUNKEND), the transaction is abended with abend code AWBP.
      This abend is necessary because CICS cannot guarantee that the chunked message is complete and correct, and so cannot issue the final empty chunk on behalf of the application.
   An incomplete chunked message is ignored and discarded by the recipient. The web client determines whether to try the request again.
9. For CICS as an HTTP client, errors are handled as follows:
   1. If your application program is informed of an error at any point in the chunked transfer-coding process, use the WEB CLOSE command to stop the process and close the connection.
      The server does not receive the final empty chunk and, therefore, ignores and discards the data that you have sent so far. You can decide whether to retry the request.
   2. If you do not send the final empty chunk or issue the WEB CLOSE command, a warning message is written at task termination to CWBO, the transient data queue for CICS web support messages.
      The server times out the receive and ignores and discards the data that you sent.