This topic tells you how to set up chunked transfer-coding for
an HTTP request by CICS® as an HTTP client, or 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:
- 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.
- 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.
- 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.
- 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.
See The HTTP protocol for more information about the
HTTP/1.1 specification. If the chunked message is not correctly constructed,
the recipient may discard it.
Sending an HTTP response from CICS as an HTTP server is the main set of instructions for writing an application
program to send a server response. Making HTTP requests through CICS as an HTTP client is
the main set of instructions for writing an application program to make a
client request. You can use the instructions in the present topic in conjunction
with either of those sets of instructions.
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.
- Before beginning a chunked message, verify that the Web client
or server 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.
- For responses sent by CICS as an HTTP server, use the WEB EXTRACT
command to check the HTTP version specified for the Web client's request.
- 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.
- 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.
- 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.
- For responses sent by CICS as an HTTP server, 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.
- For requests sent by CICS as an HTTP client, trailing headers
may be included without reference to the TE header.
The trailing headers themselves are written during the chunked sending
process.
- Use the WEB SEND command to send the first chunk of the message.
- Specify CHUNKING(CHUNKYES) to tell CICS that this is a chunk of a message.
- Use the FROM option to specify the first chunk of data from
the body of the message.
- Use the FROMLENGTH option to specify the length of the chunk.
- For requests by CICS as an HTTP client, an appropriate
method must be specified 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 it can be used for
the POST and PUT methods.
- Specify any other options that apply to both chunked and non-chunked
messages, as given in your main set of instructions. For example,
if this chunked message is the final message that you want to send to this
server or Web client, specify the CLOSESTATUS(CLOSE) option.
- 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:
- CHUNKING(CHUNKYES).
- The FROM option, giving the chunk of data.
- 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.
- 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.
- 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.
- For CICS as
an HTTP server, errors are handled as follows:
- 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.
- 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.
- For CICS as
an HTTP client, errors are handled as follows:
- 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 will not receive
the final empty chunk, and so should ignore and discard the data that you
have sent so far. You can decide whether or not to retry the request.
- 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 should time out the receive, and
ignore and discard the data that you sent.