Start of change

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.

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 CICS®. For CICS as an HTTP server, the SOCKETCLOSE attribute in the TCPIPSERVICE definition for the port determines how long the Web client has to complete its request send. When this period expires, CICS returns a 408 (Request Timeout) response to the Web client.

If a request message is sent using chunked transfer-coding, CICS assembles the chunks into a single message before passing it to the application. If a series of pipelined requests is sent, CICS 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 CICS Application Programming 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.
    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 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.
    3. 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.
    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. This is the default.
    2. 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, 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.
      Note: 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 could be unpredictable. If you cannot decipher a zipped or compressed entity body, you can inform the Web client of this by returning a 415 status code.
    2. If you want code page conversion, but CICS cannot determine the Web client's character set, 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 non-text 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 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 CICS needs to avoid returning a partial character at the end of the data.
End of change