Receiving the entity body of an HTTP request

 Top  Previous  Next

An application can issue the WEB RECEIVE command to receive the entity body of an HTTP request. You can receive only the first part of the entity body, or use a series of WEB RECEIVE commands to receive the whole body in smaller sections.

The WEB RECEIVE command does not set a timeout value. The user application is only called when the complete request has been successfully received from the Web client, and is being held by XCICS. For XCICS as an HTTP server, the close_timeout attribute in the TCPIPSERVICE definition for the port determines how long the Web client has to complete its request send. When this period expires, XCICS returns a 408 (Request Timeout) response to the Web client.

If a request message is sent using chunked transfer-coding, XCICS assembles the chunks into a single message before passing it to the application. If
a series of pipelined requests is sent, XCICS treats each request as a separate transaction, and requires a response from the user application before making the next request available to the next user application for processing.

The XCICS Command Reference has full reference information and descriptions of the options available on the WEB RECEIVE command. When you issue the WEB RECEIVE command:

1.Identify whether or not you need to receive an entity body for this request.
•For certain request methods (such as the GET method), an entity body is not appropriate, and your application is allowed to ignore any entity body that is present. If an inappropriate entity body is present, you may still receive it if you want. "Examining the request line for an HTTP request" in topic 2.3.1 tells you how to identify the request method.
•For an HTTP/1.1 request, the presence of an entity body is indicated by a non-zero Content-Length header on the request (or a Transfer-Encoding header, if the message is chunked). If the value of the Content-Length header is zero, or if neither the Transfer-Encoding header nor the Content-Length header is supplied, there is no entity body. "Examining the HTTP headers for a message" tells you how to read the HTTP headers for the message.
•HTTP/1.0 requests are not required to specify a Content-Length header, but they might do so. If you find a non-zero Content-Length header on the request, this indicates the presence of an entity body. If there is no Content-Length header, but the request method (in particular, the POST method) indicates that an entity body is appropriate, it is likely that an entity body is present.
2.Receive the entity body by specifying either the INTO option (for a data buffer), or the SET option (for a pointer reference), and the LENGTH option. On return, the LENGTH option is set to the length of data received.
3.If you want to limit the amount of data received from the entity body, specify the MAXLENGTH option.
•If you want to receive only the first part of the entity body, and discard any data that exceeds this length, omit the NOTRUNCATE option. This is the default.
•If you want to retain, rather than discarding, any data that exceeds this length, specify the NOTRUNCATE option. Any remaining data can be obtained using further WEB RECEIVE commands.
•If the data has been sent using chunked transfer-coding, XCICS assembles the chunks into a single message before passing it to the application, so the MAXLENGTH option applies to the total length of the entity body for the chunked message, rather than to each individual chunk. The total amount of data that XCICS accepts for a single message is limited by the MAXDATALEN attribute of the TCPIPSERVICE definition.
4.If you specified MAXLENGTH and NOTRUNCATE, and you have more data to receive, issue further WEB RECEIVE commands. A single RECEIVE command using the SET option and without the MAXLENGTH option receives all the remaining data, whatever its length. Alternatively, you can use a series of RECEIVE commands with the NOTRUNCATE option to receive the remaining data in appropriate chunks. Keep issuing the RECEIVE command until you are no longer getting a LENGERR response. Bear in mind that if you receive less than the length requested on the MAXLENGTH option, this does not necessarily indicate the end of the data; this could happen if XCICS needs to avoid returning a partial character at the end of the data.