|
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. XCICS supplies its usual message headers and, for a chunked message, 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. |
| 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 XCICS 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 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 XCICS 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 XCICS as an HTTP client, the HTTP version of the server is returned on the WEB OPEN command for the connection. |
| 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; XCICS 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. |
| 4. | Use the WEB SEND command to send the first chunk of the message. |
| • | Specify CHUNKING(CHUNKYES) to tell XCICS 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 XCICS 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. |
| 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: |
| • | The FROM option, giving the chunk of data. |
| • | The FROMLENGTH option, giving the length of the chunk. |
| 6. | 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. XCICS 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. |
| 7. | For XCICS 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), XCICS completes the request issuing the ending chunk. |
| 8. | For XCICS 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, XCICS will do it. |
|
