Receiving the entity body of an HTTP request

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.

1. Identify whether you need to receive an entity body for this request.
   1. 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.
      HTTP method reference for CICS web support indicates the methods where this applies. If an inappropriate entity body is present, you may still receive it if you want.
      Examining the request line for an HTTP request tells you how to identify the request method.
   2. For an HTTP/1.1 request, the presence of an entity body is indicated by a nonzero 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, no entity body is present.
      Examining the HTTP headers for a message tells you how to read the HTTP headers for the message.
   3. HTTP/1.0 requests are not required to specify a Content-Length header, but they might do so. A nonzero Content-Length header on the request indicates the presence of an entity body.
      If no Content-Length header is present, but the request method (in particular, the POST method) indicates that an entity body is appropriate, an entity body is probably 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.
   1. 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.
      NOTRUNCATE is the default.
   2. If you want to retain, rather than discard, any data that exceeds this length, specify the NOTRUNCATE option.
      You can obtain any remaining data using further WEB RECEIVE commands.
   If the data has been sent using chunked transfer-coding, CICS 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 CICS accepts for a single message is limited by the MAXDATALEN attribute of the TCPIPSERVICE definition.
4. Specify any options that you want to set here for code page conversion.
   1. The SERVERCONV option provides overall control of code page conversion. Use it to specify whether or not code page conversion takes place.
      For CICS as an HTTP server, for compatibility with web-aware applications coded in earlier releases, code page conversion is assumed if SERVERCONV is not specified but another code page conversion option is specified. If you want to prevent code page conversion, either specify SERVERCONV(NOSRVCONVERT) or omit all the code page conversion options.

      If you receive an entity body that has been zipped or compressed, as indicated by a Content-Encoding header on the message, make sure that you suppress code page conversion. CICS does not decode these types of message for you, and, if code page conversion is applied, the results might be unpredictable. If you cannot decipher a zipped or compressed entity body, you can inform the web client by returning a 415 status code.

   2. If you want code page conversion, but CICS cannot determine the character set of the web client, use the CHARACTERSET option to specify it.
      For older web clients, the request headers might not provide this information. In this case, CICS assumes the ISO-8859-1 character set, so you only need to specify the character set if that assumption is not correct.
   3. If you want code page conversion, but the default code page for the local CICS region, as specified in the LOCALCCSID system initialization parameter, is not suitable for your application, use the HOSTCODEPAGE option to specify an alternative host code page.
   Code page conversion does not take place for messages that specify a nontext media type, unless you do not specify SERVERCONV, in which case, for compatibility purposes, the media type is not taken into account. Note that for compatibility purposes, CICS deviates from the HTTP/1.1 requirement to default to application/octet-stream if inbound messages do not specify a media type. CICS uses text/plain as the default instead, so that code page conversion can be carried out for the message.
5. If you specified the MAXLENGTH and NOTRUNCATE options, 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 no longer receive a LENGERR response.
   If you receive less than the length requested on the MAXLENGTH option, it might not indicate the end of the data; this situation might arise if CICS must avoid returning a partial character at the end of the data.