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.
Before you begin
First, consider these attributes of the item that you want
to send:
- The HTTP headers to 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 to be sent in the trailer at the end of the message.
These headers are known as trailing headers. The HTTP/1.1 specification
sets requirements for the use of trailing headers, including that
it must not matter if the recipient ignores them.
- How the message will be divided. Divide it in whatever way is
most convenient for the application program. For example, the output
from a number of other application programs might be sent as it is
produced, or data from each row of a table might 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.
About this task
Use this procedure to create a correctly constructed chunked
message, as defined in the HTTP/1.1 specification. See The HTTP protocol for more information. If the chunked
message is not correctly constructed, the recipient might 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 with either
of those sets of instructions.
You cannot form the body of a chunked message directly from CICS documents,
so you cannot use the DOCTOKEN option. You must use the FROM option
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.
Procedure
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- Use the WEB SEND command to send the first chunk of the
message.
- Specify CHUNKING(CHUNKYES) to tell CICS that
it 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, 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.
- Specify any other options that apply to both chunked
and non-chunked messages, as given in your main set of instructions.
- 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:
- CHUNKING(CHUNKYES)
- FROM, giving the chunk of data
- 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.
- 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.
- 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.
- 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 also fail. The
application must handle this situation appropriately.
- 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.
- 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
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.
- 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.