Using chunked transfer-coding to send an HTTP request or response

This topic tells you how to set up chunked transfer-coding for an HTTP response from CICS as an HTTP server.

Before setting up chunked transfer-coding, you need to plan the following attributes of the item that you want to send:

  1. The HTTP headers that should be used at the beginning of the message. CICS supplies its usual message headers, which are listed in HTTP header reference for CICS Web support. For a chunked message, CICS supplies the proper headers for chunked transfer-coding, including the Transfer-Encoding: chunked header. If any additional headers are required at the beginning of the message, the application can write them before the first WEB SEND command.
  2. Any headers that should be sent in the trailer at the end of the message. These headers are known as trailing headers. Note that the HTTP/1.1 specification sets requirements for the use of trailing headers, including that it should not matter if the recipient ignores them.
  3. How the message should be divided up. This can be done in whatever way is most convenient for the application program. For example, the output from a number of other application programs could be sent as it is produced, or data from each row of a table could be read and sent individually.
  4. The length of each chunk of data that will be sent. Do not include the length of any trailing headers.

The procedure described in this topic enables you to create a correctly constructed chunked message, as defined in the HTTP/1.1 specification. If the chunked message is not correctly constructed, the recipient may discard it.

The body of a chunked message cannot be formed directly from CICS documents (so the DOCTOKEN option cannot be used). The FROM option must be used to specify data to form the body of a chunked message.

When you have begun sending the parts of a chunked message, you cannot send any different messages or receive any items, until the final empty chunk is sent and the chunked message is complete.

  1. Before beginning a chunked message, verify that the Web client is at HTTP/1.1 version. All HTTP/1.1 applications are required to understand chunked transfer-coding. A chunked message cannot be sent to an HTTP/1.0 recipient. Use the WEB EXTRACT command to check the HTTP version specified for the Web client's request.
  2. Use the WRITE HTTPHEADER command as many times as necessary to write any HTTP headers that should be sent before the body of the message. Do not write the headers for chunked transfer-coding; CICS writes these 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 you plan to send in the trailer, as the value of the Trailer header. You may send any headers as trailing headers, except the Transfer-Encoding, Trailer and Content-Length headers. You need to ensure that the Web client sent a TE: trailers header on its request. This header shows that the client understands 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. 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 this 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. Specify any other options that apply to both chunked and non-chunked messages, as given in our main set of instructions. For example, if this chunked message is the final message that you want to send to this Web client, specify the CLOSESTATUS(CLOSE) option.
  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, just specify the following items:
    1. CHUNKING(CHUNKYES).
    2. The FROM option, giving the chunk of data.
    3. The FROMLENGTH option, giving the length of the chunk.

    Do not specify any of the 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 should be sent as trailing headers. Provided that 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 along with the trailer containing any trailing headers that you wrote.
  8. 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 will also fail. The application should handle this situation appropriately.
    2. If all of 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 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 should be ignored and discarded by the recipient. The Web client will decide whether or not to retry the request.